Personnalisation du volet Paramètres (Guide Professional et Enterprise)

Suite Growth, Professional, Enterprise, and Enterprise Plus professional plan

Nous avons mis à jour les thèmes et l’interface décrits dans cet article. Les clients qui ont activé Guide avant le 14 novembre peuvent mettre à niveau et passer aux nouveaux thèmes.

Quand vous exportez un thème, les fichiers exportés incluent un fichier intitulé manifest.json. Ce fichier définit le volet Paramètres du thème dans Guide.

Cet article décrit le fichier de manifeste et à quoi il peut servir. Vous y trouverez aussi les spécifications. Par exemple, exportez votre thème et ouvrez le fichier manifest.json dans un éditeur de texte.

Sujets couverts :

Le fichier manifest.json
Utilisation des paramètres dans manifest.json comme variables
Modification du fichier manifest.json
Objet Manifest
Objet Setting
Objet Variable
Propriété Type
Type File
Type List
Type Range
Traductions

Le fichier manifest.json

Quand vous exportez un thème, les fichiers exportés incluent un fichier intitulé manifest.json. Vous pouvez utiliser le fichier de manifeste pour définir le volet Paramètres du thème dans Guide.

Vous pouvez modifier les paramètres existants ou en créer de nouveaux. Dans l’exemple suivant, le fichier de manifeste affecte une valeur par défaut de « #30aabc » au paramètre color_brand_text :

"settings": [
  {
    "label": "Colors",
    "variables": [
      {
        "identifier": "color_brand_text",
        "type": "color",
        "description": "color_brand_text_description",
        "label": "color_brand_text_label",
        "value": "#30aabc"
      },
      ...
    ]
  },
  ...
]

Après avoir importé votre thème dans Guide, le paramètre color_brand_text s’affiche dans le volet Paramètres avec le libellé Brand text color (Couleur du texte de la marque), comme spécifié dans la propriété label du fichier de manifeste et la valeur hexadécimale par défaut du sélecteur de couleur est #30aabc, comme spécifié par la propriété value :

Utilisation des paramètres dans manifest.json comme variables

Les paramètres sont aussi appelés variables, car vous pouvez utiliser l’identifiant d’un paramètre comme variable dans les fichiers du thème. Si vous modifiez une valeur dans le volet Paramètres, la valeur est mise à jour dans tous les fichiers qui utilisent cette variable.

Vous pouvez insérer une variable dans le fichier style.css du thème en utilisant la syntaxe $identifier, ou dans un modèle de page en utilisant l’assistant settings.identifier dans Curlybars. Exemples :

style.css

input:focus {
  border: 1px solid $color_brand_text;
}

Vous pouvez aussi utiliser des accolades simples pour incorporer l’assistant dans une expression CSS, comme suit :

max-width: #{$search_width}px;

Modèle de page

<div style="background-color:{{settings.color_brand_text}}">

Modification du fichier manifest.json

Le fichier manifest.json n’est pas inclus dans la liste des fichiers de la page de modification du code du Centre d’aide. Pour modifier le fichier manifest.json, vous devez exporter le thème dans des fichiers, modifier le fichier de manifeste sur votre système, puis importer le thème dans Guide.

Pour exporter le thème

À la page des thèmes, cliquez sur l’icône d’engrenage en bas à droite d’un volet de thème et sélectionnez Exporter.

Pour importer le thème modifié

À la page des thèmes, cliquez sur Importer en haut à droite.

Objet Manifest

L’objet racine du document de manifeste a les propriétés suivantes :

Nom	Type	Commentaire
name	chaîne	Nom du thème
author	chaîne	La personne qui a créé le thème
version	chaîne	La version du thème
api_version	chaîne	La version de l’API du manifeste
settings	tableau	La liste des objets Paramètres. Consultez Objet Setting

Exemple

{
  "name": "My second theme",
  "author": "Jane Doe",
  "version": "1.0.1",
  "api_version": 1,
  "settings": [
    ...
  ]
}

Objet Setting

Les paramètres dans l’objet racine du manifeste et dans le volet Paramètres de Guide sont organisés en groupes, par exemple Couleurs ou Polices. Chaque groupe de paramètre est défini dans le fichier de manifeste par un objet Setting. Chaque objet se compose d’un libellé et d’un ou plusieurs paramètres, comme la couleur de la marque ou la couleur du texte.

Vous pouvez modifier les objets Setting ou en créer de nouveaux. Les objets sont reflétés dans le volet Paramètres du thème quand vous importez le thème dans Guide.

Chaque objet Setting a les propriétés suivantes :

