Présentation du format et du fichier components.json

Format général

Le format général du fichier components.json est le suivant :

• Les propriétés des composants sont indiquées dans chaque composant. Les propriétés "components" ou "apps" de niveau supérieur sont en phase d'abandon.

• Chaque composant possède une propriété "type". Les composants ne peuvent avoir que certaines valeurs (toutes les valeurs possibles sont répertoriées dans le tableau des composants par défaut).

• Chaque composant possède une propriété "id" qui doit être unique. Cette propriété permet de distinguer les composants ayant le même "type". Auparavant, les applications possédaient la propriété "appName". "appName" fonctionne toujours si la propriété "id" n'est pas disponible, mais la propriété "appName" est en phase d'abandon.

• Chaque composant possède une propriété "name" qui correspond au nom d'affichage dans l'interface utilisateur. Si les valeurs de basculement ne sont pas indiquées, la valeur pour les composants est le nom du composant par défaut correspondant, et la valeur pour les composants distants est l'ID.

Voici un exemple de fichier components.json :

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline",
                "name": "My Headline",
                ...
            },
            {
                ...
            },...
        ]
    },
    {
        "name": "My own category name",
        "list": [ ... ]
    }
]

La structure générale est un tableau JSON d'objets de catégorie. Chaque objet de catégorie possède une propriété "name" et une propriété "list". La propriété "name" peut être une clé qui mappe à une chaîne localisée. Si ces catégories par défaut ne sont pas suffisantes, vous pouvez fournir votre propre nom de catégorie, qui ne sera pas localisé. Le tableau suivant répertorie les catégories par défaut disponibles et les clés correspondantes.

La propriété "list" de chaque objet de catégorie contient un tableau d'objets de composant. Chaque composant ou objet doit posséder les propriétés "type" et "id". Les autres propriétés sont facultatives.

• La propriété "type" doit être égale à l'un des types trouvés dans les composants par défaut. Si "type" n'existe pas, le composant ne sera pas affiché.

• La propriété "id" doit être propre à chaque composant. Si "id" existe déjà, le composant ne sera pas affiché.

• La propriété "name" correspond au nom d'affichage du composant dans l'interface utilisateur. Elle remplace l'ancienne propriété "appName" pour les applications (désormais composants distants).

• Toutes les autres propriétés sont traitées de la même façon que dans les autres versions.

Ajout de nouveaux composants à components.json

Vous n'êtes pas autorisé à modifier les composants par défaut. Toutefois, vous pouvez créer un composant à partir d'un composant par défaut existant. Par exemple, vous pouvez créer un composant à partir du composant "scs-title", qui définit un texte par défaut. Pour ajouter un nouveau composant, vous devez au moins indiquer les propriétés "type" et "id".

• "type" doit être égale à l'un des types trouvés dans les composants par défaut. Si "type" n'existe pas, le composant ne sera pas affiché.

• "id" doit être propre à chaque composant. Si "id" existe déjà, le composant ne sera pas affiché.

Voici un exemple de code permettant d'ajouter un nouveau composant de titre. Ce composant sera affiché avec le composant de titre par défaut.

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline"
            }
        ]
    }
]

Voici un exemple de code permettant d'ajouter un nouveau composant de titre avec un nom d'affichage et un texte par défaut.

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline",
                "name": "My Headline",
                "initialData": {
                    "userText": "This is a second title component"
                }
            }
        ]
    }
]

Le composant de titre est créé à partir de toutes les propriétés du composant de titre par défaut qui servent de base et auxquelles sont appliquées des modifications de niveau de thème.

Compatibilité amont

Les fichiers components.json à l'ancien format peuvent encore être lus.

• Fichiers avec des propriétés "components" ou "apps" de niveau supérieur.

• Si le fichier contient une propriété "apps", les composants distants définis par l'utilisateur sous cette propriété sont encore chargés.

• Si le fichier contient une propriété "apps" de niveau supérieur, partez du principe que tous les composants distants répertoriés sous cette propriété sont de type "scs-app".

• Si la propriété "appName" est présente, définissez "id" sur la valeur "appName". Le nom d'affichage est le même que "name", s'il est indiqué, ou bascule vers la valeur "id".