Criando e utilizando um DataSource

Um DataSource é construído a partir de um script .ids no sistema de arquivos virtual ou somente instanciando o DataSource e passando como parâmetro um objeto literal. O objeto literal definido no .ids ou passado direto como parâmetro deve conter as seguintes propriedades e funções:

• • includes (opcional): é um array de chaves ou scripts que devem ser inclusos quando for necessário utilizar alguma biblioteca ou função externa ao DataSource. Utilizada quando algum script faz uso de bibliotecas ou funções externas ao DataSource.

  • help: a ajuda do DataSource. Certas classes que utilizam o DataSource, como por exemplo a DataSourceVisualization, podem exibir esta ajuda em tela.

  • onDefineFilters (opcional): esse método, quando definido, será executado na definição especializada dos filtros do datasource e roda no início de sua criação. Isso será especialmente útil quando, na preparação do availableFilters, for necessário acessar os scripts sinalizados na propriedade includes. O primeiro parâmetro passado é a própria definição do objeto literal que constrói o datasource. O segundo parâmetro passado é a instância do datasource.

  • onDefineColumns (opcional): esse método, quando definido, será executado na definição especializada das colunas do datasource e roda no início de sua criação. Isso também será útil quando, na preparação do availableColumns, for necessário acessar os scripts sinalizados na propriedade includes. O primeiro parâmetro passado é a própria definição do objeto literal que constrói o datasource. O segundo parâmetro passado é a instância do datasource.

  • onCreate (opcional): esse método será executado no final da construção do DataSource. Recebe o próprio DataSource como único parâmetro.

  • availableFilters: definição dos filtros que podem ser usados para a consulta que o DataSource realiza. Não é necessário usá-los todos durante uma consulta. Essa propriedade é um Array de objetos, cujo formato será detalhado mais adiante neste manual.

  • availableColumns: definição das colunas que ficarão disponíveis para uso em consultas. Ao menos uma coluna precisa ser utilizada durante uma consulta. Esta propriedade é um Array de objetos, cujo formato será detalhado mais adiante.

  • onCreate (opcional): esse método será executado durante a criação do DataSource. Recebe o próprio DataSource como único parâmetro.

  • onGetQuery: esse método recebe o próprio DataSource, uma instância de uwl.datsource.Filters e uma de uwl.datasource.Columns. Os dois últimos parâmetros são objetos montados pelo DataSource a partir de suas definições. O método onGetQuery deve retornar uma query SQL, que será utilizada pelo método getDataSet do DataSource.

Segue um exemplo de implementação:

onGetQuery: function (dataSource, filters, columns) { var filts = filters.getIQueryFilters("U_*", "and"); var cols = columns.getIQueryColumns("U_*"); if (columns.indexOf("U_iKey") === -1) { cols.push({ alias: "U_iKey", field: "iKey" }); } var iquery = IQuery.from(-1898187809) /* Usuários */ .where(filts) .column(cols); return iquery.toSql(); }

• • onMountDataSet (opcional): executado após a obtenção do DataSet no método getDataSet do DataSource. O DataSet obtido é informado como parâmetro, e o retorno deste método substitui o retorno do método getDataSet.

Os filtros e colunas no script são objetos literais, cuja documentação das definições se encontra em bdo.datasource.FilterDef e bdo.datasource.ColumnDef.

Opcionalmente, uma fonte de dados pode ser construída de forma imperativa criando uma instância da classe bdo.datasource.DataSourceDef. Essa forma alternativa é útil quando a definição de filtros e colunas dependem de regras externas à fonte de dados ou quando deseja-se reaproveitar lógicas existentes em outros códigos. Exemplos de como utilizar essa forma alternativa podem ser vistos aqui.

Consumindo o DataSource

Uma vez que o script esteja pronto, podemos criar instâncias a partir dele. Precisamos apenas de sua chave.

Atenção: o DataSource faz parte da biblioteca do Framework. Para utilizá-la fora do Framework, você deve incluí-la da seguinte forma:

__includeOnce('ufs:/uwl/all.js');

Para criar uma instância do DataSource, há duas formas:

Utilizando chave da iVFS, onde key é a chave do script .ids que você deseja usar:

var dts = new DataSource(key);

Ou utilizando objeto literal e passando para o construtor:

var obj = {includes: [], //includes help: "", //Ajuda do DataSource availableFilters: [], //Filtros disponíveis availableColumns: [], //Colunas disponíveis onCreate: function(){}, //Função invocada na criação do DataSource (opcional) onGetQuery: function(dataSource, filters, columns){} //Função de montagem da query } var dts = new DataSource(obj);

Antes de recuperar um DataSet com o nosso DataSource, precisamos definir quais colunas e filtros desejamos utilizar, através das funções createFilter e createColumns. Por exemplo:

var filters = dts.createFilters([{prefix: 'U', classKey: -1898187811 /*Grupos, papéis e usuários*/}]); var columns = dts.createColumns([{prefix: 'U', classKey: -1898187811 /*Grupos, papéis e usuários*/}]);

A seguir, utilizamos o método getDataSet da instância:

var ds = dts.getDataSet(filters, columns);

O retorno será um DataSet preenchido com os dados desejados.