Pular para o conteúdo principal

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 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 ao criar ou editar entradas.
  • Ú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 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 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 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 caixa de seleção 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 a esse outro elemento. Tem uma configuração extra chamada tipo de relação, que pode ter um dos seguintes valores:

  • any: A relação é com qualquer entrada, Seção ou coleção.
  • entry: A relação é com qualquer entrada.
  • singleton: A relação é com qualquer Seção.
  • collection: A relação é com qualquer coleção.
O que são singletons?

A relação do tipo singleton se refere a uma relação com uma Seção. Seções eram chamadas de "singletons" no passado e, para evitar mudanças drásticas nas APIs atuais, elas ainda se chamam "singletons" nas APIs v1 e v2. Seções serão chamadas de sections a partir da versão 3 das APIs.

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

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