پیکربندی پلکانی

پیکربندی مرحله‌ای به یک کانکتور اجازه می‌دهد تا پیکربندی کانکتور را بر اساس پاسخ‌های ارائه شده توسط کاربر، به صورت پویا پر کند. به عنوان مثال، پر کردن منوی کشویی "شهر" پس از انتخاب منوی کشویی "استان".

الزامات

این راهنما فرض می‌کند که شما از قبل با پیکربندی‌های Community Connector آشنا هستید. برای آشنایی بیشتر، به بخش define configuration via getConfig مراجعه کنید.

نمای کلی

پیکربندی مرحله‌ای شامل فراخوانی چندین باره تابع getConfig() توسط Data Studio است و کانکتور شما هر بار سوالات پیکربندی بیشتری را برمی‌گرداند. هر فراخوانی getConfig() شامل پاسخ‌های کاربر به آخرین پاسخ getConfig() خواهد بود. این فرآیند تا زمانی که پاسخی با setIsSteppedConfig(true) برگردانید، ادامه می‌یابد.

دستورالعمل‌ها

تا زمانی که پیکربندی کامل شود setIsSteppedConfig(true) را تنظیم کنید.

دیتا استودیو تا زمانی که setIsSteppedConfig(true) تنظیم شده باشد، getConfig() را مکرراً فراخوانی می‌کند. پس از تکمیل پیکربندی، پاسخ نهایی getConfig() باید setIsSteppedConfig(false) را تنظیم کند.

برای سوالات پیکربندی که سوالات بعدی را تعیین می‌کنند isDynamic(true) را تنظیم کنید.

اگر فیلدی که با isDynamic مشخص شده است توسط کاربر تغییر داده شود، ورودی‌های پیکربندی بعدی در رابط کاربری پاک می‌شوند و کاربر باید تمام مراحل بعدی را پیکربندی کند. این به شما اطمینان می‌دهد که کاربران پیکربندی نامعتبری برای شما ارسال نمی‌کنند.

پاسخ‌های ارائه شده توسط کاربر از طریق request.configParams ارسال می‌شوند.

request.configParams برای اولین درخواست getConfig() به کانکتور شما undefined خواهد بود. درخواست‌های بعدی شامل پاسخ‌های ارائه شده توسط کاربر به عنوان یک شیء با کلید شناسه‌های پیکربندی یا undefined در صورتی که کاربر هیچ پاسخی ارائه ندهد، خواهند بود.

مثال:

{
  state: 'CA',
  city: 'mountain_view'
}

پیکربندی‌ها افزایشی هستند

سوالات پیکربندی جدید باید پس از سوالات موجود اضافه شوند.

پیکربندی‌ها قابل تغییر نیستند

اگر قبلاً یک سوال پیکربندی پرسیده شده باشد، باید برای همه فراخوانی‌های بعدی نیز وجود داشته باشد. برای مثال، اگر سوال پیکربندی A در اولین فراخوانی getConfig() پرسیده شده باشد، A باید در تمام پاسخ‌های بعدی گنجانده شود.

پیکربندی‌ها خودتوان هستند

فراخوانی‌های getConfig() با همان configParams باید پیکربندی یکسانی را برگردانند.

پارامترهای پویا قابل لغو نیستند

دیتا استودیو اجازه نمی‌دهد پارامترهای پیکربندی پویا لغو شوند.

پیکربندی‌های نمونه

منوی کشویی پویا

این سوال اول از کاربر می‌خواهد که یک ایالت را انتخاب کند، سپس به صورت پویا یک منوی کشویی از شهر بر اساس ایالت انتخاب شده ارائه می‌دهد.

var cc = DataStudioApp.createCommunityConnector();

function optionsForState(state) {
  switch (state) {
    case "IL": {
      return [["Chicago", "chicago"], ["Springfield", "springfield"]];
    }
    case "CA": {
      return [["Mountain View", "mountain_view"], ["Los Angeles", "los_angeles"]];
    }
    default: {
      cc.newUserError()
          .setText('You must either select "IL" or "CA"')
          .throwException();
    }
  }
}

function getConfig(request) {
  var configParams = request.configParams;
  var isFirstRequest = configParams === undefined;
  var config = cc.getConfig();
  if (isFirstRequest) {
    config.setIsSteppedConfig(true);
  }

  config.newSelectSingle()
      .setId("state")
      .setName("State")
  // Set isDynamic to true so any changes to State will clear the city
  // selections.
      .setIsDynamic(true)
      .addOption(config.newOptionBuilder().setLabel("Illinois").setValue("IL"))
      .addOption(config.newOptionBuilder().setLabel("California").setValue("CA"));

  if (!isFirstRequest) {
    var city = config.newSelectSingle()
        .setId("city")
        .setName("City");
    var cityOptions = optionsForState(configParams.state);
    cityOptions.forEach(function(labelAndValue) {
      var cityLabel = labelAndValue[0];
      var cityValue = labelAndValue[1];
      city.addOption(config.newOptionBuilder().setLabel(cityLabel).setValue(cityValue));
    });
  }
  return config.build();
}

مسیرهای شاخه‌ای

اگر "کشور" انتخاب شده "ایالات متحده آمریکا" باشد، این یک سوال اضافی می‌پرسد.

var cc = DataStudioApp.createCommunityConnector();

function getConfig(request) {
  var configParams = request.configParams;
  var isFirstRequest = configParams === undefined;
  var config = cc.getConfig();
  if (isFirstRequest) {
    config.setIsSteppedConfig(true);
  }

  config
      .newSelectSingle()
      .setId('country')
      .setName('Country')
  // Set isDynamic to true so any changes to Country will clear the state
  // selections.
      .setIsDynamic(true)
      .addOption(config.newOptionBuilder().setLabel('United States').setValue('USA'))
      .addOption(config.newOptionBuilder().setLabel('Canada').setValue('CA'));

  if (!isFirstRequest) {
    // validate a valid value was selected for configParams.country
    if (configParams.country === undefined) {
      cc.newUserError().setText('You must choose a country.').throwException();
    }
    switch (configParams.country) {
      case 'USA': {
        config
            .newSelectSingle()
            .setId('state')
            .setName('State')
            .addOption(config.newOptionBuilder().setLabel('New York').setValue('NY'))
            .addOption(config.newOptionBuilder().setLabel('Calfornia').setValue('CA'));
        break;
      }
      case 'CA': {
        // No additional configuration is needed for Canada.
        break;
      }
      default: {
        cc.newUserError()
            .setText('You must either select "CA" or "USA"')
            .throwException();
      }
    }
  }
  return config.build();
}