Visão geral do Form Schema

No Catálogo Particular, um tipo de solução compatível são as configurações do Deployment Manager. Para ajudar você a criar e implantar as configurações do Deployment Manager, temos o Form Schema.

O Form Schema é usado para o layout de componentes da interface do usuário (IU) em um formulário HTML. Especificamente, ele permite que os administradores e desenvolvedores da nuvem forneçam uma IU para inserir parâmetros ao criar uma nova instância ou implantação na nuvem.

Os administradores do Cloud podem usar o Form Schema para criar formulários que possibilitam aos usuários personalizar soluções baseadas em modelos do Deployment Manager antes de iniciá-las. Por exemplo, os usuários podem selecionar o tipo de máquina, o tamanho do disco, a zona e o número de CPUs que uma máquina virtual terá. Esses formulários são semelhantes aos usados no Cloud Marketplace.

A seguinte captura de tela ilustra a aparência de um formulário de implantação:

Formulário de implantação

Alternativas ao Form Schema

O Form Schema é uma alternativa à forma atual de criar formulários de IU, chamada metadados de exibição.

Comparado aos metadados de exibição, o Form Schema melhorou a flexibilidade e tem código aberto.

Relação com o JSON Schema

O Form Schema se baseia no formulário de esquema JSON, que é um código aberto escrito em JSON para especificar e validar um conjunto de parâmetros.

O Form Schema faz referência a campos no JSON Schema e herda atributos dele.

É possível incluir o Form Schema dentro do JSON Schema adicionando uma matriz de objetos form entry ao atributo form, conforme ilustrado neste exemplo:

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

Como especificar uma instância do Form Schema

É possível especificar instâncias do Form Schema no formato YAML.

Você cria um arquivo de esquema que coloca os widgets na ordem em que devem aparecer na IU. Esse arquivo de esquema tem a extensão .py ou .jinja, conforme descrito na documentação do Deployment Manager.

Depois, adicione-os a um arquivo em modelo ZIP do Deployment Manager e faça o upload.

Como o Form Schema se encaixa no fluxo de trabalho do Catálogo Particular

Os administradores do Cloud usam o Form Schema com o Catálogo Particular da seguinte forma:

  1. Criar um modelo do Deployment Manager
  2. Especificar um esquema JSON para definir ou validar os campos de entrada que podem ser usados na IU na configuração do modelo do Deployment Manager.
  3. Definir no Form Schema quais campos incluir para uma solução específica e a ordem em que eles aparecerão. Além de organizar, é possível usar o Form Schema para atribuir textos simples aos campos enumerados, como menus suspensos, e agrupar campos com títulos de seção.

Lista de formulários

Uma matriz de objetos form entry. Cada objeto representa um componente da IU em um formulário. Especifique os campos na ordem em que devem aparecer no formulário, independentemente de sua localização no esquema.

Entrada de formulário

Uma entrada de formulário especifica a aparência de um componente de IU em um formulário. Pode ser uma string, que especifica a chave de um campo no JSON Schema, ou um objeto. Quando uma entrada de formulário é uma string, os valores padrão da aparência são herdados da entrada do JSON Schema.

Quando uma entrada de formulário é um objeto, o atributo key refere-se à entrada do JSON Schema. Use um ponto . para separar nós em um valor aninhado. Por exemplo, use name.first para referenciar um campo first dentro de um objeto name. Todos os outros campos são opcionais e, quando especificados, herdam um valor padrão do JSON Schema.

Campos
key*String
Especifica a definição do campo no JSON Schema.
widgetWidget
Especifica o widget da IU a ser usado nesse campo. Padrão: com base no mapeamento do tipo de campo.
titleString
Título do campo. Herda title do esquema.
notitleBoolean
Se o título será ocultado. (Padrão: falso).
descriptionString
Usado como uma dica para o campo. Herda description do esquema.
validationMessageString
Mensagem a ser exibida quando o campo é inválido.
placeholderString
Marcador para o campo. Observação: o Material Design usa title como um marcador.
readonlyBoolean
Se o campo é somente de leitura. Herda readonly do esquema.
conditionString
Uma expressão lógica que determina se o campo será mostrado.
titleMapTitle map
Fornece rótulos de texto para as opções nos widgets checkboxes, radio e select.

* obrigatório.

Processamento especial para tipos

Objeto

Para o tipo object, o campo additionalProperties define se propriedades extras podem ou não estar presentes. O campo pode ter o valor "verdadeiro" (permitir qualquer coisa), "falso" (não são permitidas outras propriedades) ou um esquema JSON que restringe as propriedades adicionais permitidas. Quando o valor é falso ou não está presente, os widgets são exibidos para os campos listados no atributo items. Para outros valores (esquema verdadeiro ou JSON), uma área de texto é exibida para inserir um valor JSON.

