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

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

الزامات

این راهنما فرض می کند که شما قبلاً با پیکربندی های Connector Community آشنا هستید. برای بازنگری به تعریف پیکربندی از طریق getConfig مراجعه کنید.

نمای کلی

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

رهنمودها

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

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

برای سؤالات پیکربندی که سؤالات بعدی را تعیین می کنند، isDynamic(true) را تنظیم کنید

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

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

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

مثال:

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

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

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

تنظیمات را نمی توان تغییر داد

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

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

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

پارامترهای پویا را نمی توان نادیده گرفت

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

تنظیمات نمونه

کشویی پویا

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

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();
}