Cada ação de dados deve implementar vários métodos para funcionar corretamente, sendo apenas necessário substituir os métodos que implementam comportamento que pretende alterar.
Métodos Genéricos
Se estiver a alargar uma das classes de ações de dados concretas, por exemplo HTTPAPIDataAction, a maior parte dos métodos necessários já está implementada e só precisa de substituir os métodos que implementam o comportamento que pretende alterar.
Esta secção descreve os vários métodos e o que se espera deles.
Todos os tipos de ação de dados devem implementar os métodos aqui descritos.
create(sID, sName)
O método estático create() é chamado quando está a criar uma nova ação de dados e seleciona um Tipo de Ação de Dados a partir do menu pendente. Este método é responsável por:
A classe do Modelo Knockout deve ter a ID e o nome transmitidos ao método create() juntamente com os valores por omissão adequados para todas as outras propriedades. Por exemplo, para uma ação de dados de conversão de moeda, poderá pretender definir a moeda por omissão para converter em euros. O Modelo Knockout é o local correto para fornecer os seus valores por omissão.
invoke(oActionContext, oDataActionContext)
O método invoke() é chamado quando o utilizador invoca a sua ação de dados a partir do menu de contexto de um ponto de dados numa visualização. O método transmite o argumento DataActionContext que contém metadados que descrevem os pontos de dados selecionados, a visualização, os filtros, o livro e a sessão. Consulte Classes de Serviços de Ações de Dados.
validate()
O método validate() é chamado em cada ação de dados quando o utilizador clica em OK na caixa de diálogo Ações de Dados. O método validate() devolve um valor null para indicar que tudo é válido ou um DataActionError se houver algo inválido. Se existir um erro numa das ações de dados na caixa de diálogo, o erro impede que a caixa de diálogo seja fechada e é apresentada uma mensagem de erro ao utilizador. Este método valida o nome da ação de dados utilizando o método this.validateName().
getGadgetInfos(oReport)
O método getGadgetInfos() é chamado para ativar a interface do utilizador para apresentar campos de propriedades de ações de dados. O método devolve uma matriz de GadgetInfos pela ordem em que pretende que apareçam na interface do utilizador. São fornecidos gadgets para todos os tipos de campos mais comuns (por exemplo, texto, lista pendente, senha, seleção múltipla, botão de rádio, caixa de seleção), mas pode criar gadgets customizados se quiser campos mais complicados (por exemplo, em que vários gadgets são agrupados ou em que são apresentados campos de gadgets diferentes consoante a opção que for selecionada). Um procedimento recomendado é criar um método que crie cada GadgetInfo que pretende na sua matriz, uma vez que torna mais fácil às potenciais subclasses escolher a partir dos GadgetInfos fornecidos. Se seguir este procedimento recomendado, já existem vários métodos implementados pelas diferentes classes base de ações de dados que podem devolver um GadgetInfo para cada um dos campos utilizados nas respetivas interfaces do utilizador. Se também precisar de algum destes GadgetInfos, chame o método create****GadgetInfo() correspondente e efetue push do respetivo valor de retorno para a sua matriz de gadgets.
isAllowedHere(oReport)
O método isAllowedHere() é chamado quando o utilizador clica com o botão direito do rato num ponto de dados numa visualização e a interface do utilizador começa a gerar o menu de contexto. Se existir uma ação de dados que seja relevante para os pontos de dados selecionados, o método devolve true e a ação de dados aparece no menu de contexto. Se o método devolver false, a ação de dados não aparece no menu de contexto. Considere aceitar o comportamento por omissão herdado da superclasse.
upgrade(oOldDataActionJS)
Se estiver a criar a sua primeira ação de dados, não utilize o método upgrade(oOldDataActionJS). Utilize este método apenas depois de ter criado o seu primeiro Modelo Knockout e se estiver a efetuar alterações significativas às propriedades para uma segunda versão do seu Modelo Knockout. Por exemplo, se a primeira versão da sua ação de dados armazenar um URL no respetivo Modelo Knockout, mas decidir que a próxima versão irá armazenar as partes componentes do URL em propriedades separadas (por exemplo, protocol, hostname, port, path, queryString e bookmark).
A segunda versão do código do Modelo Knockout iria pedir para abrir uma ação de dados gravada com a primeira versão do código do Modelo Knockout, o que pode causar problemas. Para resolver este problema, o sistema identifica que a sua versão do código da ação de dados atual é mais recente do que a da ação de dados a ser aberta e chama o método upgrade() na sua classe de ação de dados nova, transmitindo o Modelo Knockout da ação de dados antigo (serializado para um objeto JSON). Depois, pode utilizar o objeto JSON antigo para preencher o seu novo Modelo Knockout e devolver uma versão atualizada do objeto JSON. Isto assegura que os metadados da ação de dados antigos continuam a funcionar enquanto melhora o código da ação de dados.
Métodos de HTTPAPIDataAction
Se estiver a alargar a classe HTTPAPIDataAction, é fornecido o seguinte método adicional que pode optar por substituir:
getAJAXOptions(oDataActionContext)
O método getAJAXOptions() é chamado pelo método invoke() da ação de dados. O método getAJAXOptions() cria o objeto AJAX Options que descreve o pedido de HTTP que pretende que a sua ação de dados efetue. O método getAJAXOptions() recebe o objeto oDataActionContext que contém os metadados que descrevem os pontos de dados selecionados, a visualização, os filtros, o livro e a sessão. Defina AJAX Options conforme requerido pela API HTTP com a qual está a tentar a integração e especifique as funções que pretende que sejam chamadas quando o HTTPRequest tiver êxito ou resultar num erro. Consulte o site JQuery para obter uma explicação do objeto jQuery.ajax e das respetivas propriedades.
A implementação seguinte é herdada da classe HTTPAPIDataAction. É necessário reescrever o método herdado para especificar requisitos. Por exemplo, formar o pedido de HTTP e o código que processa a resposta de HTTP. Esta implementação é útil porque mostra os parâmetros transmitidos à função getAJAXOptions(), o objeto que deverá ser devolvido e apresenta um exemplo claro de como estruturar o código dentro do método.
1 /**
2 * This method returns an object containing the AJAX settings used when the data action is invoked.
3 * Subclasses may wish to override this method to provide their own behavior.
4 * @param {module:obitech-reportservices/dataactionmanager.DataActionContext} oDataActionContext The context metadata describing where the data action was invoked from.
5 * @returns {?object} A JQuery AJAX settings object (see http://api.jquery.com/jQuery.ajax/ for details) - returns null if there is a problem.
6 */
7 dataaction.HTTPAPIDataAction.prototype.getAJAXOptions = function (oDataActionContext)
8 {
9 jsx.assertInstanceOfModule(oDataActionContext, "oDataActionContext", "obitech-reportservices/dataactionmanager", "DataActionContext");
10
11 var oAJAXOptions = null;
12 var oKOViewModel = this.getKOViewModel();
13 var sURL = oKOViewModel.sURL();
14 if (sURL)
15 {
16 // Parse the URL
17 var sResultURL = this._parseURL(sURL, oDataActionContext);
18 if (sResultURL)
19 {
20 // Parse the POST parameters (if required)
21 var eHTTPMethod = oKOViewModel.eHTTPMethod()[0];
22 var sData = null;
23 if (eHTTPMethod === dataaction.HTTPDataActionKOModel.HTTPMethod.POST)
24 {
25 var sPOSTParams = oKOViewModel.sPOSTParams();
26 sData = sPOSTParams.replace(dataaction.AbstractHTTPDataAction.RegularExpressions.LINE_END, "&");
27 sData = this._parseURL(sData, oDataActionContext, false);
28 }
29 oAJAXOptions = {
30 type: eHTTPMethod,
31 url: sResultURL,
32 async: true,
33 cache: false,
34 success: function (/*oData, sTextStatus, oJQXHR*/)
35 {
36 oDataActionContext.getReport().displaySuccessMessage(messages.HTTP_API_DATA_ACTION_INVOCATION_SUCCESSFUL.format(oKOViewModel.sName()));
37 },
38 error: function (oJQXHR/*, sTextStatus, sError*/)
39 {
40 oDataActionContext.getReport().displayErrorMessage(messages.HTTP_API_DATA_ACTION_INVOCATION_FAILED.format(oKOViewModel.sName(), oJQXHR.statusText, oJQXHR.status));
41 }
42 };
43 if (sData)
44 {
45 oAJAXOptions.data = sData;
46 }
47 }
48 }
49 return oAJAXOptions;
50 };