O campo de pesquisa (ou campo zoom) é uma ferramenta poderosa para otimizar a seleção e visualização de dados em formulários. Com um simples campo, o usuário passa a ter acesso à dados de uma forma ágil, podendo filtrar e selecionar valores de outros componentes e formulários do Fluig ou mesmo de aplicativos externos através de Datasets.

Nesta documentação

Pré-requisitos

Essa documentação é indicada para desenvolvedores familiarizados com html e javascript, e com o uso de Datasets no Fluig.

Sintaxe

<input type="zoom" id="campo" name="campo" data-zoom="...">

<input type="zoom" id="campo" name="campo" zoomvalue="campoIdDoDataset" data-zoom="...">

Atributo data-zoom

O atributo data-zoom é onde a maior parte das configurações possíveis para o campo pesquisa são feitas. Ele é um objeto complexo onde é definido qual o dataset, qual campo deste dataset será usado para preencher o campo, se permite mais de uma item selecionado e quais os campos podem ser usados de filtro.

Sintaxe do data-zoom

{
 	'datasetId':'colleague',
    'displayKey':'colleagueName',
    'placeholder': 'Selecione o usuário do Fluig',
    'filterValues': 'campo1,valorDoCampo1,campo2,valorDoCampo2',
 	'fields':[{
		'field': 'colleagueName',
		'label': 'colleagueName',
		'standard': 'true'
	},{
		'field': 'colleagueId',
		'label': 'colleagueId',
		'visible': 'false'
	}]
}

Parâmetros

datasetId

Uma string que define id do dataset que o campo pesquisa vai consultar

displayKey

Uma string que define qual o campo do dataset que será usado como exibição no campo pesquisa após a seleção

maximumSelectionLength

(opcional)

Um número inteiro que indica um limite de itens do dataset que podem ser selecionados (múltipla escolha)

Caso não seja informado, será utilizado o valor padrão que é 1, ou seja, permite que apenas um registro selecionado.

resultLimit

(opcional)

Um número inteiro que indica um limite de itens retornado por consulta no campo pesquisa

Caso não seja informado, será utilizado o valor padrão que é 300. Não é recomendável usar um número grande por questões de performance e processamento de dados.

placeholder

(opcional)

Um texto para user usado como place holder, ou seja, uma instrução quando não tiver nenhum item selecionado

Caso não seja informado, o campo não exibirá nenhum texto quando não tiver nenhum item selecionado

filterValues

(opcional)

Uma string complexa composta por um ou mais campos que serão usados como filtro prévio do campo de pesquisa e valores esperados. 

Caso não seja informado, nenhum filtro prévio será utilizado.

fields

Uma lista de objetos que configuram quais são os campos ('field') do dataset que serão exibidos, qual o label ('label') que será utilizado, qual será usado para ordenação ('standard': 'true') e se será visível ou não ('visible': 'false') para o usuário final.

Este campo é válido para os datasets internos do Fluig. Em datasets personalizados, vale lembrar que é necessário implementar os filtros a partir das constraints recebidas.

Métodos

O campo zoom invoca algumas funções que podem ser sobrescritos para uma maior personalização do formulário.

setSelectedZoomItem

Esta função é chamada sempre que um item é selecionado em um campo pesquisa. Pode ser utilizado para armazenar outra informação do item de dataset selecionado em outro campo, validações ou mesmo para atualizar os filtros de outros componentes e campos pesquisa do formulário.

removedZoomItem

Esta função é chamada sempre que um item é removido do campo pesquisa. Normalmente é usado em conjunto com setSelectedZoomItem para "desfazer" as ações.

reloadZoomFilterValues

Esta função é usada para atualizar o filterValues da configuração realizada no atributo data-zoom, e pode ser utilizado para adicionar filtros extras conforme outros dados do formulário ou outras opções selecionadas em outros campos pesquisa. Por exemplo, o usuário selecionou um cliente em um campo pesquisa e eu posso adicionar esta seleção como um novo filtro no campo de pedido.

Dependências

Para o funcionamento correto do componente, o seu formulário deve carregar as seguintes bibliotecas

