
マスカットフレームワーク 2.3.0
RELNOTES.txt - リリースノート

最終更新日: 2011/4/8

マスカットプロジェクト
http://maskat.sourceforge.jp/


 1. 概要
───────────────────────────────────

マスカットフレームワークは Web ブラウザ上で動作するリッチクライアント
アプリケーションのための実行環境および開発フレームワークです。

マスカットフレームワーク バージョン 2.3 は、バージョン 2.0 で一新した
内部アーキテクチャをベースとし、動作検証済み環境の拡充や不具合改修を
行ったマイナーバージョンアップにあたります。

この文書では、マスカットフレームワーク 2.x および 1.x の開発者向けに、
マスカットフレームワーク 2.1、2.2、2.3 における変更点を説明します。


 2. コンテナ HTML に関する変更
───────────────────────────────────

2.1 JavaScript ファイルの圧縮によるロード時間の短縮

アプリケーションの初回起動時のロード時間を短縮するため、フレームワーク
・コアやプラグインの JavaScript ファイルを圧縮しました。ファイルサイズ
は圧縮前と比較して 1/3 以下になります。

フレームワークの読み込み方法は従来と同様です。HTML 文書には maskat.js
のみを指定してください。

  ・例:
  <script type="text/javascript"
          src="path/to/maskat/core/maskat.js"></script>


2.2 非圧縮版の JavaScript ファイルの利用

圧縮済みの JavaScript ファイルはアプリケーションの性能を高める一方で、
開発中のデバッグを困難にします。このため、マスカットフレームワークでは
非圧縮版の JavaScript ファイルも同梱しています。

非圧縮版のフレームワーク・コア (maskat.js.uncompressed) を HTML 文書で
指定するとアプリケーションがデバッグモードで開始され、プラグインも非圧
縮版 (plugin.js.uncompressed) がロードされます。

  ・例:
  <script type="text/javascript"
          src="path/to/maskat/core/maskat.js.uncompressed"></script>


 3. フレームワーク・コアに関する変更
───────────────────────────────────

3.1 動作検証済みブラウザの変更

マスカットフレームワーク 2.2 では下記の Web ブラウザを動作検証済み環境
としています。

  ・Windows Internet Explorer 6, 7, 8
  ・Mozilla Firefox 3.0.15, 3.5.9
  
また、下記の Web ブラウザを動作検証済み環境から除外しました。

  ・Mozilla Firefox 1.5 (マスカットフレームワーク 2.1 にて除外)
  ・Mozilla Firefox 2.0 (マスカットフレームワーク 2.2 にて除外)


3.2 ログメッセージの改善による分析支援

マスカットフレームワーク 2.1 ではイベント処理の各段階でフレームワーク
の動作状況をログ (情報／デバッグ／トレース) に自動的に出力しています。
ログレベルの設定に従って以下の情報を得ることができます。

  ・イベント処理の開始 (INFO)
  ・コールバック関数の呼び出し (DEBUG)
  ・レイアウトから要求メッセージへのデータバインド (TRACE)
  ・要求メッセージの送信 (DEBUG)
  ・応答メッセージの受信 (DEBUG)
  ・応答メッセージからレイアウトへのデータバインド (TRACE)
  ・イベント処理の終了 (INFO)

イベント処理中にエラーが発生した場合はエラー内容がログに出力されます。
デバッグ時に正常な処理がどこまで行われており、エラーの発生個所や原因が
どこにあるのかを分析するためにログを活用してください。


3.3 window.onerror ハンドラによるエラー処理

マスカットフレームワーク 2.1 はアプリケーションの実行中に補足されない
例外が発生した場合、可能な限り window.onerror ハンドラに通知してエラー
処理を行います。

デフォルトの window.onerror ハンドラではロガーにエラーメッセージを出力
する動作を行います。アプリケーション開発者は maskat.js の読み込み後に
独自の window.onerror ハンドラを設定することで、統一的なポリシーに基づ
いてエラー処理を実装できます。

