Formulário - Campo TagSelector

Visão Geral

TagSelector é um novo tipo de campo que foi adicionado ao Formulário Dinâmico.

O nome “TagSelector” foi utilizado pois ele possibilita selecionar várias “etiquetas” (tags) relacionados a um objeto.

Por exemplo, se estamos desenvolvendo um cadastro de filmes, podemos classificar um único filme com diversos gêneros, tais como suspense, terror e ficção. Ou se estamos desenvolvendo um cadastro de veículos, podemos atribuir diversas características ao veículo, tais como Automático, Conversível e 4 Portas.

E embora este campo tenha sido desenvolvido para este propósito, ele pode muito bem ser usado para outras finalidades. Ele pode por exemplo substituir um campo do tipo ComboBox, e ainda proporcionar alguns recursos adicionais como o suporte a pesquisa e o template de itens.

Aparência

Em modo Design

O campo TagSelector é apresentado da seguinte forma no editor de layout absoluto do Formulário Dinâmico

image

Na página

Quando aberto no navegador, o campo terá essa aparência:
image

Ao clicar no ícone de adição (+), a caixa de seleção de itens será aberta, com a seguinte aparência:

image

Principais Recursos

Seguem abaixo os principais recursos do campo TagSelector.

Procurar

Existe um campo de pesquisa dentro da caixa de seleção de itens do TagSelector. Com ele é possível pesquisar os itens disponíveis para seleção.

Usando a opção Filtro Automático, a pesquisa será executada sempre que um caractere for digitado, respeitando a opção de Comprimento mínimo do filtro.

O Filtro Automático vem habilitado por padrão. Se desabilitado, o filtro será executado quando o usuário digitar Enter.

Fonte de Dados

Assim como nos campos ComboBox e TreeView, é possível carregar os itens de forma desconectada (informando valor + texto fixos) ou conectado ao banco de dados, quando os itens são carregados dinamicamente.

Para carregar os itens do banco de dados, use a propriedade Fonte de Dados.

Quando uma Fonte de Dados for especificada, os Itens (desconectados) serão ignorados.

Carregar Sob Demanda

A propriedade Carregar Sob Demanda faz com que o banco de dados seja acessado apenas quando necessário para obter os itens que serão listados no TagSelector. Do contrário, os itens serão carregados quando a página estiver sendo carregada.

Se a quantidade de registros for pequena, é recomendado manter desabilitada essa opção, para que não seja necessário abrir uma nova conexão com o banco de dados para obter os itens.

Independentemente do estado dessa propriedade, o itens serão carregados apenas uma vez, e serão recarregados quando uma ação Atualizar Fonte de Dados for executada explicitamente através de um Procedimento.

A única exceção é quando a opção Filtro no Servidor estiver habilitada. Neste caso, o banco de dados será acessado a cada operação de filtragem.

Filtro no Servidor

A propriedade Filtro no Servidor é voltada a ganho de performance, nos casos onde a fonte de dados retorna muitos registros.

Quando esta opção estiver habilitada, a pesquisa deve ocorrer diretamente no comando SQL, retornando apenas os registros filtrados.

Para utilizar essa opção, é necessário habilitar também a opção Carregar Sob Demanda, e além disso uma implementação adicional é necessária no comando SQL para fazer o filtro.

Para a implementação do filtro no comando SQL, temos 3 tipos de parâmetros especiais que podemos usar na cláusula Where: {?FILTER SearchText}, {?FILTER Values} e {?FILTER ValuesIN}.

image

Parâmetro Descrição
SearchText É o texto usado na pesquisa.
Values Texto com o valor dos itens selecionados separados pelo Delimitador de Valores configurado. Exemplo: Valor1,Valor2
ValuesIN Lista de Valores formatados para a clausula IN do comando SQL. Exemplo 'Valor1', Valor2'

Estes 3 parâmetros podem ser usados para compor a clausula Where de diversas formas.

Os parâmetro {?FILTER Values} e {?FILTER ValuesIN} são necessário quando um valor está sendo passado explicitamente para o campo, através da ação Popular Campos e Variáveis dos Procedimentos. Neste caso, como precisamos encontrar os registros através do valor e não através do texto, o comando SQL vai procurar apenas os itens solicitados, provavelmente usando a chave primária do registro.

O parâmetro {?FILTER ValuesIN} em específico deve ser testado com as condições de pre-execução de SQL antes de ser utilizado pois e se estiver vazio vai causar um erro no comando SQL, pois a clausula IN ficaria assim:

WHERE campo IN ( )

Segue abaixo o modelo sugerido para implementação do filtro no Comando SQL. Este mesmo modelo é sugerido ao abrir o editor de fonte de dados do campo pela primeira vez:

SELECT 
    codigo, descricao
FROM tabela
WHERE

--#if {?FILTER SearchText}
descricao LIKE '%{?FILTER SearchText}%'

--#else if {?FILTER ValuesIN}
codigo IN ({?FILTER ValuesIN})

--#else
1 = 0

Templates

O campo TagSelector permite a configuração de Templates diferentes para os Itens Selecionados e para os Itens Listados.

image

Valor

O valor do campo TagSelector é representado pela concatenação dos valores dos itens selecionados, separados pelo Delimitador de Valor configurado.

Por exemplo, se os Itens (desconectados) ou a Fonte de Dados tivessem os valores abaixo:

Valor Texto
RS Rio Grande do Sul
SC Santa Catarina
SP São Paulo
RJ Rio de Janeiro

Considerando que as linhas em negrito fossem os itens selecionados, e o Delimitador de Valores fosse “,” (vírgula), o valor do campo seria: SC,SP.

Este formato de valor, serve tanto para a utilização do valor do campo em Comandos SQL e instruções de Procedimentos (get) quando para a atribuição (set).

Por exemplo, se o campo tiver as mesmas configurações do exemplo anterior, e for preenchido com o valor RJ,RS, o resultado seria esse:

Valor Texto
RS Rio Grande do Sul
SC Santa Catarina
SP São Paulo
RJ Rio de Janeiro

Valor Indisponível

Se uma parte do valor passado para o TagSelector não estiver disponível nos Itens (desconectados) Fonte de Dados, ele será simplesmente ignorado.

Por exemplo, se o campo do exemplo anterior fosse preenchido com o valor RS,AM, o resultado seria esse:

Valor Texto
RS Rio Grande do Sul
SC Santa Catarina
SP São Paulo
RJ Rio de Janeiro
1 Curtida

Ficou top, só não ficou claro, ao menos pra mim, como esse campo vai ser retornado no formulário.
Por exemplo, se for salvar as informações no banco de dados, este será retornado como texto, array?

1 Curtida

Olá @daniel.oriques.
Adicionei a explicação de como funciona o valor do campo.
Se ainda tiver algum dúvida, avise.

1 Curtida

Muito interessante, existe alguma previsão para implementação disso nas consultas?

Olá @Gustavo!

Seja bem vindo a nossa comunidade.

Temos planos de implementar este campo na Consulta no futuro, mas ainda não temos nenhuma estimativa do tempo que isso pode levar.

Isso porque o Formulário tem vários recursos que a Consulta não tem, e está mais “preparado” para receber novas funcionalidades.