Nom	Type	Commentaire
libellé	chaîne	Le nom de la propriété d’une traduction. Consultez Traductions. Affiche un titre pour un groupe de paramètres.
variables	tableau	La liste des paramètres du groupe. Aussi appelés variables. Consultez Objet Variable.

Exemple

"settings": [
  {
    "label": "colors_group_label",
    "variables": [{...}, ...]
  },
  {
    "label": "fonts_group_label",
    "variables": [{...}, ...]
  },
  {
    "label": "brand_group_label",
    "variables": [{...}, ...]
  },
  {
    "label": "banners_group_label",
    "variables": [{...}, ...]
  }
]

Remarque - La valeur des propriétés "label" sont des noms de propriétés de traduction. Consultez Traductions.

L’exemple crée les catégories suivantes dans le volet Paramètres :

Objet Variable

Chaque objet Setting a un tableau variables qui répertorie les paramètres. On les appelle variables, car vous pouvez les insérer sous la forme de variable dans les modèles du Centre d’aide ou dans le code CSS.

Vous pouvez définir toutes les variables que vous souhaitez. Cependant, le fichier de manifeste doit contenir deux variables de fichier avec les identifiants suivants : logo et favicon. Consultez Variables obligatoires.

Chaque variable a les propriétés suivantes :

Nom	Type	Commentaire
identifier	chaîne	Le nom de variable que vous pouvez utiliser dans les expressions CSS ou Curlybars. Ne doit pas dépasser 30 caractères.
type	chaîne	Le contrôle de l’interface utilisateur dans le volet Paramètres pour obtenir la valeur de l’utilisateur. Soit `text`, `list`, `checkbox`, `color`, `file` ou `range`. Consultez Propriété Type.
libellé	chaîne	Le nom de propriété d’une traduction. Consultez Traductions. Affiche la valeur de la traduction à côté du contrôle de l’interface utilisateur dans le volet Paramètres.
description	chaîne	Le nom de propriété d’une traduction. Consultez Traductions. Affiche la valeur de la traduction sous la forme d’une courte description du paramètre.
valeur	chaîne	La valeur par défaut du paramètre
options	tableau	Pour le type `list` uniquement. Un tableau d’éléments de liste. Consultez Objet Option.
min	entier	Pour le type `range` uniquement. La valeur minimum de la plage.
max	entier	Pour le type `range` uniquement. La valeur maximum de la plage.

Exemple

"variables": [
  {
    "identifier": "color_brand",
    "type": "color",
    "label": "color_brand_label",
    "description": "color_brand_description",
    "value": "#0072EF"
  },
  ...
]

L’exemple crée le libellé et le contrôle suivants dans le volet Paramètres :

Variables obligatoires

Vous devez spécifier les deux variables suivantes dans le fichier de manifeste ou il sera rejeté à l’importation :

logo - identifier doit être « logo » et type doit être « file »
favicon - identifier doit être « favicon » et type doit être « file »

Exemple

"variables": [
  {
    "identifier": "logo",
    "type": "file",
    "description": "logo_description",
    "label": "logo_label"
  },
  {
    "identifier": "favicon",
    "type": "file",
    "description": "favicon_description",
    "label": "favicon_label"
  }
]

Propriété Type

Chaque objet Variable a une propriété type qui spécifie un contrôle d’interface utilisateur pour définir la valeur de paramètre dans le volet Paramètres de Guide. La propriété peut avoir l’une des valeurs suivantes :

text - Champ de saisie de texte.
list - Liste déroulante. Inclut une liste d’objets Option pour les éléments de liste. Consultez Type List.
checkbox - Case à cocher. Consultez Type Checkbox.
color - Sélecteur de couleur.
file - Contrôle de téléchargement de fichiers. Consultez Type File.
range - Champ de saisie de plage. Consultez Type Range.

Exemple

{
  "identifier": "color_headings",
  "type": "color",
  ...
}

Type List

Si le type d’un objet Variable est « list ».l’objet inclut un tableau options pour remplir la liste déroulante. Chaque option dans la liste a les propriétés suivantes :

Nom	Type	Commentaire
libellé	chaîne	Le texte convivial affiché pour l’élément de liste.
valeur	chaîne	La valeur sous-jacente de l’élément de liste.

Vous devez spécifier plus d’une option dans le tableau ou l’importation du thème échouera.

Exemple

{
  "identifier": "font_headings",
  "type": "list",
  "label": "Heading",
  "description": "Font for headings",
  "value": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
  "options": [
    {
      "label": "Arial",
      "value": "Arial, 'Helvetica Neue', Helvetica, sans-serif"
    },
    {
      "label": "Copperplate Light",
      "value": "'Copperplate Light', 'Copperplate Gothic Light', serif"
    },
    {
      "label": "Baskerville",
      "value": "Baskerville, 'Times New Roman', Times, serif"
    }
  ]
}

