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.1 - Exemplo do componente rodando no browser

Principais propriedades

Na tabela abaixo estão descritas as principais propriedades para o funcionamento básico do componente.

Aba de Eventos

Os eventos abaixo possuem características diferentes no componente Caixa de seleção dinâmica.

Valor do campo

A imagem a seguir mostra a janela que é exibida ao abrir a configuração de um evento. Caso o recurso escolhido possua parâmetro, é possível selecionar a opção "Expressão" para o Valor do campo e, ao lado, informar manualmente uma expressão, selecionar o valor (ng-model) de um campo ou Fonte de dados. Contudo, para os eventos Ao Alterar e Ao Selecionar do componente Caixa de seleção Dinâmica existem 3 expressões exclusivas (destaque 1 da figura 1.2).

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

Aba de Estilos

Configuração

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

Figura 2.1 - Janela de configuração

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

Figura 2.2 - 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:

  • Contendo: mostra as opções que contêm a sequência das letras digitadas;

  • Iniciando com: mostra as opções que comecem com a sequência das letras digitadas;

  • Final com: mostra 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.

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

• 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: dependendo do tipo escolhido, o componente se comporta de algumas formas diferentes. Os tipos disponíveis são:
  • Auto completar: funciona de forma semelhante ao componente visual Auto completar dinâmico,
  • Fixo. na forma Fixa o componente é um campo de pesquisa em que as opções só são exibidas no momento que o usuário começa a digitar o texto, exibindo opções ao invés vez de auto completar.

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

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

• Ao iniciar usar valor do primeiro registro: marque essa opção para deixar marcado 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 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.

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 no início da lista de opções exibidas pelo componente.

O conteúdo inserido nessa aba será exibido na área destacada pelo item 3 da figura 2.1.

Figura 2.3 - Adicionando um cabeçalho ao componente

Aba 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 da lista de opções exibidas pelo componente.

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

Figura 2.4 - Adicionando um rodapé ao componente

Aba Elementos

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

Para exibir os atributos dos itens da fonte de dados, use a seguinte notação: #: data.<Campo da Fonte de dados> #. 

Figura 2.5 - Personalização dos elementos da lista

Valores

A aba Valores só será exibida ao marcar como verdadeira a opção Usar Template Personalizado na aba Geral.

Nela podemos definir como será exibido o item selecionado, é possível inserir os atributos dos objetos de forma dinâmica e conteúdo estático, inclusive HTML. O conteúdo inserido nessa aba será exibido na área destacada pelo item 1 da figura 2.1.

Para exibir os atributos dos itens da fonte de dados, use a seguinte notação: #: data.<Campo da Fonte de dados> #. 

Figura 2.6 - Personalização do elemento selecionado