Skip to end of metadata
Go to start of metadata

Índice


Objetivo


Um Dataset pode ser acessado de várias formas: no desenvolvimento de widgets, formulários, webservices, eventos globais, eventos de formulários e eventos de processos.
O objetivo desse guia é mostrar como acessar o Dataset nestes cenários.


Pré-requisitos


Para que se tenha uma compreensão completa destas informações, alguns conhecimentos são considerados pré-requisitos, entre eles:


Acessando um Dataset


Vários locais do fluig podem fazer uso dos dados retornados pelos Datasets. Serão apresentadas abaixo as variações na forma de acessá-los ou de manuseá-los.


Widgets

No desenvolvimento de um widget, é possível acessar dados de Datasets, através da linguagem Javascript, utilizando a biblioteca DatasetFactory.

Consulte a documentação Integrando widget com formulários/datasets do fluig.


Via pontos de customização

Quando um Dataset é acessado via um ponto de customização como eventos globais, eventos de processos, eventos de formulário ou mesmo em outros Datasets, isto é feito através de chamadas JavaScript que serão executadas no lado servidor.

O exemplo abaixo apresenta um exemplo simples de chamada a um Dataset:

function doTest1() {
	var dataset = DatasetFactory.getDataset("group", null, null, null);
	return dataset.rowsCount;
}

No exemplo acima, o código JavaScript faz o acesso ao Dataset interno group, e retorna a quantidade de linhas disponíveis (rowsCount). O objeto DatasetFactory é a "porta de entrada" para o acesso a qualquer Dataset. Além de permitir a carga de um Dataset, ela também permite navegar entre todos os Datasets disponíveis no sistema.

O acesso a um Dataset é feito através do método getDataset do objeto DatasetFactory, onde seus parâmetros são:

  • Nome do Dataset: Nome do Dataset a ser buscado;
  • Campos: Array com os campos do Dataset que serão retornados. Caso seja informado null, retorna todos os campos do Dataset;
  • Constraints: Array com os condições de busca do Dataset. Caso seja informado null, retorna todos os registros do Dataset.
  • Ordem: Array com os campos para ordenação dos registros do Dataset. Caso seja informado null, retorna os registros com a ordenação padrão.

Já para a criação das constraints é utilizado o método createConstraint do objeto DatasetFactory, onde seus parâmetros são:

  • Campo: Nome do campo que será filtrado;
  • Valor Inicial: Valor inicial da faixa de valores do filtro
  • Valor Final: Valor final da faixa de valores do filtro
  • Tipo: Tipo da condição, podendo ser:
    • MUST: indica que todos os registros do Dataset devem satisfazer a esta condição.
    • SHOULD: indica que os registros do Dataset podem ou não atender à condição. Esse tipo é mais comum quando se necessita que um mesmo campo tenha valores A ou B (onde cada um será uma condição de busca com tipo SHOULD).
    • MUST_NOT: indica que nenhum dos registros pode satisfazer a condição.


Após a criação da constraint, é possível informar que esta será utilizada na consulta em formato de LIKE, ou seja, o valor retornado poderá conter qualquer letra ou sequência de letras no lugar do símbolo '%'. Isso é feito chamando o método setLikeSearch(true) para a constraint que se deseja este comportamento, conforme exemplificado na implementação abaixo, na constraint c5, onde pretende-se retornar todos os registros que NÃO possuam (pois é uma constraint MUST_NOT) a palavra "teste" na descrição do documento.

Exemplo:

function doTest2() {
	//Monta as constraints para consulta
	var c1 = DatasetFactory.createConstraint("activeVersion", "true", "true", ConstraintType.MUST);
	var c2 = DatasetFactory.createConstraint("publisherId", "adm", "adm", ConstraintType.MUST_NOT);
	var c3 = DatasetFactory.createConstraint("documentType", "1", "1", ConstraintType.SHOULD);
	var c4 = DatasetFactory.createConstraint("documentType", "2", "2", ConstraintType.SHOULD);
	var c5 = DatasetFactory.createConstraint("documentDescription", "%teste%", "%teste%", ConstraintType.MUST_NOT);
    c5.setLikeSearch(true);
    var constraints   = new Array(c1, c2, c3, c4, c5);
	
	//Define os campos para ordenação
	var sortingFields = new Array("documentPK.documentId");
	
	//Busca o dataset
	var dataset = DatasetFactory.getDataset("document", null, constraints, sortingFields);
	
	for(var i = 0; i < dataset.rowsCount; i++) {
		log.info(dataset.getValue(i, "documentPK.documentId"));
	}
}

