Configuración escalonada

La configuración escalonada permite que un conector rellene dinámicamente su configuración en función de las respuestas proporcionadas por los usuarios. Por ejemplo, puede rellenar el menú desplegable de ciudad después de que el usuario seleccione una opción en el menú desplegable de estado.

Requisitos

En esta guía se da por hecho que estás familiarizado con las configuraciones de los conectores comunitarios. Si quieres revisar la información relacionada, consulta Definir la configuración con getConfig.

Introducción

En la configuración escalonada, Data Studio llama a getConfig() varias veces y tu conector devuelve más preguntas de configuración cada vez. Cada llamada a getConfig() incluirá las respuestas del usuario a la última respuesta de getConfig(). Este proceso persiste siempre y cuando devuelvas una respuesta con setIsSteppedConfig(true).

Directrices

Define setIsSteppedConfig(true) hasta que se complete la configuración

Data Studio llamará repetidamente a getConfig() siempre y cuando setIsSteppedConfig(true) esté definido. Cuando se haya terminado la configuración, la respuesta final de getConfig() debería definir setIsSteppedConfig(false).

Define isDynamic(true) para las preguntas de configuración que determinan las preguntas posteriores

Si el usuario modifica un campo marcado como isDynamic, las entradas de configuración posteriores se borrarán en la UI y el usuario deberá configurar todos los pasos posteriores. De esta manera, te aseguras de que los usuarios solo te envíen configuraciones válidas.

Las respuestas proporcionadas por los usuarios se transferirán a través de request.configParams.

request.configParams será undefined en la primera solicitud getConfig() a tu conector. Las solicitudes posteriores incluirán las respuestas proporcionadas por el usuario como un objeto con la clave de los ID de configuración, o el valor undefined si el usuario no proporciona ninguna respuesta.

Ejemplo:

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

Las configuraciones son acumulativas

Las preguntas de configuración nuevas deben añadirse a las que ya existen.

No es posible alterar las configuraciones

Si se ha hecho una pregunta de configuración anteriormente, debe estar presente en todas las llamadas posteriores. Por ejemplo, si se ha hecho la pregunta de configuración A en la primera llamada a getConfig(), A debería incluirse en todas las respuestas posteriores.

Las configuraciones son idempotentes

Las llamadas a getConfig() con el mismo configParams deberían devolver la misma configuración.

Los parámetros dinámicos no pueden ser anulables

Data Studio no permite que se anulen los parámetros de configuración dinámicos.

Configuraciones de ejemplo

Menús desplegables dinámicos

En esta primera pregunta se solicita al usuario que elija un estado y, a continuación, se proporciona dinámicamente un menú desplegable de ciudad en función del estado seleccionado.

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

Rutas de encabezado

Se hará otra pregunta si el país ("Country") seleccionado es EE. UU. ("USA").

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