<link rel="stylesheet" type="text/css" href="/style-guide/css/fluig-style-guide.min.css">
<script src="/resources/js/jquery/jquery.js"></script>
<script src="/resources/js/jquery/jquery-ui.min.js"></script>
<script src="/style-guide/js/fluig-style-guide.min.js"></script>

Exemplos de uso

Consulta simples ao cadastro de usuários buscando e ordenando pelo nome

		<div class="form-group">
			<label for="zoomfield0">Usuário</label>
			<input type="zoom" class="form-control" id="user" name="user" data-zoom="
				{
					'displayKey':'colleagueName',
					'datasetId':'colleague',
					'fields':[{
						'field':'colleagueName',
						'label':'colleagueName',
						'standard':true
					}]
				}">
		</div>

...

Atributos

zoomvalue

Uma string com o nome de um campo do dataset que pode ser armazenado além do texto visível em tela.

O campo de pesquisa pode ser usado para armazenar uma informação para o usuário (como nome de uma pessoa ou empresa) mas a solicitação precisa de um código de identificação (como id do usuário, cpf, cnpj) para alguma integração ou mesmo mecanismo de atribuição. Quando não utilizado o atributo zoomvalue, apenas o valor que é exibido após a seleção é gravado.

Ao utilizar o zoomvalue, o formulário deve conter um campo com nome e id iguais ao do campo de pesquisa com o prefixo "hidden_" (por exemplo, campo "pessoa" precisa do campo "hidden_pessoa"). Assim, ao selecionar um registro, o Fluig irá automaticamente preencher o hidden_campo com o campo do dataset definido no atributo.

Importante: O campo definido no zoomvalue deve estar entre os campos listados em fields no atributo data-zoom

Data-zoom

O atributo data-zoom recebe um objeto onde a maior parte das configurações possíveis para o campo pesquisa são feitas. Ele é um objeto complexo onde é definido qual o dataset, qual campo deste dataset será usado para preencher o campo, se permite mais de uma item selecionado e quais os campos podem ser usados de filtro. Consulte mais sobre ele neste documentação.

Métodos

O campo zoom invoca algumas funções que podem ser sobrescritos para uma maior personalização do formulário.

setSelectedZoomItem (Object item)

Esta função é chamada sempre que um item é selecionado em um campo pesquisa. Pode ser utilizado para armazenar outra informação do item de dataset selecionado em outro campo, validações ou mesmo para atualizar os filtros de outros componentes e campos pesquisa do formulário.

removedZoomItem (Object item)

Esta função é chamada sempre que um item é removido do campo pesquisa. Normalmente é usado em conjunto com setSelectedZoomItem para "desfazer" as ações.

reloadZoomFilterValues (String inputName, String filterValues)

Esta função é usada para atualizar o filterValues da configuração realizada no atributo data-zoom, e pode ser utilizado para adicionar filtros extras conforme outros dados do formulário ou outras opções selecionadas em outros campos pesquisa. Por exemplo, o usuário selecionou um cliente em um campo pesquisa e eu posso adicionar esta seleção como um novo filtro no campo de pedido.

Dependências

Para o funcionamento correto do componente, o seu formulário deve carregar as seguintes bibliotecas

<link rel="stylesheet" type="text/css" href="/style-guide/css/fluig-style-guide.min.css">
<script src="/resources/js/jquery/jquery.js"></script>
<script src="/resources/js/jquery/jquery-ui.min.js"></script>
<script src="/style-guide/js/fluig-style-guide.min.js"></script>

Exemplos de uso

Consulta simples ao cadastro de usuários buscando e ordenando pelo nome

		<div class="form-group">
			<label for="user">Usuário</label>
			<input type="zoom" class="form-control" id="user" name="user" data-zoom="
				{
					'displayKey':'colleagueName',
 					'placeholder': 'Selecione o usuário do Fluig',
 					'datasetId':'colleague',
					'fields':[{
						'field':'colleagueName',
						'label':'colleagueName',
						'standard':true
					}]
				}">
		</div>

