Présentation de Form Schema

Dans Service Catalog, les configurations de Deployment Manager constituent un type de solution compatible. Pour vous aider à créer et à déployer des configurations Deployment Manager, nous vous proposons Form Schema.

Form Schema permet de disposer des composants d'interface utilisateur (UI) dans un formulaire HTML. Plus précisément, il permet aux administrateurs cloud et aux développeurs de fournir une interface utilisateur pour la saisie des paramètres lors de la création d'une instance ou d'un déploiement cloud.

Les administrateurs cloud peuvent utiliser Form Schema pour créer des formulaires permettant aux utilisateurs de personnaliser les solutions basées sur des modèles Deployment Manager avant de lancer les solutions. Par exemple, les utilisateurs peuvent sélectionner le type de machine, la taille du disque, la zone et le nombre de processeurs d'une machine virtuelle. Ces formes ressemblent aux formulaires utilisés dans Cloud Marketplace.

La capture d'écran suivante illustre un formulaire de déploiement :

Alternatives à Form Schema

Form Schema est une alternative à une méthode existante de création de formulaires UI, appelée Display Metadata.

Par rapport à Display Metadata, Form Schema est plus flexible et est Open Source.

Relation avec le schéma JSON

Form Schema s'appuie sur le formulaire de schéma JSON, qui est un schéma Open Source écrit en JSON pour spécifier et valider un ensemble de paramètres.

Form Schema référence les champs du schéma JSON et hérite des attributs de celui-ci.

Vous pouvez inclure Form Schema dans le schéma JSON en incluant un tableau d'objets form entry dans l'attribut form, comme illustré dans l'exemple suivant :

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "type": "object",
      "properties": {...}
      "form": [
        ...Form List goes here...
      ]
    }

Spécifier une instance de Form Schema

Vous pouvez spécifier des instances de Form Schema au format YAML.

Vous créez un fichier de schéma qui expose les widgets d'interface utilisateur dans l'ordre dans lequel ils doivent apparaître dans l'interface utilisateur. Ce fichier de schéma contient l'extension de fichier .py ou .jinja, comme décrit dans la documentation de Deployment Manager.

Vous ajoutez ensuite les fichiers à une archive ZIP du modèle Deployment Manager, puis importez cette archive ZIP.

Intégration de Form Schema dans le workflow Service Catalog

Les administrateurs cloud utilisent Form Schema avec Service Catalog comme suit :

Créer un modèle Deployment Manager
Spécifiez un schéma JSON pour définir ou valider les champs de saisie pouvant être utilisés dans l'interface utilisateur de la configuration du modèle Deployment Manager.
Dans Form Schema, définissez les champs à inclure pour une solution particulière et l'ordre dans lequel ces champs doivent apparaître. En plus du tri, vous pouvez utiliser Form Schema pour fournir un texte convivial pour les champs énumérés, tels que des listes déroulantes et des champs de groupe associés à des titres de section.

Liste de formulaires

Tableau d'objets form entry. Chaque objet représente un composant d'interface utilisateur dans un formulaire. Vous devez spécifier des champs dans l'ordre dans lequel vous souhaitez les afficher dans le formulaire, quel que soit leur emplacement dans le schéma.

Entrée de formulaire

Une entrée de formulaire spécifie l'apparence d'un composant d'interface dans un formulaire. Il peut s'agir d'une chaîne qui spécifie la clé d'un champ du schéma JSON, ou d'un objet. Lorsqu'une entrée de formulaire est une chaîne, les valeurs par défaut de l'apparence sont héritées de l'entrée de schéma JSON.

Lorsqu'une entrée de formulaire est un objet, l'attribut key fait référence à l'entrée de schéma JSON. Utilisez un point . pour séparer les nœuds pour une valeur imbriquée. Par exemple, utilisez name.first pour référencer un champ first dans un objet name. Tous les autres champs sont facultatifs et, le cas échéant, héritent d'une valeur par défaut du schéma JSON.

Champs
`key*`	`String` Spécifie la définition de champ dans le schéma JSON.
`widget`	`Widget` Spécifie le widget d'interface utilisateur à utiliser pour ce champ. Valeur par défaut : basée sur le mappage du type de champ.
`title`	`String` Titre du champ. Hérite de `title` du schéma.
`notitle`	`Boolean` Indique si le titre doit être masqué. Valeur par défaut : "false".
`description`	`String` Utilisé comme indice ou info-bulle pour le champ. Hérite de `description` du schéma.
`validationMessage`	`String` Message à afficher lorsque le champ n'est pas valide.
`placeholder`	`String` Espace réservé pour le champ. Remarque : Material Design utilise `title` comme espace réservé à la place.
`readonly`	`Boolean` Indique si le champ est en lecture seule. Hérite de `readonly` du schéma.
`condition`	`String` Expression logique qui détermine si le champ est affiché ou non.
`titleMap`	`Title map` Fournit des libellés textuels pour les options des widgets `checkboxes`, `radio` et `select`.

* obligatoire.

Traitement spécial des types

Objet

Pour le type object, le champ additionalProperties indique si des propriétés supplémentaires peuvent être présentes ou non. Le champ peut avoir la valeur "true" (autoriser tout), "false" (aucune propriété supplémentaire autorisée) ou un schéma JSON qui limite les propriétés supplémentaires autorisées. Lorsque la valeur est "false" ou manquante, des widgets sont affichés pour les champs répertoriés dans l'attribut items. Pour les autres valeurs ("true" ou schéma JSON), une zone de texte s'affiche pour la saisie d'une valeur JSON.

