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


  1. 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".
  2. Campo de pesquisa: permite filtrar a lista, visível somente quando o campo Tipo (configurações) estiver selecionado como "Fixo".
  3. Linha vazia, limpa a última seleção.
  4. Cabeçalho: exibe o conteúdo inserido na aba Cabeçalho (template) da janela de configurações.
  5. Lista: exibe a lista com o filtro do campo de pesquisa.
  6. 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

Configuraçã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 requeridovalidationMessageExibe 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.

Desabilitadong-disabledDirectiva usada para desabilitar um componente quando a expressão vinculada for verdadeira.
Texto quando não tem resultadono-results-messageTexto exibido quando a busca não oferece resultado. Por padrão o texto apresentado é "no data found", mas pode ser alterado.
EstilostyleAltera o estilo geral do componente de forma inline.

Exibir

ng-show

Propriedade Angular usada para exibir ou oculta o componente.

Repetircrn-repeatPropriedade 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.

Skincrn-skinPermite 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.

NomePropriedadeFunçã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êsNome em inglêsDescriçã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.

  1. Aba Geral
  2. Aba Cabeçalho
  3. Aba Rodapé
  4. Aba Elementos
  5. Aba Valores


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

É possível utilizar o bloco de programação Obter Valor do Campo (Cliente ou Servidor) para conseguir o elemento selecionado pelo usuário na Caixa de seleção dinâmica. O retorno do bloco será sempre o atributo selecionado no campo Campo Chave.

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


  1. 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.
  2. 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.