Consulta simples ao cadastro de usuários buscando e ordenando pelo nome, mas exibindo o e-mail após a seleção

		<div class="form-group">
			<label for="user">Usuário</label>
			<input type="zoom" class="form-control" id="user" name="user" data-zoom="
				{
					'displayKey':'mail',
 					'placeholder': 'Selecione o usuário do Fluig', 
				    'datasetId':'colleague',
					'fields':[{
						'field':'colleagueName',
						'label':'colleagueName',
						'standard':true
					}]
				}">
		</div>

Consulta ao cadastro de usuários buscando e exibindo o nome do usuário selecionado e o código em outro campo

		<div class="form-group">
			<label for="zoomfield0">Usuário</label>
			<input type="zoom" class="form-control" id="user" name="user" zoomvalue="colleagueId" data-zoom="
				{
					'displayKey':'mailcolleagueName',
					'datasetId':'colleague',
					'fields':[{
						'field':'colleagueNamecolleagueId',
						'label':'colleagueNamecolleagueId',
						'standardvisible':true 'false'
					}],{
						}">
		</div>

do registro selecionado pelo usuário, pode ser adicionada a seguinte função JavaScript ao formulário do processo:

function setSelectedZoomItem(selectedItem) {               
}

Onde selectItem é o registro selecionado pelo usuário na tela de zoom.

Esta função será disparada ao eliminar uma tag (valor) do zoom. A partir deste evento, o valor eliminado poderá ser manipulado, por exemplo, para controlar outros campos que dependem deste valor eliminado. 

 function removedZoomItem(removedItem) {
}

...

'field':'colleagueName',
						'label':'colleagueName',
						'standard':true
					},{
						'field':'mail',
						'label':'mail'
					}]
				}">
 			<input type="hidden" class="form-control" id="hidden_user" name="hidden_user"> <!-- este campo irá armazenar o campo 'collegueId' -->
		</div>

Consulta à solicitação de um determinado processo

...

Bloco de código
language html/xml
selectedItem["fieldName"]

Onde fieldName é o nome do campo de retorno que foi definido na chamada de zoom. Caso a 'label' do campo tenha sido declarada, ela deverá ser utilizada.

Para acessar o tipo de zoom selecionado:

Bloco de código
selectedItem.inputId = "c7_total" selectedItem.inputName = "c7_total"

Onde inputId é o id do campo e inputName é o nome do campo de retorno que foi definido no input zoom. Estes parâmetros possuem a mesma funcionalidade do type da antiga técnica de zoom.

Para recarregar o valor do filterValues no formulário a fim de torná-lo mais dinâmico, é possível utilizar o método a seguir:

Bloco de código
reloadZoomFilterValues(inputName, filterValues);

Este método é padrão durante a execução de um formulário dentro do Fluig a partir da atualização 1.5.5 e recarrega o Zoom por inteiro, colocando os novos valores de filterValues. Em que:

inputName: refere-se ao nome do campo de zoom, ou seja, o valor name na sua declaração;

filterValues: espera-se um valor literal separado por vírgula, sendo que o primeiro valor refere-se ao campo a ser filtrado e o segundo valor refere-se ao valor que irá filtrar.

Informações
title Observação
Foi criado um exemplo (form-smart-filter) de como utilizar o método reloadZoomFilterValues, que você pode acompanhar clicando aqui.

...

Para realizar a busca de um valor em um campo de tipo zoom, com valores obtidos de outros campo zoom, deve-se ser utilizada primeiramente a função setSelectedZoom, que por parâmetro receberá o item selecionado pelo usuário no campo (selectedItem).

Bloco de código
function setSelectedZoomItem(selectedItem) {}

...

Bloco de código
if(selectedItem.inputId == "id do campo"){}

Os id's dos campos de tipo zoom serão retornados em selectedItem.inputId, por este motivo devemos inserir esta validação, para que apenas o valor do campo certo seja retornado. Após o valor do campo estiver de acordo com sua opção, deverá ser utilizada a função reloadZoomFilterValues dentro da validação do nome do campo, que aplicará o filtro e recarregará o zoom.

