オーバーライドするデータ・アクションの継承メソッドの選択

各データ・アクションは、適切に動作するために様々なメソッドを実装する必要があるため、変更して使用できる動作を実装しているメソッドをオーバーライドすることになります。

汎用メソッド

HTTPAPIDataActionなどの具象データ・アクション・クラスのいずれかを拡張する場合、必要なメソッドのほとんどはすでに実装されており、変更して使用できる動作を実装しているメソッドをオーバーライドするだけで済みます。

この項では、様々なメソッドとその予期される動作について説明します。

すべてのタイプのデータ・アクションは、ここで説明されているメソッドを実装する必要があります。

create(sID, sName)

create()静的メソッドは、新しいデータ・アクションを作成してドロップダウン・メニューからデータ・アクション・タイプを選択したときにコールされます。このメソッドの役割は次のとおりです:

  • データ・アクションで使用するKnockoutモデル・クラスの構築。

    Knockoutモデル・クラスには、他のすべてのプロパティにとって意味のあるデフォルト値とともにcreate()メソッドに渡されるIDと名前が含まれる必要があります。たとえば、通貨換算データ・アクションでは、ドルに換算するデフォルト通貨を設定できます。Knockoutモデルは、デフォルト値を提供するための適切な場所です。

  • Knockoutモデルからのデータ・アクションのインスタンスの構築。
  • データ・アクションのインスタンスの返却。

invoke(oActionContext, oDataActionContext)

invoke()メソッドは、ビジュアライゼーションのデータ・ポイントのコンテキスト・メニューからユーザーがデータ・アクションを起動したときにコールされます。このメソッドは、選択されたデータ・ポイント、ビジュアライゼーション、フィルタ、ワークブックおよびセッションを記述したメタデータを含むDataActionContext引数を渡します。「データ・アクション・サービス・クラス」を参照してください。

validate()

validate()メソッドは、「データ・アクション」ダイアログでユーザーが「OK」をクリックしたときに各データ・アクションでコールされます。validate()メソッドは、すべてが有効であることを示す場合はnullを返し、何かが無効である場合はDataActionErrorを返します。ダイアログでいずれかのデータ・アクションにエラーが発生した場合、ダイアログは閉じられず、ユーザーにエラー・メッセージが表示されます。このメソッドは、this.validateName()メソッドを使用してデータ・アクションの名前を検証します。

getGadgetInfos(oReport)

getGadgetInfos()メソッドは、ユーザー・インタフェースでデータ・アクション・プロパティ・フィールドを表示できるようにするためにコールされます。このメソッドは、ユーザーが希望するユーザー・インタフェースへの表示順序でGadgetInfosの配列を返します。ガジェットは、最も一般的なタイプのすべてのフィールドに対して提供されますが(たとえば、テキスト、ドロップダウン、パスワード、複数選択、ラジオ・ボタン、チェック・ボックスなど)、より複雑なフィールドが必要な場合はカスタム・ガジェットを作成できます(たとえば、複数のガジェットをまとめてグループ化する場合や、ユーザーの選択したオプションに応じて異なるガジェット・フィールドを表示する場合など)。配列で必要な各GadgetInfoを構築するメソッドを作成する方が、後でサブクラスがその提供されたGadgetInfoから選択しやすくなるため、ベスト・プラクティスです。このベスト・プラクティスに従う場合、ユーザー・インタフェースで使用されるフィールドごとにGadgetInfoを返すことができる各種データ・アクション・ベース・クラスによって実装された様々なメソッドがすでに用意されています。また、これらのGadgetInfoのいずれかが必要な場合、対応するcreate****GadgetInfo()メソッドをコールして、その戻り値をガジェットの配列に配置します。

isAllowedHere(oReport)

isAllowedHere()メソッドは、ユーザーがビジュアライゼーションのデータ・ポイントを右クリックし、ユーザー・インタフェースがコンテキスト・メニューの生成を開始したときにコールされます。選択されたデータ・ポイントに関連するデータ・アクションが存在する場合、メソッドはtrueを返し、そのデータ・アクションがコンテキスト・メニューに表示されます。メソッドがfalseを返した場合、データ・アクションはコンテキスト・メニューに表示されません。スーパークラスから継承したデフォルト動作を受け入れることを検討してください。

upgrade(oOldDataActionJS)

最初のデータ・アクションを作成する場合、upgrade(oOldDataActionJS)メソッドを使用しないでください。このメソッドは、最初のKnockoutモデルの作成後に、第2バージョンのKnockoutモデルのプロパティを大幅に変更する場合にのみ使用してください。たとえば、最初のバージョンのデータ・アクションではそのKnockoutモデルにURLを格納するが、次のバージョンでは別個のプロパティにURLコンポーネント部分を格納する予定の場合です(たとえば、protocolhostnameportpathqueryStringbookmarkなど)。

第2バージョンのKnockoutモデル・コードは、問題が発生する可能性のある最初のバージョンのKnockoutモデル・コードに保存されているデータ・アクションを開こうとする場合があります。この問題を解決するため、システムでは、現在のデータ・アクション・コードのバージョンが、開かれようとしているデータ・アクションのバージョンより新しいことを認識すると、新しいデータ・アクション・クラスのupgrade()メソッドをコールして、古いデータ・アクションのKnockoutモデル(JSONオブジェクトにシリアライズ済)を渡します。その後、古いJSONオブジェクトを使用して新しいKnockoutモデルに移入し、JSONオブジェクトのアップグレード・バージョンを返すことができます。これにより、データ・アクション・コードを改善しても、古いデータ・アクション・メタデータは動作し続けることが保証されます。

HTTPAPIDataActionメソッド

HTTPAPIDataActionクラスを拡張する場合、オーバーライドできる次の追加メソッドが用意されています:

getAJAXOptions(oDataActionContext)

getAJAXOptions()メソッドは、データ・アクションのinvoke()メソッドによってコールされます。getAJAXOptions()メソッドは、データ・アクションで作成されるHTTPリクエストを記述したAJAX Optionsオブジェクトを作成します。getAJAXOptions()メソッドには、選択されたデータ・ポイント、ビジュアライゼーション、フィルタ、ワークブックおよびセッションを記述したメタデータを含むoDataActionContextオブジェクトが渡されます。統合しようとしているHTTP APIの要件どおりにAJAX Optionsを設定し、HTTPRequestが成功するかエラーで終了した場合にコールする関数を指定します。jQuery.ajaxオブジェクトとそのプロパティの説明は、JQueryのWebサイトを参照してください。

次の実装は、HTTPAPIDataActionクラスから継承されています。継承メソッドをリライトして要件を指定する必要があります。たとえば、HTTPリクエストと、HTTPレスポンスを処理するコードを構成します。この実装は、getAJAXOptions()関数に渡されるパラメータ、返されることが予期されるオブジェクト、およびメソッド内でコードを構成する方法の明確な例を示しているため、役に立ちます。

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 };