Campos dos modelos

Cada campo de um modelo é uma informação que estará presente nele que poderá ser criada, configurada, editada e deletada pelo editor de campos. Essa informação pode ser, dentre outras coisas, uma palavra, uma frase, um número, um texto, uma imagem ou até mesmo um conjunto desses. Quando você requisitar uma entrada específica de um modelo pelas APIs do Starlight, você receberá todos os campos preenchidos daquela entrada num JSON, da forma que você organizou.

Por padrão, o editor de campos tem um grupo de campos chamado de "Informações básicas", que contém dentro dele os campos título e slug. Esses campos são obrigatórios e não podem ser removidos do modelo.

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 iniciais (título e slug) e do grupo 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 ao criar novas entradas e editar existentes.
• Único: Define se os dados desse campo precisam ser diferentes entre as entradas. Campos únicos são obrigatórios por padrão.
• Listável: Define se esse campo deve aparecer em cada entrada de uma listagem desse modelo na API. Por padrão, esse campo está ligado.
• Privado: Define se esse campo não será retornado pela API (mesmo ao requisitar apenas uma entrada específica). Independente disso, ele ainda aparecerá no editor de entradas.
• Arquivado: Define se esse campo ficará escondido durante a edição de entradas. 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).

Nota

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).

Sobre a configuração "Listável"

Por padrão, todos os campos do modelo serão listáveis, isto é, serão retornados ao requisitar uma lista de entradas. Porém, se você como desenvolvedor achar que não utilizará aquele campo ao listar as entradas daquele modelo, então pode desativá-lo (para deixar de receber dados não essenciais para a listagem).

Tipos de campos

Quando introduzimos os campos dos modelos, descrevemos que cada campo poderia conter qualquer tipo de conteúdo (ou até mesmo alguma combinação deles). Abaixo, descreveremos quais são esses tipos e como eles podem ser utilizados:

Título

Campo que contém o nome daquela entrada. É criado automaticamente pelo Starlight ao criar um novo modelo, é um campo obrigatório e não pode ser deletado. Apesar disso, suas configurações de Título e Chave são modificáveis - se for um modelo descrevendo uma pessoa, por exemplo, poderia ser modificado para "Nome".

Slug

Campo que terá um identificador único para aquela entrada. O conceito de slug é melhor explicado na sua própria subseção. Assim como o campo título, é criado automaticamente pelo Starlight ao criar um novo modelo, é um campo obrigatório e não pode ser deletado, mas suas configurações de Título e Chave são modificáveis.

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 subtítulos e descrições de imagens. 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 descrição grande ou um parágrafo em uma postagem de blog. 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.

Editor visual

Campo que representa uma combinação de diversos elementos, sendo eles textos, imagens, vídeos, etc, onde cada um deles pode ser customizado de diversas formas. Pode ser utilizado, por exemplo, como o "corpo" de uma postagem de blog. Por ser um campo importante e difícil de descrever brevemente, explicamos ele em detalhe na sua própria seção.

Arquivo de mídia

Campo que representa uma mídia suportada pelo Starlight, geralmente uma imagem. Quando esse campo for ser preenchido durante a criação de uma nova entrada, o usuário poderá selecionar um arquivo que já foi hospedado naquela organização ou enviar um novo arquivo (que também será hospedado no Starlight para uso futuro, caso necessário).

Campo booleano

Campo que representa uma checkbox cuja entrada teria um valor que poderia ser apenas verdadeiro ou falso, como destacado, verificado, patrocinado, 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).

Cuidado!

Se um campo booleano for configurado como obrigatório, ele deve ser marcado como verdadeiro para uma entrada ser salva.

Relação

Campo que representa a relação com algum outro elemento do Starlight, isto é, uma referência à esse outro elemento. Tem uma configuração extra chamada tipo de relação, que é uma configuração que pode ter 4 valores possíveis:

• any: A relação é com qualquer entrada, singleton ou coleção.
• entry: A relação é com qualquer entrada.
• singleton: A relação é com qualquer singleton.
• collection: A relação é com qualquer coleção.

Se o conteúdo (entrada, singleton ou coleção) que estava presente em uma relação foi deletada, a relação deixará de existir e o campo ficará vazio, mesmo se o campo for obrigatório.

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 modelo (a partir de 1, que é o mínimo). Por padrão, todo modelo tem um grupo de campos inicial chamado de "Informações básicas".