Função

Esse componente faz a seleção de múltiplas opções dentro da uma lista, com isso é possível vincular vários itens a um registro em relacionamentos 1 para N ou N para M. Os itens selecionados aparecerão em labels e estarão destacados em uma cor diferente na lista. Além disso, o seu campo possui um filtro, restringindo sua lista à medida que o usuário digita.

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

Configuração

Arraste o componente para a área do editor visual para abrir a janela de Configurações. Para abrir a janela posteriormente, dê um duplo clique sobre o componente ou clique no botão "..." da propriedade Configurações (Figura 2.1).

Figura 2.1 - Janela de configuração

• Fonte de dados: define o conteúdo que fornecerá os dados para serem as opções do auto completar. Para saber mais sobre como configura uma fonte de dados, acesse o link ao lado: Fonte de dados .

  • "+": adiciona uma fonte de dados.

  • "...": configura uma fonte de dados.

• Placeholder: exibe alguma mensagem enquanto o campo estiver vazio, é possível internacionalizar o conteúdo através do ícone de internacionalização ao final do campo.

• Tipo Filtro: define a forma de filtro:

  • Iniciando com: mostra as opções que comecem com as letras digitadas;

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

  • Final com: mostra as opções que terminam com as letras digitadas.

• Campo Texto: define o atributo que será exibido na caixa de seleção.

• Campo Chave: define o identificador dos itens da lista.

• Fonte relacionada: adiciona a segunda fonte de dados para relacionamentos N para M;

• Campo relacionado: define o atributo da fonte de dados relacionada com o atributo da fonte de dados principal.

• Obter valor do campo como: define o conteúdo da lista retornada, podendo ser:

  • Chave: retorna uma lista com os identificadores dos itens selecionados;

  • Objeto: retorna uma lista com os objetos selecionados - essa é opção padrão.
    

    Observação

    A opção obter valor do campo como só se comportará da maneira descrita quando ele tiver somente uma, e somente uma, fonte de dados vinculada ao componente.

• Usar template personalizado: ao ser selecionado, adiciona a aba Elementos na janela de configuração.

Campos Texto e Chave

O Campo Chave define o conteúdo que será utilizado para identificar o item pelo sistema, enquanto o Campo Texto será o conteúdo associado a essa chave na caixa de seleção múltipla. O retorno desse componente será uma lista dos objetos selecionados pelo usuário.

Abas Cabeçalho e rodapé

As abas cabeçalho e Rodapé permitem adicionar texto e conteúdo HTML para inserir um item no início e no fim da lista. (Figuras 2.2, 2.3 e 2.4)

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

Figura 2.4 - Resultado das configurações nas figuras 2.2 e 2.3

Aba Elementos

Nessa aba é possível personalizar o conteúdo exibido na lista, podendo inserir texto estático ou mais de um atributo. No exemplo da figura 2.5, além da frase que irá se repetir para cada item, foram adicionados dois atributos: nome e login.

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

Figura 2.5 - Utilizando template personalizado

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

Fonte Relacionada

A fonte relacionada só funciona em relacionamentos M para N e tem o objetivo de gerar registros na entidade intermediária no momento de criação da segunda entidade.

Exemplo de uso

Na Figura 2.7, temos as tabelas cliente, produto e uma terceira tabela de relacionamento, pedido_cliente.

Figura 2.7 - Exemplo de modelagem em relacionamento M para N

Durante a criação de um novo cliente (Figura 2.8), podemos ter uma caixa de seleção múltipla para selecionarmos diversos produtos, e após salvar o cliente, os registros relacionados serão salvos automaticamente na tabela pedido_cliente (Figura 2.9). 

Para mais detalhes sobre as configurações de formulários com entidades relacionadas, acesse Relacionamento entre classes no CRUD.

Figura 2.8 - Selecionando os produtos 

Figura 2.9 - Grade da entidade pedido_cliente

No formulário CRUD Cliente, a caixa de seleção múltipla deve estar associada a Fonte de dados do produto, já que ela irá exibir a lista de produtos, a Fonte Relacionada deve estar vinculada a entidade de relacionamento "pedido_cliente" e o Campo Relacionado deve ser o campo que faz relacionamento com a fonte de dados principal na Fonte de dados Relacionada. (Figura 2.10)

Figura 2.10 - Configuração da Caixa de seleção múltipla do formulário cliente