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 quesetIsSteppedConfig(true)
est défini.Une fois la configuration terminée, la réponsegetConfig()
finale doit définirsetIsSteppedConfig(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
seraundefined
pour la première requêtegetConfig()
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êmeconfigParams
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();
}