$ref() - Campos que Referenciam Outros Campos

Campos construídos com esta palavra-chave são utilizados quando, numa instância, pretendemos fazer referência a uma - e só uma - instância da mesma ou outra definição. Ao ligar uma instância* a outra instância, podemos aceder às propriedades de informação da instância* ligada. Embora uma instância só possa apontar para uma instância, várias instâncias podem fazer referência à mesma instância. Ainda que os campos do tipo $ref apontem normalmente para instâncias de outras definições, pode haver cenários onde seja vantajoso criar uma árvore de instâncias dentro da mesma definição. Neste caso, podemos marcar o campo como $ref dessa definição.

Utilização

$ref(nome_da_definição, query, [Parametros])

O primeiro argumento necessita de ser o nome da definição onde queremos pesquisar, ao passo que o segundo deve consistir no nome da instância específica dessa definição da qual queremos exibir resultados relacionados.

Options:

• nome_da_definição - The name of the definition to pull the data
• query: A query usada para pesquisar na definição

Para saber como pesquisar por referências de instâncias de outras definições em campos construídos com a palavra-chave $ref, leia este artigo

Parâmetro	Descrição
sort	Ordena os resultados por um campo específico em ordem ascendente (asc) ou descendente (desc). Exemplos: [sort:my_field\:asc] ou [sort:my_field\:desc]
size	Limita quantas opções são exibidas de uma vez na lista (default: 5). Exemplo: [size:10])

WARNING

Quando temos uma definição com um campo do tipo $ref que refere uma definição cujo campo $instanceLabel é também um campo do tipo $ref, iremos obter na listagem da definição inicial o valor do campo $ref da definição intermédia, i.e. o id da instância referida da terceira definição. Para obtermos realmente o valor do campo $instanceLabel field da terceira definição, o campo $instanceLabel da segunda definição terá de ser um campo $auto.ref().field() para o campo da terceira definição que queremos exibir na listagem da definição inicial.

Usar Dinâmicamente Valores de Campos nas Queries

É possível definir uma query de um $ref() utilizando dinâmicamente o valor de outro campo da instância atual.

Para referenciar outro campo, utiliza-se a seguinte sintaxe: __NomeDoCampo__, onde NomeDoCampo é o nome do campo cujo valor queremos usar na query.

WARNING

Notas Importantes

• O nome do campo tem de ser escrito exatamente como definido.
• A sintaxe requer duplos underscores antes e depois do nome do campo.
• A substituição do valor acontece antes de a query ser executada (no frontend).
• Se o campo referenciados não tem valor, o placeholder NomeDoCampo não será substituído. A query pode não funcionar como pretendido.

Exemplos

Exemplo base

No exemplo seguinte estamos a utilizar a expressão $ref(Countries,*) de forma a que os utilizadores possam procurar por valores de campo em todas as instâncias da definição Countries.

Para identificar campos do tipo $ref, basta procurar por qualquer campo acompanhado do seu lado direito por uma lupa. Estes campos permitem-lhe procurar por instâncias de outra definição:

Se pretende saber como construir campos de definição com a palavra-chave $ref, consulte o vídeo incluído em baixo

Com Valores de Campos Dinâmicos - Exemplo

$ref(orders, client_name:__name__ country:__country__)

Isto irá:

• Filtrar encomendas com os valores dos campos name e country