エラーハンドラの設定例を以下に示します。

  例: 独自のエラーハンドラ
  --------------------------------------------------------------------
  window.onerror = function(message, url, line) {
      alert(message + "\nURL: " + url + "\n行番号: " + line);
      return false;
  }
  --------------------------------------------------------------------


3.4 プロパティファイルの書式変更

マスカットフレームワーク 2.0 ではフレームワークインストールフォルダに
置かれた JSON 形式のプロパティファイル (properties.json) を読み込んで
フレームワーク・コアやプラグインを設定する機構が導入されました。

バージョン 2.1 ではプロパティファイルをより簡素な書式に変更しました。
プラグイン識別子ごとにキーを作成し、その内部にプラグインごとの設定値を
記述します。この変更により、フレームワーク・コアのプロパティは "core"
というプロパティキーの内部に集約されました。

以下にプロパティファイルの記述例を示します。

  例: プロパティファイル (properties.json) 
  --------------------------------------------------------------------
  {
      "core": {
          "log.default.level" : "INFO",
          "log.factory" : "maskat.log.SimpleLogFactory",
          ... (省略) ...
      },

      "compat": { "enabled": true },

      "html": { "enabled": false },

      "google": { "enabled": false, "key": "ABCDE" },

      "rialto": {
          "enabled": false,
          "isDebug": false,
          "traceLevel": 0,    
          "isTestVersion": false,
          "language": "en",
          "skin": "standart"
      },

      ... (省略) ...
  }
  --------------------------------------------------------------------

既存のアプリケーションとの後方互換性および移行のため、従来の形式のプロ
パティファイルも利用可能です。ただし、従来の形式は非推奨として廃止予定
のため、新たに開発するアプリケーションは新しい形式でプロパティファイル
を記述してください。


3.5 アプリケーションごとのプロパティの変更

同一のサーバ上で複数のアプリケーションがフレームワークを共有する場合に
すべて同じ設定値をを使用する必要がありました。マスカットフレームワーク
2.1 では HTML ファイルと同じフォルダにアプリケーションごとのプロパティ
ファイルを配置することで、フレームワーク固有のプロパティファイルの設定
値を上書きすることができます。

例えば、特定のアプリケーションのみ Google Maps 部品を使用したい場合に
HTML ファイルと同じフォルダに以下の内容を持つプロパティファイルを配置
することで、そのアプリケーションのみで Google 部品ライブラリを利用する
ことが可能です。

  例: プロパティファイル (properties.json) 
  --------------------------------------------------------------------
  {
      "google": { "enabled": true },
  }
  --------------------------------------------------------------------

ここでは、Google AJAX API を指定する "key" 属性が省略されていることに
注意してください。省略した属性はフレームワークのインストールフォルダに
格納された共通のプロパティファイルの設定値が使用されます。


3.6 レイアウトスコープの導入

マスカットフレームワークは、レイアウト定義 XML のタグで記述された部品
をインスタンス化し、name 属性で指定された名前を持つ変数へ格納します。
以前のバージョンでは変数がグローバルスコープのため、アプリケーションに
含まれるすべてのレイアウトで部品名がユニークである必要がありました。

マスカットフレームワーク 2.1.0 では、各レイアウトが独自の変数スコープ
を持つように設定可能です。この機能を利用するためには、プロパティファイ
ルを以下のように設定してください。

  例: プロパティファイル (properties.json) 
  --------------------------------------------------------------------
  {
      "core": {
          "variable.scope": "layout"
      }
  }
  --------------------------------------------------------------------
  
以前のバージョンとの互換性のため、このプロパティの既定値は "global" で
あり、変数スコープとしてグローバル変数を使用します。

スコープに格納された変数への参照は maskat.layout.Layout オブジェクトの
getVariable(name), setVariable(name, value) メソッドで取得・設定が可能
です。


3.7 変数によるラッパーオブジェクトの参照

前述のように、マスカットフレームワークはインスタンス化した部品を変数ス
コープに格納する際に、Rialto コンポーネントなどの Ajax 部品への参照を
格納していました。

