- Created by Deborah Melo de Carvalho, last modified by Igor Andrade on 22/05/2024
Função
Esse componente exibe uma lista de opções obtidas a partir de uma fonte de dados, possui um campo de pesquisa para filtrar seu conteúdo.
Figura 1 - Exemplo do componente rodando no browser
Não é possível utilizar o mesmo componente visual fonte de dados para dois componentes na mesma tela. Se necessário, utilize outro componente fonte de dados e vincule a mesma entidade ou Fonte de dados.
Uso
Abaixo vemos os elementos que compõe o componentes, esses locais podem ser personalizados.
Figura 1.2 - Elementos do componente
- Campo do item selecionado: exibe o elemento selecionado e serve como campo de filtro quando o campo Tipo (configurações) estiver selecionado como "Auto completar".
- Campo de pesquisa: permite filtrar a lista, visível somente quando o campo Tipo (configurações) estiver selecionado como "Fixo".
- Linha vazia, limpa a última seleção.
- Cabeçalho: exibe o conteúdo inserido na aba Cabeçalho (template) da janela de configurações.
- Lista: exibe a lista com o filtro do campo de pesquisa.
- Rodapé: exibe o conteúdo inserido na aba Rodapé (template) da janela de configurações.
Principais propriedades
Aba de Propriedades
Na tabela abaixo estão descritas as principais propriedades para o funcionamento básico do componente.
Nome | Propriedade | Função |
---|---|---|
options | Abre uma janela para personalização do componente. | |
Título | content | Define o rótulo. |
Valor | ng-model | Propriedade Angular que pode ser usada para obter e alimentar o conteúdo pelo bloco de programação. |
Requerido | ng-required | Define que o campo é de preenchimento obrigatório. |
Texto quando requerido | validationMessage | Exibe a mensagem informada ao tentar submeter o formulário com o campo vazio. A propriedade Requerido (ng-required) deve estar configurada com "sim". |
Identificador | id | Atributo que especifica um ID exclusivo para o componente. Por padrão, um ID é gerado automaticamente e atribuído ao componente. |
Desabilitado | ng-disabled | Directiva usada para desabilitar um componente quando a expressão vinculada for verdadeira. |
Texto quando não tem resultado | no-results-message | Texto exibido quando a busca não oferece resultado. Por padrão o texto apresentado é "no data found", mas pode ser alterado. |
Estilo | style | Altera o estilo geral do componente de forma inline. |
Exibir | ng-show | Propriedade Angular usada para exibir ou oculta o componente. |
Repetir | crn-repeat | Propriedade que seleciona uma fonte de dados contida na tela e repete o componente baseado no número de itens dessa fonte de dados. |
Segurança | cronapp-security | Abre a janela de seleção dos grupos com permissões para visualização ou edição. |
Skin | crn-skin | Permite selecionar um skin que afetará apenas o componente selecionado. |
Classes CSS | class | Adiciona classes CSS que já foram criadas. |
Aba de Eventos
Os eventos abaixo possuem constantes específicas que podem ser passadas no argumento do recurso.
Nome | Propriedade | Função |
---|---|---|
Ao Alterar | ng-change | Executa uma ação assim que algo no componente é alterado. |
Ao Selecionar | ng-selected | Executa uma ação assim que selecionar uma opção do componente. |
Aba de Estilos
Nome em português | Nome em inglês | Descrição |
---|---|---|
Caixa de Seleção | Combobox | Estiliza a caixa de seleção. |
Seta | Dropdown | Estiliza a seta do componente. |
Título | Title | Estiliza o título do componente |
Lista de Itens | Item List | Estiliza a lista de itens do componente. |
Item da Lista Hover | Item List Hover | Estiliza o item da lista Hover. |
Item Selecionado | Selected Item | Estiliza o item selecionado. |
Constantes exclusivas dos eventos
Ao selecionar algum recurso com parâmetros nos eventos Ao Alterar ou Ao Selecionar é possível escolher uma das 3 constantes que são exclusivas para esse componente.
Na figura abaixo foi selecionado um bloco de programação que possui um parâmetro (param) no evento Ao Alterar, dessa forma, é possível selecionar a opção "Expressão" para a coluna Valor do campo e, ao lado, selecionar uma das constantes exclusivas (destaque 1 da figura 2).
Figura 2 - Expressões usadas nos eventos Ao Alterar e Ao Selecionar
As expressões exclusivas dos eventos Ao Alterar e Ao Selecionar no componente Caixa de seleção Dinâmica:
- selected: objeto selecionado.
- selectedKey: campo chave do registro selecionado no componente.
- selectedValue: campo texto do registro selecionado no componente.
Para mais informações sobre as expressões comuns aos demais eventos do componente, consulte a documentação Eventos dos componentes visuais.
Configuração
As Configurações possuem diversas propriedades para personalizar e adicionar novos elementos a Caixa de seleção dinâmica. Para abrir a janela de configurações, selecione o componente no editor visual, exibindo suas propriedades no menu lateral, e clique no botão “...” da propriedade Configuração. (Figura 2.1)
A janela possui 3 abas fixas e mais 2 que são exibidas apenas ao habilitar uma opção.
Aba Geral
Possui as principais propriedades da Caixa de seleção dinâmica.
Figura 2.1 - Aba Geral da janela de configurações do componente
Fonte de dados: seleciona ou cria uma fonte de dados para alimentar o componente (Para saber como configura uma fonte de dados, acesse Componente visual fonte de dados):
"+": adiciona uma fonte de dados.
"...": configura uma fonte de dados.
Tipo Filtro: define a forma de filtragem dos dados, podendo ser:
- <Vazio>: remove o campo de pesquisa do componente.
Contendo: ao digitar no campo de pesquisa será mostrada as opções que contêm a sequência das letras digitadas.
Iniciando com: ao digitar no campo de pesquisa será mostrada as opções que comecem com a sequência das letras digitadas.
Final com: ao digitar no campo de pesquisa será mostrada as opções que terminem com a sequência das letras digitadas.
Campo Texto: define o campo da fonte de dados que será exibido no campo de seleção (destaque 1 da figura 2).
- Modificar texto em: permite escolher o Valor (
ng-model
) de outro campo na tela para ser alimentado com opção selecionada pela Caixa de seleção dinâmica, Campo Chave: permite selecionar qualquer atributo do objeto para ser o identificador do registro selecionado, normalmente são utilizados campos de chave primária.
A opção "
_objectKey
" é utilizada para representar o(s) campo(s) chave(s) do objeto. Porém, se a Fonte de dados não possuir nenhum campo definido como chave, a opção "_objectKey
" exibirá uma chave temporária com a concatenação de todos os atributos do registro, separando-os com o símbolo til "~
" (ex.:<atributo1>~<atributo2>~<atributoN>
). Isso pode ocorrer, por exemplo, em Fontes de dados do tipo Bloco de programação alimentada por lista de objetos.Para evitar obter o valor nesse formato, basta selecionar outro atributo do objeto no Campo Chave.
- Tipo: define o formato do campo de pesquisa.
- Auto completar: a área com o campo do item selecionado (destaque 1 da figura 2) também será um campo de pesquisa e uma nova requisição é feita a cada novo caractere informando, redefinindo a lista.
- Fixo. um campo de pesquisa será exibido no começo da lista e uma nova requisição é feita a cada novo caractere informando, redefinindo a lista.
- Máscara ({0:d}): define a forma como serão apresentados os elementos na lista e após a seleção. É possível criar ou selecionar uma máscara da lista.
Esse campo ficará desabilitado ao ativar a opção Usar Template Personalizado. Texto do rótulo: define o conteúdo do campo como a primeira opção (estático) da caixa de seleção. É possível internacionalizá-lo clicando no ícone no final do campo.
Valor do rótulo: define um identificador para o conteúdo inserido no campo Texto do rótulo. É possível internacionalizá-lo clicando no ícone no final do campo. Esse campo ficará desabilitado ao habilitar a opção Permitir valor nulo.
Permitir valor nulo: marcando essa opção, quando o usuário selecionar a opção do campo Texto do rótulo o valor nulo é retornado. O campo Valor do Rótulo fica desabilitado quando essa opção está ativa.
Valor Inicial: informe o identificador de um dos registros para iniciar o componente com o elemento selecionado. Utilizar aspas (ex.: "59a5-11eb-95ba") em identificadores do tipo texto.
Ao iniciar usar valor do primeiro registro: marque essa opção para sempre vir selecionado o primeiro registro da fonte de dados,
Usar valor primitivo: ao marcar (valor padrão), os dados se tornam do tipo primitivo - ou seja, eles deixam de ser representados como objetos. Caso seja desmarcado, o campo do objeto será clonado e o tipo será o mesmo do objeto.
Alterar cursor ao modificar: coloca o cursor do registro selecionado na caixa de seleção dinâmica na fonte de dados.
- Usar Template Personalizado: ao selecionar, as abas Elementos e Valores são exibidas para personalizar, respectivamente, o modo como será exibido os elementos da lista e o modo como será exibido o item selecionado.
O formato da máscara padrão para alguns tipos de atributos, exemplo tipo Date, podem ser afetadas apenas ao marcar ou desmarcar essa opção.
Bloco Obter Valor do Campo
Aba Cabeçalho
Na aba Cabeçalho é possível adicionar texto e elementos HTML para incluir no início da lista de opções.
Figura 2.2 - Adicionando um cabeçalho ao componente
O conteúdo inserido nessa aba será exibido na área destacada pelo item 1 da figura 2.3.
Figura 2.3 - Cabeçalho do componente
Aba Rodapé
Na aba Rodapé é possível adicionar texto e elementos HTML para incluir no fim da lista de opções.
Figura 2.4 - Adicionando um rodapé ao componente
O conteúdo inserido nessa aba será exibido na área destacada pelo item 1 da figura 2.5.
Figura 2.5 - Rodapé do componente
Aba Elementos
A aba Elementos só será exibida ao marcar a opção Usar Template Personalizado na aba Geral. Nela podemos definir como serão exibidos os itens da lista para seleção, é possível inserir tanto atributos do objeto de forma dinâmica quanto conteúdo estático, além de alguns recursos de HTML e Javascript (high-code).
Para exibir os atributos dos itens da fonte de dados, use a seguinte notação: #: data.<Campo da Fonte de dados> #
No exemplo abaixo, listamos o e-mail e o nome de usuário do objeto, porém, no nome de usuário adicionamos uma função Javascript (toUpperCase) para deixar todos os caracteres em maiúsculo.
Veja como manipular os atributos do objeto no tópico Edição do template.
Figura 2.6 - Personalização dos elementos da lista
O conteúdo inserido nessa aba afetará a lista destacada pelo item 1 da figura 2.7.
Figura 2.7 - Elementos da lista
Aba Valores
A aba Valores só será exibida ao marcar a opção Usar Template Personalizado na aba Geral. Nela podemos definir como será exibido o item selecionado, é possível inserir tanto atributos do objeto de forma dinâmica quanto conteúdo estático, além de alguns recursos de HTML e Javascript (high-code).
Para exibir os atributos dos itens da fonte de dados, use a seguinte notação: #: data.<Campo da Fonte de dados> #
.
No exemplo abaixo, listamos o nome e o nome de usuário contido no objeto, porém, no nome de usuário adicionamos tags HTML (<b></b>
) para deixá-lo em negrito.
Veja como manipular os atributos do objeto no tópico Edição do template.
Figura 2.8 - Personalização do elemento selecionado
O conteúdo inserido nessa aba afetará o item 1 da figura 2.9.
Figura 2.9 - Componente com um item selecionado
Exemplo de personalização do Template
As abas Elementos e Valores permitem utilizar elementos de HTML e Javascript (High-code) para manipular os atributos do objeto. Se o objetivo for exibir apenas um atributo personalizado tanto na lista quanto ao selecionar o elemento, provavelmente utilizar o campo Máscara ({0:d}) da aba Geral seja suficiente. No entanto, se for necessário incluir mais de um atributo ou se houver a necessidade de exibir os itens da lista e o item selecionado de maneira distinta, a personalização dos templates pode ser utilizada.
Os métodos Javascript devem ser utilizados com base no tipo do dado do atributo selecionado, por exemplo: Date, String, Number, Boolean etc. Além disso, pode ser necessário utilizar if ternário para tratar valores nulos (Figura 3.1).
Outra alternativa para manipular os atributos exibidos sem utilizar as configurações do componente Caixa de seleção dinâmica é criando um Campo Calculado na Fonte de dados vinculada e, em seguida, selecioná-lo no Campo Texto na aba Geral. Os Campos calculados podem ser alimentados a partir do retorno de uma função de bloco de programação.
Na figura abaixo vemos um componente Caixa de seleção dinâmica vinculado a um atributo do tipo Data sem máscara ou personalização de templates nas abas Elementos e Valores.
Figura 3 - Atributo de data sem a personalização de template
Nos exemplos abaixo, tanto a aba Valores (destaque 1) quanto a aba Elementos (destaque 2) está utilizando um if ternário para validar se o atributo de data está nulo, caso esteja, não exibirá nada (''
).
Figura 3.1 - Templates usados para o tratamento de datas
- Aba Valores: se o atributo for diferente de nulo, utiliza o método toLocaleString para modificar o atributo "
nasc
" para o formato data e hora e, em seguida, obtém os 10 primeiros caracteres com o método substr. - Aba Elementos: se o atributo é diferente de nulo, utiliza o método concat para concatenar o atributo "
nome
" com o atributo "nasc
" que foi formatado utilizando o método toLocaleDateString.
O resultado das alterações da figura 3.1 podem ser vistas na figura abaixo.
Figura 3.2 - Atributo de data com a personalização de template
Nome em inglês
Dynamic Combobox
Nesta página
Compatibilidade
Formulário web
Equivalente mobile
Caixa de seleção dinâmica (mobile)
Botão do Componente
Imagem no Editor Visual
Assista sobre o tema no Cronapp Academy
Caso seja seu primeiro acesso ao Cronapp Academy, crie antes uma conta gratuita e matricule-se no curso abaixo.