Mapeamento tipo-widget

Se nenhum widget for especificado no Form Schema, um valor padrão será usado com base no tipo JSON Schema do campo, da seguinte maneira:

Tipo de esquema Widget do Form Schema
string texto
número number
integer number
Booleano caixa de seleção
objeto fieldset
string + enumeração botão de opção (três ou menos opções)
string + enumeração selecione (quatro ou mais opções)
matriz + enumeração caixas de seleção
matriz matriz

Widget

Um widget é especificado como uma string que se refere a uma das estruturas de dados a seguir.

Array

Uma lista onde é possível adicionar, remover e reordenar as linhas. O JSON Schema permite que a propriedade items do tipo array seja um esquema ou uma lista de esquemas. A lista não é compatível com o Form Schema.

Matrizes com itens primitivos

Como o Form Schema exige que todas as entradas do formulário tenham uma chave, e as matrizes com itens primitivos (não objeto) não têm uma chave para referenciá-las, o formulário deve fazer referência à entrada da matriz primitiva usando uma palavra-chave reservada: "x-googleProperty".

Por exemplo, é possível definir uma matriz de esquema JSON contendo strings da seguinte forma:

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

Deve, portanto, ser referenciado no esquema do formulário como:

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

Matrizes com itens de objeto

As matrizes que contêm objetos precisam especificar cada chave do tipo de item que precisa ser renderizada no formulário.

Por exemplo, considere uma matriz de esquema JSON contendo um objeto:

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

O esquema de formulário necessário para criar uma matriz de formulário com uma entrada para o atributo someArrayItemAttribute seria:

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

Caixa de seleção

Um campo de entrada com o tipo checkbox.

Caixas de seleção

Uma lista de campos de entrada do tipo checkbox. O campo "JSON Schema" deve ser do tipo array e ter um atributo enum. Para fornecer rótulos às opções, especifique um titleMap.

Expandir

Muito parecido com uma seção, mas coloca campos dentro de um widget do painel de expansão que os usuários podem abrir e fechar clicando no título.

Número

Um campo de entrada com o tipo number. Os seguintes atributos do JSON Schema são validadores para o campo: minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf.

Senha

Um campo de entrada com o tipo password.

rádio

Um campo de entrada com o tipo radio. Use isso para campos que tenham uma lista enum no JSON Schema ou que sejam do tipo booleano. Para fornecer rótulos às opções, especifique um titleMap.

Seção

Esse widget agrupa um conjunto de campos. O campo key é ignorado. Uma seção tem um atributo items obrigatório, que é uma matriz de objetos de entrada de formulário. Uma seção pode ter os seguintes atributos opcionais: title, description, condition.

Seleção

Um campo de entrada select. Use isso para campos que tenham uma lista enum no JSON Schema ou que sejam do tipo booleano. Para fornecer rótulos às opções, especifique um titleMap.

Texto

Um widget de entrada com o tipo text. Se o JSON Schema contiver um atributo pattern, o padrão será usado como um validador de regex.

Textarea

Um widget de entrada de área de texto. Esse widget é exibido em algumas situações para inserir JSON diretamente. Consulte objeto.

Mapa de títulos

O atributo titleMap pode ser especificado para widgets do tipo checkboxes, radio e select. Ele é ignorado em outros widgets.

O atributo é uma matriz de objetos que contêm dois atributos, value e name. O atributo value é uma referência a um valor de enumeração para o campo. O atributo name é um texto a ser usado como um rótulo para a opção correspondente no widget da IU. Quando o widget é radio ou checkboxes, um campo description opcional é adicionado como subtexto para esse botão ou caixa de seleção.

Se nenhum titleMap for fornecido, os valores de enum serão usados.

Recursos não suportados

No momento, os seguintes recursos não são compatíveis com o Form Schema:

  • Opções globais
  • Mensagens de validação complexas (somente uma mensagem é compatível)
  • Interpolação da mensagem de validação
  • Funções de mensagem de validação
  • Validação personalizada
  • Widgets não compatíveis: actions, fieldset, radios-inline, radiobuttons, help, template, tab, tabarray
  • Opções não compatíveis: onChange, feedback, disabledSuccessState, disabledErrorState, ngModelOptions, htmlClass, fieldHtmlClass, labelHtmlClass, copyValueTo, destroyStrategy
  • Função pós-processamento
  • Eventos
  • Inserção manual de campo