Vista geral do esquema de formulários

No catálogo de serviços, um tipo de solução suportada são as configurações do Deployment Manager. Para ajudar a criar e implementar configurações do Deployment Manager, temos o esquema de formulário.

O esquema de formulário é usado para estruturar componentes da interface do utilizador (IU) num formulário HTML. Especificamente, permite que os administradores e os programadores da nuvem forneçam uma IU para introduzir parâmetros quando criam uma nova instância ou implementação na nuvem.

Os administradores da nuvem usam o esquema de formulário para criar formulários que permitem aos utilizadores personalizar as soluções baseadas em modelos do Deployment Manager antes de lançar as soluções. Por exemplo, os utilizadores podem selecionar o tipo de máquina, o tamanho do disco, a zona e o número de CPUs que uma máquina virtual vai ter. Estes formulários são semelhantes aos formulários usados no Cloud Marketplace.

A captura de ecrã seguinte ilustra o aspeto de um formulário de implementação:

Alternativas ao esquema de formulário

O esquema de formulário é uma alternativa a uma forma existente de criar formulários de IU, denominada metadados de visualização.

Em comparação com os metadados de visualização, o esquema de formulário tem uma flexibilidade melhorada e é de código aberto.

Relação com o esquema JSON

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

O esquema de formulário faz referência a campos no esquema JSON e herda atributos do mesmo.

Pode incluir o esquema do formulário no esquema JSON, incluindo uma matriz de objetos form entry no atributo form, conforme ilustrado no exemplo seguinte:

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

Como especificar uma instância do esquema de formulário

Pode especificar instâncias do esquema de formulários no formato YAML.

Cria um ficheiro de esquema que apresenta os widgets da IU na ordem em que devem aparecer na IU. Este ficheiro de esquema tem a extensão de ficheiro .py ou .jinja, conforme descrito na documentação do Deployment Manager.

Em seguida, adicione os ficheiros a um arquivo zip de modelo do Deployment Manager e carregue o arquivo zip.

Como o esquema de formulário se enquadra no fluxo de trabalho do catálogo de serviços

Os administradores da nuvem usam o esquema de formulário com o catálogo de serviços da seguinte forma:

1. Crie um modelo do Deployment Manager.
2. Especifique um esquema JSON para definir ou validar que campos de entrada podem ser usados na IU para a configuração do modelo do Deployment Manager.
3. Defina no esquema do formulário os campos a incluir para uma solução específica e a ordem pela qual esses campos devem aparecer. Além de ordenar, pode usar o esquema de formulário para fornecer texto simples para campos enumerados, como menus pendentes, e agrupar campos com títulos de secções.

Lista de formulários

Uma matriz de objetos form entry. Cada objeto representa um componente da IU num formulário. Deve especificar os campos pela ordem em que quer que sejam apresentados no formulário, independentemente da respetiva localização no esquema.

Entrada de formulário

Uma entrada de formulário especifica o aspeto de um componente da IU num formulário. Pode ser uma string, onde especifica a chave de um campo no esquema JSON, ou um objeto. Quando uma entrada de formulário é uma string, os valores predefinidos para o aspeto são herdados da entrada do esquema JSON.

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

Campos
key*	String Especifica a definição do campo no esquema JSON.
widget	Widget Especifica o widget da IU a usar para este campo. Predefinição: com base no mapeamento do tipo de campo.
title	String Título do campo. Herda title do esquema.
notitle	Boolean Se o título deve ser ocultado. Predefinição: falso.
description	String Usado como sugestão ou dica de ferramenta para o campo. Herda description do esquema.
validationMessage	String Mensagem a apresentar quando o campo é inválido.
placeholder	String Marcador de posição para o campo. Nota: o Material Design usa title como marcador de posição.
readonly	Boolean Indica se o campo é só de leitura. Herda readonly do esquema.
condition	String Uma expressão lógica que determina se o campo é apresentado.
titleMap	Title map Fornece etiquetas 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 podem ou não estar presentes propriedades adicionais. O campo pode ter um valor verdadeiro (permitir tudo), falso (não são permitidas propriedades adicionais) ou algum esquema JSON que restrinja as propriedades adicionais permitidas. Quando o valor é falso ou não está presente, os widgets são apresentados para os campos indicados no atributo items. Para outros valores (verdadeiro ou esquema JSON), é apresentado um campo de texto para introduzir um valor JSON.

