الإعداد المرحلي

تسمح عملية "الضبط المتدرج" للموصل بتعبئة إعدادات الموصل ديناميكيًا استنادًا إلى الإجابات التي يقدّمها المستخدم. على سبيل المثال، تعبئة القائمة المنسدلة "المدينة" بعد تحديد القائمة المنسدلة "الولاية".

المتطلّبات

يفترض هذا الدليل أنك على دراية بإعدادات ضبط موصلات المنتدى. راجع تحديد التهيئة عبر getConfig لتنشيط ذاكرتك.

نظرة عامة

تتكوّن عملية الإعداد المفصّلة من طلب في Looker Studio لـ getConfig() عدة مرات، ويعرض الموصل المزيد من أسئلة الضبط في كل مرة. وسيتضمن كل استدعاء إلى getConfig() إجابات المستخدم على رد getConfig() الأخير. وتستمر هذه العملية طالما تم الرد بـ setIsSteppedConfig(true).

الإرشادات

يجب ضبط setIsSteppedConfig(true) إلى أن تكتمل عملية الإعداد.

ستتصل أداة Looker Studio بـ getConfig() بشكل متكرّر طالما تم ضبط setIsSteppedConfig(true).بعد إكمال عملية الضبط، يجب أن يتم ضبط setIsSteppedConfig(false) في استجابة getConfig() النهائية.

ضبط isDynamic(true) لأسئلة الإعدادات التي تحدّد الأسئلة لاحقًا

إذا تم تعديل حقل يحمل علامة isDynamic من قِبل المستخدم، سيتم محو إدخالات الإعدادات اللاحقة في واجهة المستخدم، وسيكون على المستخدم ضبط جميع الخطوات اللاحقة. يساعد ذلك في ضمان عدم إرسال المستخدمين لإعدادات غير صالحة.

يتم تمرير الإجابات المقدَّمة من المستخدم عبر request.configParams.

سيكون "request.configParams" undefined مقابل أول طلب getConfig() من الموصِّل. ستتضمّن الطلبات اللاحقة الإجابات المقدَّمة من المستخدِم كعنصر مرتبط بأرقام تعريف الإعدادات أو 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();
}