Jede Datenaktion muss für ihre ordnungsgemäße Funktion verschiedene Methoden implementieren. Sie müssen also nur die Methoden außer Kraft setzen, die zu änderndes Verhalten implementieren.
Generische Methoden
Wenn Sie eine der konkreten Datenaktionsklassen erweitern (z.B. HTTPAPIDataAction), sind die meisten erforderlichen Methoden bereits implementiert. Sie müssen also nur die Methoden außer Kraft setzen, die zu änderndes Verhalten implementieren.
In diesem Abschnitt werden die verschiedenen Methoden und deren erwartetes Verhalten beschrieben.
Alle Datenaktionstypen müssen die hier beschriebenen Methoden implementieren.
create(sID, sName)
Die statische create()-Methode wird aufgerufen, wenn Sie eine neue Datenaktion erstellen und im Dropdown-Menü einen Datenaktionstyp auswählen. Diese Methode ist verantwortlich für:
Die Knockout-Modellklasse muss die ID und den Namen haben, die zusammen mit geeigneten Standardwerten für alle anderen Eigenschaften an die create()-Methode übergeben werden. Beispiel: Bei einer Datenaktion zur Währungsumrechnung können Sie als Standardwährung die Umrechnung in Dollar festlegen. Die Standardwerte müssen im Knockout-Modell angegeben werden.
invoke(oActionContext, oDataActionContext)
Die invoke()-Methode wird aufgerufen, wenn der Benutzer die Datenaktion aus dem Kontextmenü für einen Datenpunkt in einer Visualisierung aufruft. Die Methode übergibt das DataActionContext-Argument, das Metadaten zur Beschreibung der ausgewählten Datenpunkte, der Visualisierung, der Filter, der Arbeitsmappe und der Session enthält. Siehe Serviceklassen für Datenaktionen.
validate()
Die validate()-Methode wird für jede Datenaktion aufgerufen, wenn der Benutzer im Dialogfeld "Datenaktionen" auf OK klickt. Die validate()-Methode gibt Null zurück, wenn alles gültig ist, und einen DataActionError, wenn etwas ungültig ist. Wenn ein Fehler in einer der Datenaktionen im Dialogfeld vorliegt, wird das Dialogfeld nicht geschlossen, und eine Fehlermeldung wird angezeigt. Diese Methode validiert den Namen der Datenaktion mit der this.validateName()-Methode.
getGadgetInfos(oReport)
Die getGadgetInfos()-Methode wird aufgerufen, damit die Eigenschaftsfelder der Datenaktion auf der Benutzeroberfläche angezeigt werden können. Diese Methode gibt ein Array von GadgetInfos in der Reihenfolge zurück, in der diese in der Benutzeroberfläche angezeigt werden sollen. Gadgets werden für die gängigsten Feldtypen bereitgestellt (z.B. Text, Dropdown, Kennwort, Mehrfachauswahl, Optionsfeld, Kontrollkästchen). Sie können aber auch benutzerdefinierte Gadgets für kompliziertere Felder erstellen (z.B. wenn mehrere Gadgets gruppiert werden oder je nach ausgewählter Option andere Gadgetfelder angezeigt werden sollen). Als Best Practice wird empfohlen, eine Methode zu erstellen, die jede gewünschte GadgetInfo im Array erstellt. So können potenzielle Unterklassen einfacher aus den bereitgestellten GadgetInfos wählen. Wenn Sie diese Best Practice befolgen, können Sie mehrere bereits von den verschiedenen Datenaktionsbasisklassen implementierte Methoden verwenden, die eine GadgetInfo für jedes der in ihren Benutzeroberflächen verwendeten Felder zurückgeben können. Wenn Sie auch eine dieser GadgetInfos benötigen, rufen Sie die entsprechende create****GadgetInfo()-Methode auf und übergeben den jeweiligen zurückgegebenen Wert an Ihr Gadgetarray.
isAllowedHere(oReport)
Die isAllowedHere()-Methode wird aufgerufen, wenn der Benutzer mit der rechten Maustaste auf einen Datenpunkt in einer Visualisierung klickt und die Benutzeroberfläche das Kontextmenü generiert. Wenn eine für die ausgewählten Datenpunkte relevante Datenaktion vorhanden ist, gibt diese Methode true zurück, und die Datenaktion wird im Kontextmenü angezeigt. Wenn die Methode false zurückgibt, wird die Datenaktion nicht im Kontextmenü angezeigt. Sie sollten unter Umständen das von der Superklasse geerbte Standardverhalten akzeptieren.
upgrade(oOldDataActionJS)
Verwenden Sie die upgrade(oOldDataActionJS)Methode nicht, wenn Sie Ihre erste Datenaktion erstellen. Verwenden Sie sie erst, wenn Sie das erste Knockout-Modell erstellt haben und wesentliche Änderungen an Eigenschaften für eine zweite Version des Knockout-Modells vornehmen. Beispiel: Die erste Version der Datenaktion speichert eine URL in ihrem Knockout-Modell, aber die nächste Version soll URL-Komponententeile in separaten Eigenschaften speichern (z.B. protocol, hostname, port, path, queryString und bookmark).
Die zweite Version des Knockout-Modellcodes fordert das Öffnen einer Datenaktion an, die mit der ersten Version des Knockout-Modellcodes gespeichert wurde. Das kann zu Problemen führen. Zur Behebung dieses Problems erkennt das System, dass die aktuelle Version des Datenaktionscodes neuer als die der zu öffnenden Datenaktion ist. Daher wird die upgrade()-Methode für die neue Datenaktion aufgerufen, und das Knockout-Modell der alten Datenaktion wird (als JSON-Objekt serialisiert) übergeben. Dann können Sie das neue Knockout-Modell mit dem alten JSON-Objekt auffüllen und eine upgegradete Version des JSON-Objekts zurückgeben. So wird sichergestellt, dass alte Datenaktionsmetadaten weiterhin funktionieren, wenn Sie Datenaktionscode verbessern.
HTTPAPIDataAction-Methoden
Wenn Sie die HTTPAPIDataAction-Klasse erweitern, werden die folgenden zusätzlichen Methoden bereitgestellt, die Sie eventuell außer Kraft setzen möchten:
getAJAXOptions(oDataActionContext)
Die getAJAXOptions()-Methode wird von der invoke()-Methode der Datenaktion aufgerufen. Die getAJAXOptions()-Methode erstellt das AJAX Options-Objekt, das die HTTP-Anforderung beschreibt, die Ihre Datenaktion senden soll. Das oDataActionContext-Objekt wird an die getAJAXOptions()-Methode übergeben. Dieses enthält die Metadaten für die ausgewählten Datenpunkte, die Visualisierung, die Filter, die Arbeitsmappe und die Session. Legen Sie AJAX Options wie für die zu integrierende HTTP-API erforderlich fest, und geben Sie die Funktionen an, die aufgerufen werden sollen, wenn HTTPRequest erfolgreich ist oder einen Fehler auslöst. Eine Erläuterung des jQuery.ajax-Objekts und dessen Eigenschaften finden Sie auf der JQuery-Website.
Die folgende Implementierung wird von der HTTPAPIDataAction-Klasse geerbt. Sie müssen die geerbte Methode umschreiben, um Anforderungen anzugeben. Beispiel: Bilden der HTTP-Anforderung und des Codes, der die HTTP-Antwort verarbeitet. Diese Implementierung ist nützlich, da sie die an die getAJAXOptions()-Funktion übergebenen Parameter und das erwartungsgemäß zurückgegebene Objekt sowie ein verständliches Beispiel für die Strukturierung des Codes in der Methode zeigt.
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 };