Mapeamento de tipo para widget

Se não for especificado nenhum widget no esquema de formulário, é usado um valor predefinido com base no tipo de esquema JSON do campo, da seguinte forma:

Tipo de esquema	Widget de formulário de esquema
de string	texto
número	number
número inteiro	number
booleano	caixa de verificação
objeto	fieldset
string + enum	rádio (3 ou menos opções)
string + enum	selecionar (4 ou mais opções)
matriz + enumeração	caixas de verificação
matriz	array

Widget

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

Matriz

Uma lista onde as linhas podem ser adicionadas, removidas e reordenadas. O esquema JSON permite que a propriedade items para o tipo array seja um esquema ou uma lista de esquemas. A lista não é suportada pelo esquema de formulário.

Matrizes com itens primitivos

Uma vez que o esquema do formulário requer que todas as entradas do formulário tenham uma chave e as matrizes que contêm itens primitivos (não objetos) não têm uma chave para lhes fazer referência, o formulário deve fazer referência à entrada da matriz primitiva através de uma palavra-chave reservada: "x-googleProperty".

Por exemplo, definiria uma matriz de esquemas JSON que contivesse strings da seguinte forma:

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

Deve ser referenciado no esquema do formulário como:

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

Matrizes com itens de objetos

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

Por exemplo, considere uma matriz de esquema JSON que contenha 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ários com uma entrada para o atributo someArrayItemAttribute seria:

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

Caixa de verificação

Um campo de entrada com o tipo checkbox.

Caixas de verificaçã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 etiquetas para as opções, pode especificar um titleMap.

Expander

Muito semelhante a uma secção, mas coloca os campos num widget de painel de expansão que os utilizadores podem abrir e fechar clicando no título.

Número

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

Palavra-passe

Um campo de entrada com o tipo password.

Rádio

Um campo de entrada com o tipo radio. Use isto para campos que tenham uma enum lista no esquema JSON ou que sejam do tipo booleano. Para fornecer etiquetas para as opções, pode especificar um titleMap.

Secção

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

Selecionar

Um campo de entrada do select. Use isto para campos que tenham uma lista enum no esquema JSON ou que sejam do tipo booleano. Para fornecer etiquetas para as opções, pode especificar um titleMap.

Texto

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

Textarea

Um widget de entrada da área de texto. Este widget é apresentado em algumas situações para introduzir JSON diretamente. Consulte o objeto.

Mapa de títulos

O atributo titleMap pode ser especificado para widgets do tipo checkboxes, radio e select. É ignorado para 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 enum para o campo. O atributo name é texto a usar como etiqueta para a opção correspondente no widget da IU. Quando o widget é radio ou checkboxes, é adicionado um campo description opcional como texto secundário para esse botão de opção ou caixa de verificação.

Se não for fornecido nenhum titleMap, são usados os valores de enumeração.

Funcionalidades não suportadas

As seguintes funcionalidades não são atualmente suportadas no esquema de formulários:

• Opções globais
• Mensagens de validação complexas (apenas é suportada uma mensagem)
• Interpolação de mensagens de validação
• Funções de mensagens de validação
• Validação personalizada
• Widgets não suportados: actions, fieldset, radios-inline, radiobuttons, help, template, tab e tabarray
• Opções não suportadas: onChange, feedback, disabledSuccessState, disabledErrorState, ngModelOptions, htmlClass, fieldHtmlClass, labelHtmlClass, copyValueTo e destroyStrategy
• Função de pós-processamento
• Eventos
• Inserção manual de campos