תצורה מדורגת

הגדרה בשלבים מאפשרת למחבר לאכלס באופן דינמי את הגדרת המחבר על סמך תשובות שהמשתמשים מספקים. לדוגמה, מילוי תפריט נפתח של 'עיר' אחרי בחירה בתפריט נפתח של 'מדינה'.

דרישות

במדריך הזה אנחנו יוצאים מנקודת הנחה שאתם כבר מכירים את ההגדרות של מחבר הקהילה. אפשר לקרוא את המאמר הגדרת הגדרות באמצעות getConfig.

סקירה כללית

הגדרה מדורגת מורכבת מכך ש-Data Studio קורא ל-getConfig() מספר פעמים, ובכל פעם המחבר מחזיר עוד שאלות להגדרה. כל קריאה ל-getConfig() תכלול את התשובות של המשתמש לתגובה האחרונה של getConfig(). התהליך הזה נמשך כל עוד מחזירים תגובה עם setIsSteppedConfig(true).

הנחיות

צריך להגדיר את setIsSteppedConfig(true) עד שההגדרה תושלם

‫Data Studio יתקשר שוב ושוב אל getConfig() כל עוד setIsSteppedConfig(true) מוגדר.בסיום ההגדרה, בתגובה הסופית של getConfig() צריך להגדיר את setIsSteppedConfig(false).

הגדרת isDynamic(true) לשאלות הגדרה שקובעות שאלות בהמשך

אם המשתמש משנה שדה שמסומן ב-isDynamic, כל רשומות ההגדרה הבאות יימחקו בממשק המשתמש, והמשתמש יצטרך להגדיר את כל השלבים הבאים. כך תוכלו לוודא שהמשתמשים לא ישלחו לכם הגדרה לא תקינה.

התשובות שהמשתמשים מספקים יועברו באמצעות request.configParams.

התשלום על request.configParams יהיה undefined עבור getConfig() הבקשות הראשונות למחבר. בקשות עוקבות יכללו את התשובות שהמשתמש סיפק כאובייקט עם מפתח לפי מזהי ההגדרות או undefined אם המשתמש לא סיפק תשובות.

דוגמה:

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

ההגדרות האישיות מצטברות

צריך להוסיף שאלות חדשות להגדרות אחרי השאלות הקיימות.

אי אפשר לשנות את ההגדרות

אם הוצגה בעבר שאלה לגבי הגדרה, היא אמורה להופיע בכל הקריאות הבאות. לדוגמה, אם שאלה להגדרה A נשאלה בקריאה הראשונה אל getConfig(), התשובה A צריכה להיכלל בכל התשובות העתידיות.

ההגדרות האישיות הן אידמפוטנטיות

קריאות ל-getConfig() עם אותו configParams צריכות להחזיר את אותה הגדרה.

אי אפשר לשנות פרמטרים דינמיים

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