Campos dos formulários
Cada campo de um formulário é uma informação que estará presente nele que poderá ser criada, configurada, editada e deletada pelo editor de campos. Atualmente, essa informação pode ser textual ou booleana (isto é, verdadeira ou falsa). Quando você requisitar um envio específico de um formulário pelas APIs do Starlight, você receberá os campos preenchidos daquele envio num JSON, da forma que você organizou.
Por padrão, o editor de campos tem um grupo de campos vazio chamado de "Informações básicas". Para criar um campo, basta arrastá-lo do menu à direita do editor de campos para o espaço logo à esquerda, dentro de algum grupo de campos.
Configurações dos campos
Quando você cria um campo ou clica no ícone de engrenagem na extremidade direita de um campo, aparecerá um painel com as configurações daquele campo (ou grupo de campos). Por meio desse painel, você pode editar as características do campo da forma que quiser, e todos os campos com exceção dos grupos de campos têm as mesmas configurações em comum:
- Título: Identificador do campo. Não é retornado pela API, é apenas visual.
- Chave: Uma espécie de slug do campo, que será referenciado pela API. Será gerado automaticamente a partir do título, mas pode ser editado.
- Obrigatório: Define se é obrigatório ou não preencher esse campo para criar um envio.
- Único: Define se o valor do campo precisa ser único entre todos os envios. Campos únicos são obrigatórios por padrão.
- Listável: Define se esse campo deve aparecer em cada envio de uma listagem desse formulário na API. Por padrão, esse campo está ligado.
- Privado: Define se esse campo não será retornado pela API (mesmo ao requisitar apenas um envio específico). Independente disso, ele ainda aparecerá no editor de formulário.
- Arquivado: Define se esse campo ficará escondido durante a edição de envios. Essa configuração é utilizada para denotar campos deprecados, que tinham algum uso antigo, mas se tornaram desnecessários (mas ainda podem ou não ter suporte na sua aplicação).
Nos exemplos desse guia, chaves e slugs são escritos em inglês. Isso não é obrigatório, mas é recomendado para evitar escrever palavras em português em código-fonte (que geralmente é escrito em inglês).
Por padrão, todos os campos do modelo serão listáveis, isto é, serão retornados ao requisitar uma lista de envios. Porém, se você como desenvolvedor achar que não utilizará aquele campo ao listar os envios daquele formulário, então pode desativá-lo (para deixar de receber dados não essenciais para a listagem).
Tipos de campos
Quando introduzimos os campos dos formulários, descrevemos que cada campo poderia conter apenas conteúdo textual ou booleano. Abaixo, descreveremos quais são esses tipos de campos e como eles podem ser utilizados:
Texto simples
Campo que representa um pequeno fragmento de texto, algo que caiba em uma ou duas linhas (apesar de que o campo em si não limita isso). Dois exemplos de uso seriam o e-mail ou o nome do usuário. Esse campo contém 2 configurações extras:
- Mínimo de caracteres: Quantidade mínima de caracteres para o campo ser validado. Por padrão é 0.
- Máximo de caracteres: Quantidade máxima de caracteres para o campo ser validado. Por padrão é 1000.
Caixa de texto
Campo que representa um texto médio ou grande, algo que caiba em várias linhas, como um ou mais parágrafos. Pode ser utilizado, por exemplo, para ser alguma mensagem de ajuda ou sugestão. Esse campo contém as mesmas 2 configurações extras do campo de texto simples - a única diferença é que o padrão do máximo de caracteres é 5000.
Campo booleano
Campo que representa uma caixa de seleção cuja entrada teria um valor que poderia ser apenas verdadeiro ou falso, como destacado, verificado, ligado, etc. O "booleano" do nome representa simplesmente um tipo de dado que pode ter apenas um dentre 2 valores (1 ou 0, verdadeiro ou falso, ligado ou desligado, etc).
Se um campo booleano for configurado como obrigatório, ele deve ser marcado como verdadeiro para um envio ser validado.
Grupo de campos
Um grupo de campos não é um campo em si, mas é uma maneira de organizar os campos anteriormente citados. Eles existem simplesmente pelo fator organizacional, e você pode usar quantos quiser no seu formulário (a partir de 1, que é o mínimo). Por padrão, todo formulário tem um grupo de campos inicial chamado de "Informações básicas".