Função

A caixa de seleção fixa é um componente do tipo combobox cujos itens são definidos manualmente nas configurações do componente. É geralmente utilizada em situações que requerem a exibição de uma lista limitada de opções com valores fixos ou a entrada de valores recorrentes. Isso pode ser útil para manter a consistência dos dados no banco de dados ou para simplificar a seleção de opções pelo usuário.

O componente possui um campo de pesquisa que atualiza o filtro a cada caractere informado pelo usuário. 

Figura 1 - Exemplo do componente rodando no browser

É importante destacar que a caixa de seleção fixa não tem relação direta com a fonte de dados, portanto, não interage diretamente com alguns componentes visuais, como a Grade. Para permitir essa interação, será necessário utilizar blocos de programação.

Principais propriedades

Aba de Propriedades

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

Aba de Eventos

Na tabela abaixo estão descritos os eventos disponíveis para o componente.

Aba de Estilos

Na tabela abaixo está descrito o tipo de estilo disponível para o componente.

Configuração

A janela Configuração possui diversas propriedades para personalizar e adicionar novos elementos a Caixa de seleção fixa. 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)

A janela possui 3 abas fixas e mais 1 que é exibida apenas ao habilitar uma opção.

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

Aba Geral

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

Figura 2 - Janela de configuração

• Placeholder: exibe um texto exemplo antes do usuário selecionar uma opção, seu uso é opcional e permite internacionalização.

• Tipo Filtro: define a forma de pesquisa da lista de opções:

  • Contendo: mostra as opções que contêm a sequência de caracteres digitados.

  • Iniciando com: mostra as opções que comecem com a sequência de caracteres digitados.

  • Final com: mostra as opções que terminem com a sequência de caracteres digitados.

• Não permitir seleção fora da lista: quando habilitado, impede que a opção selecionada seja apagada, a menos que a opção vazia do início da lista seja selecionada.
• Botão "+": adiciona um novo item à lista da caixa de seleção fixa.

• Campo Chave: define o identificador dos itens.

• Campo Texto: define o conteúdo que será mostrado na caixa de seleção para o usuário.

1. Editar: abre uma janela para fazer a edição do item.

2. Excluir: exclui o item.

• Usar Template Personalizado: ao selecionar, a aba Elementos é exibida para personalizar o texto listado.

Editar campo

Ao clicar nos botões "+" ou editar de um dos elementos da lista, a janela Adicionar é aberta, permitindo inserir o texto estático e uma chave, que pode ser inclusive dinâmica, obtida por bloco de programação ou campo da tela. (Figura 2.1)

Figura 2.1 - Obtendo a chave do item através de um bloco de programação

Aba Cabeçalho

A aba Cabeçalho permite adicionar texto e conteúdo HTML para ser exibido na caixa de seleção, antes da lista (Figura 2.2).

Figura 2.2 - Inserindo conteúdo no cabeçalho da lista da caixa de seleção

O conteúdo inserido nessa aba será exibido na área destacada pelo destaque 1 da figura 2.3.

Figura 2.3 - Resultado da configuração da figura 2.2

Aba Rodapé

Na aba Rodapé é possível adicionar texto e elementos HTML para incluir no fim da lista.

Figura 2.4 - Inserindo conteúdo no rodapé da lista da caixa de seleção

O conteúdo inserido nessa aba será exibido na área destacada pelo destaque 1 da figura 2.5.

Figura 2.5 - Resultado da configuração da figura 2.4

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 conteúdo estático, além de alguns recursos de HTML e Javascript (high-code). 

A expressão para exibir os dados do campo texto da caixa é: #: data.value # enquanto os dados do campo chave é: #: data.key #. Mas, é possível inserir qualquer caractere antes ou depois dessas expressões. A modificação só ocorre na lista de opção, ao confirmar uma opção o conteúdo personalizado não será exibido.

No exemplo abaixo, listamos o identificador e o nome do usuário, 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 - Utilizando template personalizado

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

Figura 2.7 - Resultado da configuração da figura 2.6

Exemplo de personalização do Template

A aba Elementos permite utilizar elementos de HTML e Javascript (High-code) para manipular os atributos do objeto. Esses elementos podem ser utilizados principalmente quando é 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.

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 4.1). Na figura abaixo vemos um componente Caixa de seleção fixa vinculado a um atributo escrito como data sem personalização de templates na aba Elementos.

Figura 4 - Atributo de data sem a personalização de template

No exemplo abaixo, a aba Elementos está utilizando um if ternário para validar se o atributo de data está nulo, caso esteja, não exibirá nada (''). Caso contrário, data.value será convertido em um objeto Date e formatado como uma data.

Figura 4.1 - Templates usados para o tratamento de datas

O resultado das alterações da figura 4.1 pode ser visto na figura abaixo.

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