マスカットフレームワーク 2.1 では、変数にマスカット部品 (ラッパー)への
参照を格納するように設定可能です。この機能を利用するためには、プロ
パティファイルを以下のように設定してください。

  例: プロパティファイル (properties.json) 
  --------------------------------------------------------------------
  {
      "core": {
          "variable.widget": "wrapped"
      }
  }
  --------------------------------------------------------------------
  
以前のバージョンとの互換性のため、このプロパティの既定値は "unwrapped"
であり、変数には Ajax 部品への参照を格納します。また、このプロパティに
"none" を設定した場合には変数を定義しません。


 4. レイアウト定義 XML に関する変更
───────────────────────────────────

4.1 メッセージリソースの外部化

レイアウト定義 XML に記述する属性値をユーザの言語設定などに応じて動的
に切り替えるため、maskat.util.Message クラスが管理するメッセージリソー
スを外部化しました。

以下の手順により、実行時にクライアント側でメッセージリソースを置換する
ことができます。

  1) メッセージリソースを JSON 形式でサーバ上に配置します。
  
  例: myapp-resources.json
  ------------------------------------------------------------
  {
      "addressLabelText" : "住所",
      "nameLabelText" : "氏名",
      "privacyAgreementText " : "個人情報の取り扱いに同意する",
      "submitButtonText" : "送信"
  }
  ------------------------------------------------------------

  2) レイアウト定義 XML のロード前に 1) で配置したメッセージリソースを
     maskat.util.Messages クラスに読み込みます。

  例: JavaScript 処理
  ------------------------------------------------------------
  maskat.util.Messages.loadTemplates("myapp-resources.json");
  ------------------------------------------------------------

  3) レイアウト定義 XML では文字列内に #{key} の形式でメッセージを参照
     することができます。例として、Rialto 部品のテキストボックスの初期
     値やボタンのタイトルの設定例を以下に示します。

  例: レイアウト定義 XML
  ------------------------------------------------------------
  <text name="nameText" left="23" top="23" width="85"
        initValue="#{nameLabelText}"/>
  <text name="addressText" left="23" top="23" width="85"
        initValue="#{addressLabelText}"/>
  <button name="remoteCalculateButton" left="23" top="107"
          title="#{submitButtonText}" />
  ------------------------------------------------------------


4.2 データバインド API のデフォルト実装

すべてのマスカット部品の親クラスにあたる maskat.layout.Widget クラスが
規定するデータバインド API (setValue, getValue メソッド) にデフォルト
実装を追加しました。

このデフォルト実装ではイベント定義 XML で source または target 要素の
teleType 属性にマスカット部品のメソッド名またはプロパティ名を指定し、
データバインドにおける値の取得・設定に利用できます。

  ・例1: Rialto 部品の日付型テキストボックスから「年」「月」「日」を
         取得し、それぞれ個別の XML ノードとして送信する
    <source obj="dateText" teleType="getYear" node="year" />
    <source obj="dateText" teleType="getMonth" node="month" />
    <source obj="dateText" teleType="getDay" node="day" />

  ・例2: Rialto 部品のボタンの "comment" プロパティに応答メッセージに
         含まれる文字列をバインドする
    <target out="myButton" teleType="comment" in="comment" />

teleType 属性を省略した場合、データバインドで使用する既定のメソッド名
もしくはプロパティ名を defaultSetter, defaultGetter プロパティを用いて
決定します。

4.3 データバインド対象の拡充

マスカットフレームワーク 2.1 では、マスカット部品、またはシンプルな
JavaScript 変数にのみデータバインドを行うことができました。
2.2 では、階層構造を有する JavaScript オブジェクト配下の変数に対して
データバインドを行うことができるようになりました。

  ・例1: user オブジェクト配下の name プロパティから値を取得する場合 
    <source obj="user.name" node="userName"/>

  ・例2: user オブジェクト配下の name プロパティに値を格納する場合 
    <target out="user.name" in="userName" />