...

Bloco de código
reloadZoomFilterValues("nome_do_campo_de_zoom_que_receberá_o_filtro", "campo_a_ser_filtrado," + selectedItem["valor_que_ira_filtrar"]);

...

Bloco de código
function setSelectedZoomItem(selectedItem) { if(selectedItem.inputId == "id do campo"){ reloadZoomFilterValues("nome_do_campo_de_zoom_que_receberá_o_filtro", "campo_a_ser_filtrado," + selectedItem["valor_que_ira_filtrar"]); } }

...

Para bloquear e desbloquear um campo de tipo zoom, com base em outro campo, devemos implementar no campo a ser validado, o evento onBLur no HTML apontando para uma função que fará toda a validação e realizará o bloqueio dos campos. Utilizaremos como exemplo o evento onBlur.

Evento onBlur no input passando na função 'this.value', que vai mandar o valor que foi preenchido no campo para a função:

Bloco de código
<input type="text" name="fieldName" id="fieldName" class="form-control" onblur="validateFieldIsNull(this.value)">

...

<div class="form-group"> <label for="solicitacaoRelacionada">Solicitação relacionada</label> <input type="zoom" class="form-control" id="solicitacaoRelacionada" name="solicitacaoRelacionada" data-zoom=" { 'displayKey':'processInstanceId', 'placeholder': 'Selecione a solicitação relacionada', 'datasetId':'workflowProcess', 'filterValues': 'processId,FLUIGADHOC', 'fields':[{ 'field':'processInstanceId', 'label':'Solicitação', 'standard':true },{ 'field':'active', 'label':'Em andamento?' }] }"> </div>

Consulta à solicitação de um determinado processo, após selecionar um processo em outro campo pesquisa

		<div class="form-group">
			<label for="process">Selecione o processo</label>
			<input type="zoom" class="form-control" id="process" name="process" data-zoom="
				{
					'displayKey':'processId',
					'placeholder': 'Selecione o processo',
					'datasetId':'processDefinition',
					'fields':[{
						'field':'processId',
						'label':'Código do Processo'
					},{
						'field':'processDescription',
 						'label':'Descrição',
  						'standard': true
					}]
				}">
		</div>

		<div class="form-group">
			<label for="solicitacaoRelacionada">Solicitação relacionada</label>
			<input type="zoom" class="form-control" id="solicitacaoRelacionada" name="solicitacaoRelacionada" data-zoom="
				{
					'displayKey':'processInstanceId',
					'placeholder': 'Selecione a solicitação relacionada',
					'datasetId':'workflowProcess',
					'fields':[{
						'field':'processInstanceId',
						'label':'Solicitação',
						'standard':true
					},{
						'field':'active',
						'label':'Em andamento?'
					}]
				}">
		</div>

function setSelectedZoomItem(item) {
   if(item.inputId == "user") {
       reloadZoomFilterValues("solicitacaoRelacionada","process," + item.processId);
   }
}

function removedZoomItem(item) {
   if(item.inputId == "user") {
        reloadZoomFilterValues("solicitacaoRelacionada","");
    }
}

Consulta aos usuários permitindo selecionar até 5 usuários

		<div class="form-group">
			<label for="user">Usuário</label>
			<input type="zoom" class="form-control" id="user" name="user" data-zoom="
				{
					'displayKey':'colleagueName',
					'datasetId':'colleague',
					'maximumSelectionLength': 5,
					'fields':[{
						'field':'colleagueId',
						'label':'colleagueId'
					},{
						'field':'colleagueName',
						'label':'colleagueName',
						'standard':true
					},{
						'field':'mail',
						'label':'mail'
					}]
				}">
		</div>

Consulta à solicitação limitando a quantidade de registros retornados

		<div class="form-group">
			<label for="zoomfield1">Solicitação anterior</label>
			<input type="zoom" class="form-control" id="solicitacaoAnterior" name="solicitacaoAnterior" data-zoom="
				{
					'displayKey':'processInstanceId',
					'placeholder': 'Selecione o chamado que você irá avaliar',
					'datasetId':'workflowProcess',
					'resultLimit': 10,
					'fields':[{
						'field':'processInstanceId',
						'label':'Solicitação',
						'standard':true
					},{
						'field':'processId',
						'label':'Código do processo'
					},{
						'field':'active',
						'label':'Em andamento?'
					}]
				}">
		</div>

