Configuration par étapes

La configuration par étapes permet à un connecteur d'insérer dynamiquement sa configuration en fonction des réponses fournies par l'utilisateur. Par exemple, vous pouvez remplir un menu déroulant "Ville" après avoir sélectionné un menu déroulant "État".

Conditions requises

Dans ce guide, nous partons du principe que vous connaissez déjà les configurations des connecteurs de communauté. Consultez la section Définir une configuration via getConfig pour rappel.

Présentation

La configuration par étapes consiste dans Looker Studio à appeler plusieurs fois getConfig() et le connecteur renvoie d'autres questions de configuration à chaque fois. Chaque appel à getConfig() inclut les réponses de l'utilisateur à la dernière réponse getConfig(). Ce processus se poursuit tant que vous renvoyez une réponse avec setIsSteppedConfig(true).

Consignes

Définir setIsSteppedConfig(true) jusqu'à la fin de la configuration

Looker Studio appelle getConfig() à plusieurs reprises tant que setIsSteppedConfig(true) est défini.Une fois la configuration terminée, la réponse getConfig() finale doit définir setIsSteppedConfig(false).

Définir isDynamic(true) pour les questions de configuration qui déterminent les questions suivantes

Si un champ marqué isDynamic est modifié par l'utilisateur, les entrées de configuration suivantes seront effacées de l'interface utilisateur, et l'utilisateur devra configurer toutes les étapes suivantes. Cela permet de garantir que les utilisateurs ne vous envoient pas de configuration non valide.

Les réponses fournies par l'utilisateur seront transmises via request.configParams.

request.configParams sera undefined pour la première requête getConfig() envoyée à votre connecteur. Les requêtes suivantes incluront les réponses fournies par l'utilisateur en tant qu'objet associé aux ID de configuration ou à undefined si l'utilisateur ne fournit aucune réponse.

Exemple :

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

Les configurations se cumulent

Les nouvelles questions de configuration doivent être ajoutées après les questions existantes.

Les configurations ne peuvent pas être modifiées

Si une question de configuration a déjà été posée, elle doit être présente pour tous les appels suivants. Par exemple, si la question de configuration A a été posée lors du premier appel à getConfig(), A doit être incluse dans toutes les réponses futures.

Les configurations sont idempotentes

Les appels à getConfig() avec le même configParams doivent renvoyer la même configuration.

Impossible de remplacer les paramètres dynamiques

Dans Looker Studio, vous ne pouvez pas remplacer les paramètres de configuration dynamique.

Exemples de configurations

Listes déroulantes dynamiques

Cette première question invite l'utilisateur à sélectionner un État, puis fournit de manière dynamique un menu déroulant pour la ville en fonction de l'État sélectionné.

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

Chemins d'embranchement

Une question supplémentaire s'affiche si le pays sélectionné est "États-Unis".

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