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
Na página
Quando aberto no navegador, o campo terá essa aparência:
Ao clicar no ícone de adição (+), a caixa de seleção de itens será aberta, com a seguinte aparência:
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.
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}.
| 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.
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 |