Consulta ao cadastro de usuários buscando e exibindo o nome do usuário selecionado e o código em outro campo via métodos

		<div class="form-group">
			<label for="zoomfield0">Usuário</label>
			<input type="zoom" class="form-control" id="user" name="user" zoomvalue="colleagueId" data-zoom="
				{
					'displayKey':'colleagueName',
					'datasetId':'colleague',
					'fields':[{
						'field':'colleagueId',
						'label':'colleagueId',
						'visible': 'false'
					},{
						'field':'colleagueName',
						'label':'colleagueName',
						'standard':true
					},{
						'field':'mail',
						'label':'mail'
					}]
				}">
 			<input type="hidden" class="form-control" id="selected_userCode" name="selected_userCode"> <!-- este campo irá armazenar o campo 'collegueId' -->
		</div>

function setSelectedZoomItem(item) {
   if(item.inputId == "user") {
      $("#selected_userCode").val(item.colleagueId);
   }
}

function removedZoomItem(item) {
   if(item.inputId == "user") {
      $("#selected_userCode").val("");
   }
}

Outros exemplos de uso em nossos repositórios

Smart Zoom

Um exemplo com 3 campos zooms interagindo uns com os outro, modificando os valores atribuídos nos demais conforme a seleção de dados

Integração com serviços de terceiros

Um exemplo simples consultando datasets personalizados.

Solicitação de Compra de RM

Um exemplo consultando datasets personalizados onde a seleção de um dado no campo de pesquisa filtra os resultados do campo pesquisa seguinte

...

function validateFieldIsNull(valor){
	if(valor != ""){
		window["zoomfield"].disable(false);
	} else {
   		window["zoomfield"].disable(true);
	}
} 

Filtrar colunas do Zoom 

O campo Pesquisa também conhecido como Zoom, agora traz o botão “Filtrar colunas” que irá facilitar a aplicação de filtros no campo de pesquisa do registro de formulário, possibilitando realizar buscas por colunas específicas. Esta ação tornará o resultado de busca mais fácil e rápido.

O botão Filtrar colunas irá possibilitar que todas as colunas do zoom sejam exibidas, porém será possível selecionar quais colunas serão apresentadas ao preencher um registro de formulário, através da seleção do indicativo ON e OFF.

Por exemplo: ao definir a coluna Código como OFF ela não será apresentada no formulário, da mesma forma que, ao defini-la como ON a coluna será apresentada. 

Image Removed

Zoom Externo

Em situações aonde os dados dos elementos externos ao Fluig são muito volumosos é recomendada a construção de uma aplicação externa ao Fluig que fará o papel de zoom para o usuário. Abaixo será descrita uma técnica JavaScript aonde será possível chamar uma aplicação externa e a mesma poderá devolver o dado solicitado pelo usuário para um campo do formulário do Fluig.

O primeiro passo para implementação dessa técnica é criar uma lógica em JavaScript que irá abrir uma nova janela chamando a aplicação externa que irá se comportar como zoom para o formulário. Vamos utilizar e explanar o comando window.open neste exemplo:

Window.open(URL Aplicação Externa, Nome da Janela que será aberta, comandos adicionais)

Onde:

URL Aplicação Externa: É a url da aplicação externa que funcionará como zoom para o Fluig. Ex: http://servidor/applications/forneczoom.asp.

Nome da Janela: Nome da janela que será utilizado pelo navegador do usuário como identificador. Para evitar a sobreposição de conteúdo em janela é recomendado que para cada zoom chamado por um mesmo formulário seja adicionado um nome diferente. Ex: “ZoomFormec”.

Comandos Adicionais: Comandos adicionais utilizados para a criação da janela que irá conter a aplicação zoom. Ex: “width=230, height=230”.