4.4 部品の表示／非表示、有効／無効の切り替え

すべてのマスカット部品の親クラスにあたる maskat.layout.Widget クラスに
部品の表示／非表示の状態や、有効／無効の状態を切り替えるためのメソッド
を追加しました。

  ・isEnabled()
    部品が有効である場合に true を返します。
  
  ・setEnabled(enabled)
    部品の有効／無効を設定します。

  ・isVisible()
    部品が表示されている場合に true を返します。

  ・setVisible(visible)
    部品の表示／非表示を設定します。


4.4 キーイベントの処理

マスカット 2.1.0 ではキーイベントに対する処理を定義する新しい XML 文書
(キーバインド定義 XML) が導入されました。キーバインド定義 XML では特定
のレイアウトや、そのレイアウトに配置された特定の部品がフォーカスされて
いる状況に対して、キーイベント処理を定義します。

キーイベント処理はキー操作、実行タイミング、処理内容の組み合わせで指定
します。

  ・キー操作
    キー操作を表す文字列です。"CTRL+C" のように複数のキーの組み合わせ
    を指定可能です。

  ・実行タイミング
    "onkeydown", "onkeypress", "onkeyup" のいずれかのタイミングを指定
    します。デフォルトは "onkeydown" です。

  ・処理内容
    以下のいずれかの処理を実行します。また、複数の処理を指定して順番に
    実行することも可能です。
    1) フォーカスの移動 (前／後, 先頭／末尾)
    2) フォーカスの設定
    3) 部品の状態変更 (有効／無効, 表示／非表示)
    4) 部品のイベント実行
    5) JavaScript 関数の実行

以下の例では、ログインフォームのレイアウトで [Enter] キーをフォーカス
遷移に使用します。ただし、フォーカスが送信ボタンにある場合は例外として
ボタンの onclick イベントを実行します。

  例: キーイベント定義 XML
  ------------------------------------------------------------
  <?xml version="1.0" encoding="UTF-8"?>
  <keybinding layout="loginLayout">
    <default>
      <bind key="Enter">
        <move-focus type="next" />
      </bind>
    </default>

    <component id="submitButton">
      <bind key="Enter">
        <maskat-event type="onclick" target="submitButton" />
      </bind>
    </component>
  </keybinding>
  ------------------------------------------------------------

レイアウトのロード後、画面遷移定義 XML の loadKeyBinding タグを用いて
キーイベント定義 XML を読み込みます。


マスカットフレームワーク 2.0 までと同様に、部品クラスで handleKeyEvent
メソッドをオーバーライドし、部品の種類ごとのキーイベント処理を定義する
ことも可能です。


 5. イベント定義 XML に関する変更
───────────────────────────────────

5.1 コールバックインターフェースの改善