Mappage type à widget

Si aucun widget n'est spécifié dans Form Schema, une valeur par défaut est utilisée en fonction du type de schéma JSON du champ, comme suit :

Type de schéma	Widget Form Schema
chaîne	texte
nombre	nombre
Entier	nombre
boolean	case à cocher
objet	jeu de champs
chaîne + énumération	radio (3 réponses maximum)
chaîne + énumération	select (4 options ou plus)
tableau + énumération	cases à cocher
tableau	tableau

Un widget est spécifié sous forme de chaîne faisant référence à l'une des structures de données suivantes.

Array

Liste dans laquelle il est possible d'ajouter, de supprimer et de réorganiser des lignes. Le schéma JSON permet à la propriété items du type array d'être un schéma ou une liste de schémas. Cette liste n'est pas compatible avec le Form Schema.

Tableaux contenant des éléments primitifs

Comme le schéma du formulaire nécessite que toutes les entrées du formulaire aient une clé et que les tableaux contenant des éléments primitifs (non objets) ne possèdent pas de clé les référençant, le formulaire doit référencer l'entrée de tableau primitif à l'aide d'un mot clé réservé, "x-googleProperty".

Par exemple, vous définiriez un tableau de schéma JSON contenant des chaînes comme suit :

    {
      'exampleArray': {
        'type': 'array',
        'items': {
          'type': 'string'
        }
      }
    }

Celui-ci serait alors référencé dans le schéma du formulaire comme suit :

    [
      {
        'key': 'exampleArray',
        'widget': 'array',
        'items': [
          {
            'key': 'exampleArray.x-arrayPrimitive'
          }
        ]
      },
    ]

Tableaux contenant des éléments d'objet

Les tableaux contenant des objets doivent spécifier chaque clé du type d'élément qui doit s'afficher dans le formulaire.

Prenons l'exemple d'un tableau de schéma JSON contenant un objet :

    {
      'exampleArray': {
        'type': 'array',
        'items': {
          'type': 'object',
          'properties': {
            'someArrayItemAttribute': {
              'type': 'string'
            }
          }
        }
      }
    }

Le schéma de formulaire requis pour créer un tableau de formulaire avec une entrée pour l'attribut someArrayItemAttribute est le suivant :

    [
      {
        'key': 'exampleArray',
        'widget': 'array',
        'items': [
          {
            'key': 'exampleArray.someArrayItemAttribute'
          }
        ]
      },
    ]

Case à cocher

Champ de saisie de type checkbox.

Cases à cocher

Liste de champs de saisie de type checkbox. Le champ de schéma JSON doit être de type array et comporter un attribut enum. Pour fournir des libellés pour les options, vous pouvez spécifier un titleMap.

Développement

Très similaire à une section, mais place les champs dans un widget de panneau d'expansion que les utilisateurs peuvent ouvrir et fermer en cliquant sur le titre.

Numéro

Champ de saisie de type number. Les attributs suivants du schéma JSON sont des validateurs pour le champ : minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf.

Mot de passe

Champ de saisie de type password.

Signal radio

Champ de saisie de type radio. Utilisez ce champ pour les champs ayant une liste enum dans le schéma JSON ou qui sont de type booléen. Pour fournir des libellés pour les options, vous pouvez spécifier un titleMap.

Section

Ce widget regroupe un ensemble de champs. Le champ key est ignoré. Une section possède un attribut items obligatoire, qui est un tableau d'objets de saisie de formulaire. Une section peut comporter les attributs facultatifs suivants : title, description, condition.

Sélectionner

Champ de saisie select. Utilisez ce champ pour les champs qui ont une liste enum dans le schéma JSON ou qui sont de type booléen. Pour fournir des libellés pour les options, vous pouvez spécifier un titleMap.

Texte

Widget de saisie de type text. Si le schéma JSON contient un attribut pattern, le modèle est utilisé comme validateur d'expression régulière.

Zone de texte

Widget de saisie de zone de texte Ce widget s'affiche dans certains cas pour la saisie directe de JSON. Voir objet.

Carte des titres

L'attribut titleMap peut être spécifié pour les widgets de type checkboxes, radio et select. Il est ignoré dans les autres widgets.

L'attribut est un tableau d'objets contenant deux attributs, value et name. L'attribut value est une référence à une valeur d'énumération pour le champ. L'attribut name correspond au texte à utiliser comme libellé pour l'option correspondante dans le widget d'interface utilisateur. Lorsque le widget est radio ou checkboxes, un champ description facultatif est ajouté en tant que sous-texte pour cette case d'option ou case à cocher.

Si aucun titleMap n'est fourni, les valeurs d'énumération sont utilisées à la place.

Fonctions non compatibles

Les fonctions suivantes ne sont actuellement pas compatibles avec Form Schema :

Options globales
Messages de validation complexes (un seul message est accepté)
Interpolation de messages de validation
Fonctions de message de validation
Validation personnalisée
Widgets non compatibles : actions, fieldset, radios-inline, radiobuttons, help, template, tab, tabarray
Options non compatibles : onChange, feedback, disabledSuccessState, disabledErrorState, ngModelOptions, htmlClass, fieldHtmlClass, labelHtmlClass, copyValueTo, destroyStrategy
Fonction post-traitement
Événements
Insertion manuelle de champ