Configurazione con passaggi

La configurazione a passaggi consente a un connettore di compilare dinamicamente la configurazione del connettore in base alle risposte fornite dall'utente. Ad esempio, compilare un menu a discesa "Città" dopo aver selezionato un menu a discesa "Stato".

Requisiti

Questa guida presuppone che tu abbia già familiarità con le configurazioni dei connettori della community. Per un ripasso, consulta Definire la configurazione tramite getConfig.

Panoramica

La configurazione a passaggi prevede che Data Studio chiami getConfig() più volte e che il connettore restituisca ogni volta altre domande di configurazione. Ogni chiamata a getConfig() includerà le risposte dell'utente all'ultima risposta getConfig(). Questo processo continua finché non restituisci una risposta con setIsSteppedConfig(true).

Linee guida

Imposta setIsSteppedConfig(true) finché la configurazione non è completa

Data Studio chiamerà ripetutamente getConfig() finché setIsSteppedConfig(true) non sarà impostato.Una volta completata la configurazione, la risposta finale getConfig() deve impostare setIsSteppedConfig(false).

Imposta isDynamic(true) per le domande di configurazione che determinano le domande successive

Se un utente modifica un campo contrassegnato con isDynamic, le voci di configurazione successive verranno cancellate nell'interfaccia utente e l'utente dovrà configurare tutti i passaggi successivi. In questo modo, gli utenti non ti invieranno una configurazione non valida.

Le risposte fornite dall'utente verranno trasmesse tramite request.configParams.

request.configParams sarà undefined per la prima richiesta getConfig() al connettore. Le richieste successive includeranno le risposte fornite dall'utente come oggetto con chiave in base agli ID di configurazione o undefined se l'utente non fornisce risposte.

Esempio:

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

Le configurazioni sono additive

Le nuove domande di configurazione devono essere aggiunte dopo quelle esistenti.

Le configurazioni non possono essere modificate

Se una domanda di configurazione è stata posta in precedenza, deve essere presente per tutte le chiamate successive. Ad esempio, se la domanda di configurazione A è stata posta nella prima chiamata a getConfig(), A deve essere inclusa in tutte le risposte future.

Le configurazioni sono idempotenti

Le chiamate a getConfig() con gli stessi configParams devono restituire la stessa configurazione.

I parametri dinamici non possono essere sottoposti a override

Data Studio non consentirà di eseguire l'override dei parametri di configurazione dinamici overridden.

Esempi di configurazioni

Menu a discesa dinamici

La prima domanda chiede all'utente di selezionare uno stato, quindi fornisce dinamicamente un menu a discesa della città in base allo stato selezionato.

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

Percorsi di ramificazione

Se il "Paese" selezionato è "USA", verrà posta una domanda aggiuntiva.

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