O código abaixo irá programar um formulário do Fluig contendo um campo e um botão lateral que irá invocar a janela da aplicação externa:

<form name=”FornecedorForm”>
  Código do Fornecedor:
  <input name=”cod_fornec” size=’10” value=”” type=”text”>
  <input value=”lista” onClick=”mostraLista()” type=”button”>
</form>

<script language=”JavaScript”>
   Function mostraLista() {
     Window.open(“fornecedores.html”, “list”,”width=230,height=230”);
   }
</script>       

O segundo passo é programar dentro da aplicação externa uma função JavaScript que devolva para o campo do formulário o valor escolhido para o usuário na aplicação externa. Essa aplicação externa poderá ser desenvolvida em qualquer tecnologia de desenvolvimento web existente no mercado de que a mesma possa realizar a execução de scripts JavaScript no lado do cliente. Segue exemplo de uma função JavaScript que passa o valor para o campo do formulário:

<script language=”JavaScript”>
   function escolha(valor) {
       // A linha abaixo testa se a janela do formulário do fluig que abriu a janela de zoom ainda está aberta
       if (window.opener && !window.opener.close) {
              // seta o valor passando para o campo
              window.opener.document.(id do form no formulário fluig).(nome do campo).value = valor;
       }
       // Fecha a janela da aplicação zoom
       window.close();
   }
</script>

Onde:

Id do form no formuário Fluig: Caso algum id tenha sido definido para a tag <form> no formulário do Fluig é interessante referenciar neste comando. Pode ser utilizada também a referência de coleção forms dentro do comando (forms[posição]). 
Ex: FornecedorForm, forms[0].

Nome do Campo: Nome do campo que irá receber o valor passado para a função. 
Ex: cod_fornec.

Valor: Dado que será passado para o campo do formulário do Fluig.

O exemplo a seguir irá programar um exemplo de zoom externo feito inteiramente em HTML com dados estáticos apenas para ilustração. Os dados de zoom podem provir de qualquer fonte seja ela interna ou externa ao Fluig.

<html>
  <head>
  <title>Lista de fornecedores</title> 


<script language="JavaScript"> 
function escolha(valor) { 
  // Teste de validade do Opener 
  if (window.opener && !window.opener.closed) { 
      // gravando o valor do campo cod_fornec 
      window.opener.document.forms[0].cod_fornec.value = valor; 
  } 
   window.close(); 
} 
</script>
 
  </head>
  <body>   

  <!-- Os dados abaixo estão fixos mas poderiam ser montados a partir de qualquer origem. --> 

  <table border="1" cellpadding="5" cellspacing="0"> 
  <tbody><tr bgcolor="#cccccc"><td colspan="2"><b>Exemplo aplicacao ECM</b></td></tr> 
  <tr bgcolor="#cccccc"><td><b>Codigo</b></td><td><b>NASDAQ</b></td></tr> 
  <tr><td><a href="javascript:escolha('TOTVSv3')">TOTVS</a></td> 
  <td><a href="javascript:escolha('TOTVSv3')">TOTVSv3</a></td></tr> 
  <tr><td><a href="javascript:escolha('RM1')">RM</a></td> 
  <td><a href="javascript:escolha('RM1')">RM1</a></td></tr> 
  <tr><td><a href="javascript:escolha('DTS3')">Datasul</a></td> 
  <td><a href="javascript:escolha('dts3')">Dts3</a></td></tr> 
  <tr><td><a href="javascript:escolha('Lgx2')">Logix</a></td> 
  <td><a href="javascript:escolha('Lgx2')">Lgx2</a></td></tr> 
  </tbody>
  </table> 

  <!-- Fim dos dados --> 

  </body>
</html>

Para colocar o exemplo em prática no produto, basta publicar a definição de formulário a seguir informando o arquivo do zoom externo como anexo da definição de formulário.

Exemplo de Zoom.zip

Ao clicar em um dos itens da tela de zoom será chamada a função JavaScript escolha que ira enviar o valor para o campo cod_fornec no formulário do Fluig.