Função

O Auto completar é uma funcionalidade da caixa de seleção que filtra as opções à medida que o usuário digita no campo. Esse componente possui valores fixos, ou seja, é necessário inserir manualmente quais são os valores que irão aparecer para completar o campo. 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 sugestões em vez de opções.

Figura 1 - Exemplo do componente personalizado rodando no browser

É importante destacar que o Auto completar 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 Estilos

Na tabela abaixo estão descritos os tipos de estilos disponíveis para o componente Auto Completar.

Configuração

A janela Configuração possui diversas propriedades para personalizar e adicionar novos elementos ao componente. 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

Possui as principais propriedades do componente.

Figura 2 - Janela de configuração

• Placeholder: sugere um exemplo do que pode ser inserido no campo - o ícone ao lado do campo permite internacionalizar o placeholder;

• Tipo Filtro: define a forma como será feita a pesquisa.

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

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

• Campo Texto: são as opções que aparecerão à medida que o usuário digitar na caixa do auto completar.

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

2. Excluir: exclui o item correspondente.

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

Adicionar novo Campo Texto

Clique no botão "+" para abrir a janela Adicionar onde será inserido o novo Campo Texto (Figura 2.1).

Figura 2.1 - Adicionar novo campo texto

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 do componente

O conteúdo inserido nessa aba será exibido na área destacada pelo item 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é do componente

O conteúdo inserido nessa aba será exibido na área destacada pelo item 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 modificação só ocorre na lista de opção, ao confirmar uma opção o conteúdo personalizado não será exibido.

A expressão usada para exibir os dados do campo texto do componente é: #: data.value #, mas é possível inserir qualquer caractere antes ou depois dessa expressão (Figura 2.6).

No exemplo abaixo, listamos o nome do usuário e, nele, 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 item 1 da figura 2.7.

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

Expandir automaticamente

Essa propriedade permite exibir a lista de itens quando o campo de input está em foco.

Figura 3 - Configuração e resultado no browser da propriedade expandir automaticamente

Selecionar primeira opção ao sair

Essa propriedade selecionará o primeiro item da lista quando o usuário clicar fora do componente. 

Figura 3.1 - Configuração e resultado no browser da propriedade
Selecionar primeira opção ao sair 

Texto quando não tem resultado

Essa propriedade exibirá uma mensagem informando que o valor buscado no campo não está contido na lista, geralmente essa mensagem vem por padrão escrita como "No data found", mas é possível configurá-la de modo a exibir qualquer mensagem que o usuário deseje. No exemplo abaixo, configuramos a mensagem para exibir "Resultado não encontrado".

Figura 3.2 - Configuração e resultado no browser da propriedade
Texto quando não tem resultado

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 Auto completar vinculado a um atributo do 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 podem ser vistas na figura abaixo.

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