マスカットフレームワーク 2.1 ではイベント処理の各段階で呼び出される
コールバック関数のパラメータが変更されました。

  ・イベントハンドラ共通のコールバック関数 (start, finish) にはレイア
    ウト上で発生したイベントの情報が渡されます。

    ------------------------------------------------------------------
    【書式】
        function callback(event)
    【引数】
        event   : maskat.evnt.Event クラスのインスタンス。
                  レイアウト上で発生したイベントの情報を表します。
    ------------------------------------------------------------------

    マスカットフレームワーク 2.2 では、第一引数 event の arguments
    プロパティに DOM イベントハンドラの引数として渡される event 
    オブジェクトが格納されるようになりました。

  ・リモートイベントハンドラからのコールバック関数 (before, after,
    timeout) ではイベント情報に加え、リモート通信のコンテキストが渡さ
    れます。

    ------------------------------------------------------------------
    【書式】
       function(event, context)
    【引数】
        event   : maskat.evnt.Event クラスのインスタンス。
                  レイアウト上で発生したイベントの情報を表します。
        context : maskat.event.RemoteEventContext のインスタンス。
                  サーバとの HTTP 通信の状態を格納しています。
    ------------------------------------------------------------------
    
  ・通信エラー発生時 (onErrorTele) のコールバック関数ではサーバからの
    応答を XML DOM 形式で渡していましたが、他のリモートイベントからの
    コールバック関数と引数を統一しました。

    ------------------------------------------------------------------
    【書式】
       function(event, context)
    【引数】
        event   : maskat.evnt.Event クラスのインスタンス。
                  レイアウト上で発生したイベントの情報を表します。
        context : maskat.event.RemoteEventContext のインスタンス。
                  サーバとの HTTP 通信の状態を格納しています。
    ------------------------------------------------------------------

    サーバが返却した HTTP 応答が XML 形式であり、ルート要素 errors を
    持つ場合にコールバック関数が実行されます。このとき、XML を自動的に
    解析して第二引数 context の errorMessages プロパティにオブジェクト
    の配列として格納します。

    例: HTTP 応答
    ------------------------------------------------------------------
    Content-Type: application/xml 

    <?xml version="1.0" encoding="UTF-8">
    <errors>
      <error id="ERR_100">データの登録に失敗しました。</error>
      <error id="ERR_101">ID が重複しています。</error>
    </errors>
    ------------------------------------------------------------------

    ルート要素は複数の子要素 error を持つことができるため、サーバ側で
    発生した複数のエラーを通知できます。また、error 要素では任意の属性
    やテキスト要素を用いてエラーの内容を表現することができます。前述の
    XML 文書の例では以下のように context オブジェクトが設定されます。

    例: context オブジェクトに設定される内容
    ------------------------------------------------------------------
    context.errorMessages = [
        { id: "ERR_100", message: "データの登録に失敗しました。" },
        { id: "ERR_101", message: "ID が重複しています。 }
    ];
    ------------------------------------------------------------------

後方互換性のため、第一引数 event は従来のフレームワークがコールバック
関数の引数に渡していた param オブジェクトと同じプロパティを持ちます。
これらのプロパティは今後のバージョンで非推奨として廃止する予定のため、
新たに開発するアプリケーションでは新しい形式でコールバック関数を記述し
てください。


 6. 通信方式に関する変更
 
マスカットフレームワーク 2.3 では、従来の XML に加え、JSON 形式での通信に対応しました。

JSON 形式での通信を行う場合は、イベント定義 XML にて、param 要素の代わりに request を、
result の代わりに response 要素を記述します。

リクエストの場合、送信する JSON の構造を array/object/property 要素で定義します。
また、property 要素配下に widget/variable 要素を記述することで値の取得元を指定します。

  例: レイアウト定義 XML の記述例 （リクエストの場合）
  --------------------------------------------------------------------
  <request contentType="application/json" method="post">
    <array>
      <object>
        <property name="userId">
          <widget name="userIdText"/>
        </property>
      </object>
    </array>
  </request>
  --------------------------------------------------------------------

リクエストの場合、受信する JSON の構造を array/object/property 要素で定義します。
また、property 要素配下に widget/variable 要素を記述することで値の格納先を指定します。

  例: レイアウト定義 XML の記述例 （レスポンスの場合）
  --------------------------------------------------------------------
  <response contentType="application/json">
    <object>
       <property name="userId">
         <variable name="user" property="id"/>
       </property>
    </object>
  </response>
  --------------------------------------------------------------------

widget 要素を記述した場合、name 属性に指定された部品にて定義されたデフォルトの getter/setter
により値の取得／設定が実行されます。
値の取得／設定に用いる API を変更する場合は、method 要素にて部品の API を指定します。
widget/variable で取得されたオブジェクトの一部のみを対象とする場合は、property 属性にて
オブジェクト配下のプロパティ名を指定します。

なお、マスカットフレームワーク 2.3 と同時にリリースするマスカットIDE 2.3 では、JSON 形式での通信に対応し
たイベント定義 XML を出力することができません。別途、手動にてイベント定義 XML を編集する必要があります。


以上

───────────────────────────────────
Copyright(C) 2006-2011 マスカットプロジェクト