Para utilizar a função likeSearch utilizando a biblioteca vcXMLRPC.js, deve ser adicionado mais um parâmetro no método DatasetFactory.createConstraint, e não utilizar o método setLikeSearch(true). Exemplo:

var c5 = DatasetFactory.createConstraint("documentDescription", "%teste%", "%teste%", ConstraintType.MUST_NOT, true);

Isto é válido apenas para a utilização da biblioteca vcXMLRPC.js.

Constraints Avançadas 

Existe uma constraint em especial que é utilizada para limitar o número de registros na consulta SQL chamada de sqlLimit. Então é possível definir o número máximo de registros que uma consulta SQL pode retornar, porém o número de registros pode ser menor que o esperado, devido algumas validações que são feitas após o retorno dos dados. Por exemplo: O sqlLimit tem um valor 100 e é feita uma consulta em um serviço de dados de uma definição de formulário, esta consulta retornará os 100 registros, porém após isso são executadas validações para verificar se o formulário está ativo e se o usuário corrente tem permissão para visualizar os dados fazendo com que o retorno possa ser menor que 100. Para o sqlLimit é utilizada a seguinte sintaxe:

 DatasetFactory.createConstraint("sqlLimit", "10", "10", ConstraintType.MUST);

Observação: O valor considerado no sqlLimit é sempre o initialValue, o que for informado no finalValue não será considerado.

Existe outra constraint especial utilizada somente para acesso a Datasets de definições de formulário, ela indica se ao buscar o serviço de dados devem ser retornados APENAS os dados dos formulários da definição de formulário principal. A constraint é a onlyMainCards e por padrão seu valor é false, ou seja, são retornados os dados dos formulários da definição de formulário principal e das definições de formulários filhas.

DatasetFactory.createConstraint("onlyMainCards", "true", "true", ConstraintType.MUST);

Observação

O valor considerado no onlyMainCards é sempre o initialValue, o que for informado no finalValue não será considerado.

Existe ainda, outra constraint especial que é a checkSecurity essa constraint é válida somente para Datasets de formulário e quando utilizada, fará o retorno dos registros do formulário validarem a segurança, ou seja, o Dataset retornará somente os registros de formulário que o usuário possua permissão para visualização.

DatasetFactory.createConstraint("checkSecurity", "true", "true", ConstraintType.MUST);

Atenção

As constraints podem ser utilizadas apenas para Datasets internos. Datasets avançados não aceitam constraints, pelo fato de os dados serem externos, não sendo possível aplicar o filtro em sua origem. Para Datasets avançados o tratamento de filtros deve ser feito na codificação do Dataset, manipulando o objeto retornado e retirando as informações desnecessárias.

Exemplificação de uso de Constraints

Considere os valores da tabela abaixo sendo utilizadas como um serviço de dados a partir de uma definição de formulário para exemplificação dos exemplos:

CódigoNomeCidade
1Javier SpivaSão Paulo
2Cody BallowRio de Janeiro
3Javier NaramoreSão Paulo
4Max NeviusRio de Janeiro
5Noemi RoigerSão Paulo
6Lonnie CadwalladerRio de Janeiro
7Lorrie SpeceBrasília

