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.

Image Added

Figura 1 - Exemplo do componente rodando no browser

Image Removed

Uso

Abaixo vemos os elementos que compõe o componentes, esses locais podem ser personalizados.

Image Added

Figura 1.1 2 - Exemplo do componente rodando no browserElementos 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.

Aba de Eventos

Os eventos abaixo possuem constantes específicas que podem ser passadas no argumento do recurso.

Aba de Estilos

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

Image Added

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.

Configuração

A janela Configuração possui 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.21)

Image Removed

Figura 2.1 - Janela de configuração

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
6. Campo do item selecionado: exibe o elemento selecionado;
7. Campo de pesquisa: permite filtrar a lista;
8. Linha vazia, limpa a última seleção;
9. Cabeçalho: exibe o conteúdo inserido na aba Cabeçalho da janela de configurações;
10. Lista: exibe a lista com o filtro do campo de pesquisa;
11. Rodapé: exibe o conteúdo inserido na aba Rodapé da janela de configurações.

Aba Geral

Possui as principais propriedades da Caixa de seleção fixa.Ao solicitar o valor do campo da Caixa de seleção dinâmica, sempre será retornado o identificador do elemento selecionado.

Image RemovedImage Added

Figura 2.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 mais sobre como configura uma fonte de dados, acesse o link ao lado: Fonte de Dadosacesse 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: mostra ao digitar no campo de pesquisa será mostrada as opções que contêm a sequência das letras digitadas;.

  • Iniciando com: mostra ao digitar no campo de pesquisa será mostrada as opções que comecem com a sequência das letras digitadas;.

  • Final com: mostra 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 para o usuário;no campo de seleção (destaque 1 da figura 2).

• Modificar texto em: modifica outro componente na tela com o conteúdo do Campo Texto;

• Campo Chave: define o identificador de retorno do campo Texto selecionado pelo usuário;

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

  Informações

  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 PersonalizadoMáscara: define a forma como será apresentado o valor. Selecione uma máscara pronta ou crie uma.

• 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: determina qual será a primeira opção apresentada na caixa de seleção, antes de mostrar todas as opções. Esse campo fica disponível quando a opção ao iniciar usar valor do primeiro registro não está marcada. Sua determinação fica a critério do usuário, que pode utilizar blocos de programação, expressão ou o campo de tela;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 deixar marcado 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 no banco 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.

Aba Cabeçalho

Na aba Cabeçalho é possível adicionar texto ou elementos HTML - podendo ser de parágrafo, imagem, entre outros - e, assim, criar uma área e elementos HTML para incluir no início da lista de opções exibidas pelo componente..

Image Added

Figura 2.2 - Adicionando um cabeçalho ao componente

O conteúdo inserido nessa aba será exibido na área destacada pelo item

3

1 da figura 2.

1

3.

Image Removed

Image Added

Figura 2.3 - Adicionando um cabeçalho ao componenteCabeçalho do componente

Âncora
abaRodape abaRodape

Aba

rodapé

Rodapé

Na aba Rodapé é possível adicionar texto

ou HTML - podendo ser de parágrafo, imagem, entre outros - e, assim, criar uma área no final

e elementos HTML para incluir no fim da lista de opções

exibidas pelo componente.

.

Image Added

Figura 2.4 - Adicionando um rodapé ao componente

O conteúdo inserido nessa aba será exibido na área destacada pelo item 6 da figura 1 da figura 2.15.

Image RemovedImage Added

Figura 2.4 - Adicionando um rodapé ao 5 - Rodapé do componente

Âncora
abaElementos abaElementos

Aba Elementos

A aba Elementos só será exibida ao selecionar marcar a opção 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 os tanto atributos dos objetos do objeto de forma dinâmica e quanto conteúdo estático, inclusive HTML. O conteúdo inserido nessa aba será exibido na área destacada pelo item 5 da figura 2.1.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.

Image AddedImage Removed

Figura 2.5 6 - Personalização dos elementos da lista

O conteúdo inserido nessa aba afetará a lista destacada pelo item 1 da figura 2.7.

Image Added

Figura 2.7 - Elementos da lista

Âncora
abaValores abaValores

Aba Valores

A aba Valores só será exibida ao selecionar marcar a opção opção Usar Template Personalizado na aba Geral. Nela podemos definir como será exibido o item selecionado, é possível inserir os tanto atributos dos objetos do objeto de forma dinâmica e quanto conteúdo estático, inclusive HTML. O conteúdo inserido nessa aba será exibido na área destacada pelo item 1 da figura 2.1.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.

Image AddedImage Removed

Figura 2.6 8 - Personalização do elemento selecionado

O conteúdo inserido nessa aba afetará o item 1 da figura 2.9.

Image Added

Figura 2.9 - Componente com um item selecionado

Âncora
exemploPersonalizacaoDoTemplate exemploPersonalizacaoDoTemplate

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

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

Image Added

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

Image Added

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.

Image Added

Figura 3.2 - Atributo de data com a personalização de template