Type Checkbox

Si le type d’un objet Variable est « checkbox », utilisez la propriété value de l’objet pour spécifier la valeur qui est définie quand l’utilisateur sélectionne la case à cocher. Il doit s’agir d’une valeur booléenne.

Nom	Type	Commentaire
valeur	booléen	`true` ou `false`

Exemple

{
  "identifier": "scoped_hc_search",
  "type": "checkbox",
  "description": "scoped_help_center_search_description",
  "label": "scoped_help_center_search_label",
  "value": true
}

Type File

Un objet Variable avec le type « file » ajoute un contrôle de téléchargement de fichiers dans le volet Paramètres. Ce type de variable n’a pas de propriété value. Exemple :

{
  "identifier": "community_image",
  "type": "file",
  "description": "community_image_description",
  "label": "community_image_label"
}

La valeur est une URL de fichier déterminée par le système.

Vous devez fournir un fichier par défaut que le thème utilisera jusqu’à ce qu’un utilisateur télécharge un autre fichier. Le nom du fichier par défaut doit correspondre à l’identifiant de la variable. Placez le fichier dans le dossier settings dans vos fichiers de thème. Exemple :

Utilisez des variables de fichiers quand des URL sont attendues dans les fichiers de thème. Exemples :

style.css

.community_banner {
    background-image: url($community_image);
}

Modèle de page

<img src="{{settings.community_image}}">

Type Range

Un objet Variable avec le type « range » ajoute un contrôle de curseur dans le volet Paramètres. Exemple :

Une variable de plage inclut des propriétés min et max pour spécifier la plage de valeurs que l’utilisateur peut définir quand il fait glisser le curseur. Les valeurs doivent être des nombres entiers.

Exemple

{
  "identifier": "font_size",
  "type": "range",
  "description": "font_size_description",
  "label": "font_size_label",
  "min": 70,
  "max": 150,
  "value": 100
}

Traductions

Les chaînes visibles du volet Paramètres sont toutes définies dans les traductions. Une traduction se compose d’un nom de propriété et d’une valeur. Exemple :

"text_color_label": "Text color"

Les noms de propriétés sont arbitraires. Vous pouvez spécifier le nom de votre choix.

Les traductions sont stockées dans des fichiers JSON spécifiques à la langue dans le dossier translations du dossier racine du thème :

/ translations
   - en-us.json
   - es.json
   - fr.json
   - ...

Chaque fichier se compose d’un objet JSON avec une liste de traductions :

en-us.json

{
  "brand_color_description": "Brand color for major navigational elements",
  "brand_color_label": "Brand color",
  ...
}

Les traductions servent à spécifier les libellés et les descriptions dans le volet Paramètres.

Pour spécifier des chaînes pour les libellés et les descriptions

Dans le dossier translations, cherchez le fichier JSON pour la langue par défaut de votre Centre d’aide. Exemple : en-us.json.

Mettez à jour les valeurs des propriétés existantes ou ajoutez de nouvelles propriétés. Exemple :

{
  "text_color_label": "Text color",
  "text_color_description": "Text color for body and heading elements",
  ...
}

Dans les variables, utilisez le nom de propriété de la traduction comme valeur des attributs "label" ou "description".
```
"variables": [
  {
    "identifier": "color_text",
    "type": "color",
    "label": "text_color_label",
    "description": "text_color_description",
    "value": "#0072EF"
  },
  ...
]
```
Consultez Objet Variable. Si vous créez une nouvelle propriété ou modifiez le nom d’une propriété existante, n’oubliez pas de mettre vos variables à jour.

Vous pouvez traduire les libellés et les descriptions du volet Paramètres. C’est à vous de fournir les chaînes traduites.

Pour traduire les libellés et les descriptions

Dans le dossier translations, cherchez le fichier JSON pour chaque langue supplémentaire que vous souhaitez prendre en charge.
Copiez les noms des propriétés définies dans votre fichier de traductions par défaut. Exemple :
```
{
  "text_color_description": "",
  "text_color_label": "",
  ...
}
```

Spécifiez une chaîne traduite pour chaque propriété. Exemples :

fr.json

{
  "text_color_description": "Couleur du texte pour les éléments du titre et du corps",
  "text_color_label": "Couleur du texte",
  ...
}

Le fichier manifest.json

Utilisation des paramètres dans manifest.json comme variables

Modification du fichier manifest.json

Objet Manifest

Exemple

Objet Setting

Exemple

Objet Variable

Exemple

Variables obligatoires

Propriété Type

Exemple

Type List

Exemple

Type Checkbox

Exemple

Type File

Type Range

Exemple

Traductions

0 Commentaires

Articles associés