Verifique os exemplos de retorno de dados abaixo:

    Para retornar somente as linhas que os códigos estejam entre 1 á 4 usar a seguinte constraint:

    var c1 = DatasetFactory.createConstraint("Código", "1", "4", ConstraintType.MUST);

    Retorno:

    Código Nome Cidade
    1 Javier Spiva São Paulo
    2 Cody Ballow Rio de Janeiro
    3 Javier Naramore São Paulo
    4 Max Nevius Rio de Janeiro

    Para retornar somente as linhas que os nomes sejam "Noemi Roiger", "Javier Naramore" e "Lonnie Cadwallader" ou que a cidade seja Brasília, usar as seguintes constraints:

    var c1 = DatasetFactory.createConstraint("nome", "Noemi Roiger", "Noemi Roiger", ConstraintType.SHOULD);
    var c2 = DatasetFactory.createConstraint("nome", "Javier Naramore", " Javier Naramore", ConstraintType.SHOULD);
    var c3 = DatasetFactory.createConstraint("nome", "Lonnie Cadwallader", "Lonnie Cadwallader", ConstraintType.SHOULD);
    var c4 = DatasetFactory.createConstraint("cidade", "Brasília", "Brasília", ConstraintType. SHOULD);

    Retorno:

    Código Nome Cidade
    3 Javier Naramore São Paulo
    5 Noemi Roiger São Paulo
    6 Lonnie Cadwallader Rio de Janeiro
    7 Lorrie Spece Brasília

    Para retornar todas as linhas exceto onde a cidade seja Brasília, usar a seguinte constraint:

    var c1 = DatasetFactory.createConstraint("cidade", "Brasília", "Brasília", ConstraintType.MUST_NOT);

    Retorno:

    Código Nome Cidade
    1 Javier Spiva São Paulo
    2 Cody Ballow Rio de Janeiro
    3 Javier Naramore São Paulo
    4 Max Nevius Rio de Janeiro
    5 Noemi Roiger São Paulo
    6 Lonnie Cadwallader Rio de Janeiro


    Formulários

    Em formulários, é possível que um ou mais campos possam exibir ou consultar dados de Datasets utilizando Javascript ou tags.

    Via JavaScript em formulário

    O fluig permite acessar os Datasets via código JavaScript no HTML de uma definição de formulário utilizando a biblioteca vcXMLRPC.js para utilização do DatasetFactory. Para isto, basta incluir a linha abaixo antes da tag body do HTML:

    <script type="text/javascript" src="/webdesk/vcXMLRPC.js"></script>

    Importante

    Este modelo de acesso faz com que o Dataset seja transportado do servidor para o cliente, ou seja, o navegador do usuário. Por isso, é importante observar a quantidade de informações que será manuseada, caso contrário pode-se ter problemas de consumo excessivo de banda ou performance.


    Exemplo:

    function showNewDatasetFull() {
    	var div = document.getElementById("datasetDiv");
      	
    	//Busca o dataset
      	try {
        	var dataset = DatasetFactory.getDataset("colleague");
        	div.innerHTML = showDataset(dataset);
      	} catch(erro) {
      	  	div.innerHTML = erro;
      	}
    }
    
    function showDataset(dataset) {
    	var tabela = "<table>";
      	
    	//Monta o cabeçalho
      	tabela += "<tr>";
      	for (var i = 0; i < dataset.columns.length; i++) {
        	tabela += "<th>" + dataset.columns[i] + "</th>";
    	}
      	tabela += "</tr>";
    
      	//Monta os registros  	
      	for (var x = 0; x < dataset.values.length; x++) {
      		tabela += "<tr>";
        	var row = dataset.values[x];
        	for (var y = 0; y < dataset.columns.length; y++) {
        		tabela += "<td>" + row[dataset.columns[y]] + "</td>";
    		}
        	tabela += "</tr>";
      	}
      	
    	tabela += "</table>";
    	return tabela;
    }

    No exemplo acima, percebe-se que a forma de se invocar um Dataset é semelhante ao método via pontos de customização, através do DatasetFactory. A função showDataset apresenta um exemplo de código que permite apresentar os dados do Dataset.

    Assim como no método via pontos de customização, quando é preciso filtrar um Dataset é preciso criar as constraints que serão utilizadas na busca. Os argumentos utilizados no método getDataset também são os mesmos que apresentados anteriormente:

    function showNewDatasetPartial() {
    	var div = document.getElementById("datasetDiv");
    			
    	var c1 = DatasetFactory.createConstraint("parentDocumentId", "5", "5", ConstraintType.MUST);
    	var c2 = DatasetFactory.createConstraint("documentType", "1", "1", ConstraintType.MUST_NOT);
    	var c3 = DatasetFactory.createConstraint("activeVersion", "true", "true", ConstraintType.MUST);
    	var constraints   = new Array(c1, c2, c3);
    	
    	//Define os campos para ordenação
    	var fields = new Array("documentPK.documentId", "documentDescription", 
    			"documentType", "publisherId", "accessCount");
    	var sortingFields = new Array("accessCount", "documentDescription");
    	
    	//Busca o dataset
      	try {
        	var dataset = DatasetFactory.getDataset("document", fields, constraints, sortingFields);
        	div.innerHTML = showDataset(dataset);
      	} catch(erro) {
      	  	div.innerHTML = erro;
      	}
    }


    Via Tags no Formulário

    O fluig permite especificar um Dataset em um campo select (combo-box). Quando isto é feito, as opções do combo são automaticamente criadas de acordo com os dados do Dataset. Para isso, é necessário adicionar três propriedades adicionais à tag:

    Propriedade

    Descrição

    datasetDetermina o Dataset utilizado
    datasetkeyDetermina qual coluna do Dataset será utilizada como valor do campo
    datasetvalueDetermina qual coluna do Dataset será utilizada como rótulo das opções do combo

    No exemplo abaixo, o campo "estado" foi configurado para que as opções do combo sejam criadas a partir do Dataset "estadosBR". Como valor do campo será utilizado o campo "Sigla", embora para o usuário será apresentado o campo "Estado". 

    1

    <select name="estado" dataset="estadosBR" datasetkey="Sigla" datasetvalue="Estado"></select>

    Exemplo

    Webservices

    O fluig disponibiliza um conjunto de WebServices que permitem integrar aplicações de terceiros à plataforma. Dentre os serviços disponibilizados, o serviço ECMDatasetService permite fazer o acesso a um Dataset. Para verificar a lista de serviços disponíveis no fluig, acesse a URL http://<servidor>:<porta>/webdesk/services.

    A forma de uso de um Web Service varia de acordo com a tecnologia utilizada pela aplicação cliente. Consulte a documentação da tecnologia escolhida pra obter detalhes sobre como acessar Web Services.


    Via DataTable

    Para consumir um Dataset dentro de um DataTable, também utilizamos a função DatasetFactory. É necessário incluir a biblioteca vcXMLRPC.js no final dos arquivos edit.ftl e view.ftl do widget para que seja possível utilizar a função.

    <script type="text/javascript" src="/webdesk/vcXMLRPC.js"></script>

    Após configurado o arquivo vcXMLRPC.js, edite o arquivo .js do widget chamando o Dataset que desejar consumir. Abaixo segue um exemplo de uma chamada para o consumo do Dataset colleague:

    	loadTable: function() {
    		var that = this;
    		var datasetReturned = DatasetFactory.getDataset("colleague", null, null, null);
    		if (datasetReturned != null && datasetReturned.values != null && datasetReturned.values.length > 0) {
    			var records = datasetReturned.values;
    			for ( var index in records) {
    				var record = records[index];
    				that.mydata.push({
    					id: record.userTenantId,
    					name: record.colleagueName,
    					email: record.mail
    				});
    			}
    		}
    		that.myTable = FLUIGC.datatable('#idtable' + "_" + that.instanceId, {
    			dataRequest: that.mydata,
    			renderContent: ['id', 'name', 'email'],
    			header: [{
    				'title': 'Code',
    				'dataorder': 'name',
    				'size': 'col-md-4'
    			}, {
    				'title': 'Name',
    				'standard': true,
    				'size': 'col-md-4'
    			}, {
    				'title': 'EMAIL',
    				'size': 'col-md-4',
    				'dataorder': 'ASC'
    			}],
    			search: {
    				enabled: false,
    			},
    			scroll: {
    				target: ".target",
    				enabled: true
    			},
    			actions: {
    				enabled: false,
    			},
    			navButtons: {
    				enabled: false,
    			},
    			draggable: {
    				enabled: false
    			},
    		}, function(err, data) {
    			if (err) {
    				FLUIGC.toast({
    					message: err,
    					type: 'danger'
    				});
    			}
    		});
    		that.myTable.on('fluig.datatable.loadcomplete', function() {
    			if (!that.tableData) {
    				that.tableData = that.myTable.getData();
    			}
    		});
    	},

    Para um exemplo completo do uso de widget com DataTable acesse Widget com DataTable, lembrando de trocar a function loadTable do widget pela função loadTable do exemplo acima.

    Para um exemplo completo do uso de modal com Datable acesse Modal com DataTable e Dataset, lembrando sobre a limitação do datatable, no qual não é possível efetuar paginação pois não possui os recursos de offset e limit.