はじめに
クライアント側ではもちろん、JavaScriptのプログラムを記述できますが、一般的なJavaScriptの関数などを使うことに加えて、INTER-Mediatorが稼働していれば利用できるメソッドについて、ここで解説をします。
ページ合成処理
INTERMediator.construct(targetContext)
- 解説：実際のページ合成処理は、非同期にスタートするが、並行度合いはブラウザ依存し、さらに言えば、あまりパラレル動作している感覚は薄い。なお、この呼び出しの直後のステートメントは、ページ合成終了前に呼び出されてしまうので注意が必要である。ページ合成語の処理は、INTERMediatorOnPage.doAfterConstructに記述する。
- 引数：targetContext：省略あるいはtrueで、ページファイルのすべての要素に対して合成を行う。引数にコンテキストのオブジェクト（IMLibContext）を指定すれば、そのオブジェクトに対応したエンクロージャー内部のみを合成する。
- 返り値：なし
INTERMediator.constructMain(targetContext)
- 解説：非同期処理を呼び出さないので、引き続いてページ合成を行う。
- 引数：targetContext：省略あるいはtrueで、ページファイルのすべての要素に対して合成を行う。引数にコンテキストのオブジェクト（IMLibContext）を指定すれば、そのオブジェクトに対応したエンクロージャー内部のみを合成する。
- 返り値：なし
INTERMediatorOnPage.doAfterConstruct = function() { }
ページの合成処理が終わったときに呼び出す関数を指定します。引数のない関数を代入します。INTERMediator.construct(true)でページ合成を行いますが、非同期に処理を進めるため、このステートメントの次に書かれた命令は、通常は合成途中に実行されるなど、少なくともページを作り終える前になってしまいます。ページができていないと取得できないような情報もあるので、このようなコールバックの仕組みを用意してあります。
検索条件やソート条件の追加
INTERMediator.additionalCondition = ....
コンテキストに従ってデータベースのクエリを行うとき、ここで指定した検索条件が、他の条件に対してAND条件で追加される第1引数がコンテキストのname属性値、その後にオブジェクトないしはオブジェクトの配列を指定するが、オブジェクトはfield、operator、valueのプロパティを指定し、それぞれフィールド名、演算子、値を指定する。プロパティのセッタを稼働させるために、プロパティそのものへの代入を行う必要がある。
var conditions = INTERMediator.additionalCondition;
conditions['tableName'] = {field:xxx,operator:xxx,value:xxxx};
INTERMediator.additionalCondition = conditions;
var conditions = INTERMediator.additionalCondition;
conditions['tableName']= [
{field:xxx,operator:xxx,value:xxxx},
{field:xxx,operator:xxx,value:xxxx}
];
INTERMediator.additionalCondition = conditions;INTERMediator.additionalCondition = ....
コンテキストに従ってデータベースのクエリを行うとき、ここで指定したソート条件が設定される。コンテキストのソート条件より高い優先順になっている。プロパティのセッタを稼働させるために、プロパティそのものへの代入を行う必要がある。
var sortKeys = INTERMediator.additionalSortKey;
sortKeys['tableName'] = {field:xxx,direction:xxxx};
INTERMediator.additionalSortKey = sortKeys;
var sortKeys = INTERMediator.additionalSortKey;
INTERMediator.additionalSortKey['tableName'] = [
{field:xxx,direction:xxxx},
{field:xxx,direction:xxxx}
];
INTERMediator.additionalSortKey = sortKeys;ページ合成処理に割り込む処理の記述
INTERMediatorOnPage.expandingEnclosureFinish (name,target)
INTERMediatorOnPage.《コンテキストで指定した名前》 (target)
- 引数：name：展開が終わった箇所で利用した定義ファイルのコンテキストのname属性の値
- 引数：target：展開が終わったエンクロージャのノード
- 返り値：なし
エンクロージャの展開が終わる度に呼び出されます。《コンテキストで指定した名前》は、定義ファイルのコンテキストの指定で、'post-enclosure'というキーに対応する文字列で、メソッド名を指定します。そのメソッドを上記のように定義して、プログラムを記述します。前者はすべてのコンテキスト、後者は指定したコンテキストに対しての処理のときだけに呼び出されます。実際には、ヘッダのscriptタグの要素内で、以下のように記述し、{ } 内に独自のプログラムを記述します。
INTERMediatorOnPage.expandingEnclosureFinish = function(name,target) {
:
}INTERMediatorOnPage.expandingRecordFinish(name,repeaters)
INTERMediatorOnPage.《コンテキストで指定した名前》(repeaters)
- 引数：name：展開が終わった箇所で利用した定義ファイルのコンテキストのname属性の値
- 引数：repeaters：1レコード分の展開をしたリピーターの配列
- 返り値：なし
リピータの展開時に、1レコード分の処理が終わった度に呼び出される。《コンテキストで指定した名前》は、定義ファイルのコンテキストの指定で、'post-repeater'というキーに対応する文字列で、メソッド名を指定します。そのメソッドを上記のように定義して、プログラムを記述します。前者はすべてのコンテキスト、後者は指定したコンテキストに対しての処理のときだけに呼び出されます。実際には、ヘッダのscriptタグの要素内で、以下のように記述し、{ } 内に独自のプログラムを記述します。
INTERMediatorOnPage.expandingRecordFinish = function(name,repeaters) {
:
}特定のターゲット指定を持つノードの検索
INTERMediatorOnPage.getNodeIdsHavingTargetFromNode(fromNode, imDefinition)
- 引数：fromNode：基準となるノードで、このノードより下位のノードを検索する
- 引数：imDefinition：ターゲット指定。例えば、「<input type="text" class="IM[item@unitprice]" />」については、引数に "item@unitprice" を指定する
- 返り値：ノードのid属性を示す文字列の配列
INTERMediatorOnPage.getNodeIdsHavingTargetFromRepeater(fromNode, imDefinition)
- 引数：fromNode：基準となるノードで、このノードより上位のノードを検索し最初に見つかったリピータよりも下位のノードを検索する
- 引数：imDefinition：ターゲット指定。例えば、「<input type="text" class="IM[item@unitprice]" />」については、引数に "item@unitprice" を指定する
- 返り値：ノードのid属性を示す文字列の配列
INTERMediatorOnPage.getNodeIdsHavingTargetFromEnclosure(fromNode, imDefinition)
- 引数：fromNode：基準となるノードで、このノードより上位のノードを検索し最初に見つかったエンクロージャよりも下位のノードを検索する
- 引数：imDefinition：ターゲット指定。例えば、「<input type="text" class="IM[item@unitprice]" />」については、引数に "item@unitprice" を指定する
- 返り値：ノードのid属性を示す文字列の配列
URLからパラメータを取り出す
INTERMediatorOnPage.getURLParametersAsArray()
URLの中のパラメータを取り出し、パラメータ名をキーとしたオブジェクトを返す。たとえば、「http://domain.name/page.html?a=1&b=2」というページなら、返り値は {a:1, b:2}となる。
Post Onlyモードでのメソッド
INTERMediatorOnPage.processingBeforePostOnlyContext = function(targetNode) {}
バリデーションが完了し、データベースへの書き込み前に呼び出される。falseを返すとデータベースの書き込み処理はキャンセルされる。
INTERMediatorOnPage.doAfterValidationFailure = function(node) {}
バリデーションのエラーが検知される度に呼び出される。引数nodeにはエラーのある要素への参照が設定される。
数値の書式設定
INTERMediatorLib.toNumber( str );
引数の文字列を数値に変換する
INTERMediatorLib.numberFormat( str, digit );
引数strの文字列を数値に変換し、カンマ区切りで表示する。小数点以下の桁数をdigitで指定する。
要素の値を更新する
IMLibUI.valueChange(idValue)
引数にINTER-Mediatorによって展開されたノードのid属性値を指定すると、現在の値をもってデータベース側に更新を行う。INTER-Mediatorによる自動更新をしない場合に利用するかもしれない。
- 注記：バージョン4.5でINTERMediator.valueChange(idValue)からIMLibUI.valueChange(idValue)に変更されました。
INTERMediatorクラスのプロパティ
INTERMediator.debugMode = true | false
デバッグモード（展開の過程をページの最初に表示）での実行を行う。IM_Entryの4つ目の引数でコントロールするのが手軽
INTERMediator.separator = '@'
リンク定義の区切り文字で、既定値は@
INTERMediator.defDivider = '|',
複数のリンク定義がある場合の区切り文字で、既定値は |
INTERMediator.defaultTargetInnerHTML = true
リンク設定のターゲット指定がない場合、既定値はテキストノードを作成して下位のノードとする。ここにtrueを指定すると、ターゲット指定がない場合にはinnerHTMLに代入する
INTERMediator.navigationLabel = ...
ナビゲーションのカスタマイズ（別項目で詳細を解説）
INTERMediator.titleAsLinkInfo = true;
titile属性の内容をリンク設定として解釈する。既定値はtrue
INTERMediator.classAsLinkInfo = false;
class属性にあるIM[ ] でかこった箇所をリンク設定として解釈する。既定値はtrue
エラーメッセージ、デバッグメッセージ
INTERMediator.setDebugMessage(message, level)
でバッグメッセージを設定する。引数messageが実際のメッセージで、levelはそのレベル。定義ファイルでのIM_Entry関数の4つ目の引数の数値より低いレベルのデバッグメッセージが画面あるいはコンソールに表示される。
INTERMediator.setErrorMessage(ex, moreMessage)
単にエラーメッセージを表示するだけなら第1引数に文字列を指定するだけでよい。フレームワーク内では、exにExceptionクラスのオブジェクト、第2引数に付加的なメッセージを設定している。
INTERMediator.flushMessage()
エラーメッセージやデバッグメッセージを表示する
バリデーション処理後に呼び出される関数
INTERMediatorOnPage.doAfterValidationSucceed(target,linkInfo)
バリデーションの設定がされていて、ルールの結果がtrueとなった直後に呼び出される。引数targetは調べたノードへの参照、linkInfoは対照となったリンク定義の文字列が得られる
INTERMediatorOnPage.doAfterValidationFailure(target,linkInfo)
バリデーションの設定がされていて、ルールの結果がfalseとなった直後に呼び出される。引数targetは調べたノードへの参照、linkInfoは対照となったリンク定義の文字列が得られる。テキストフィールドの値をもとにして計算処理をしている場合、間違えた値で再計算をしてしまっているかもしれないが、この関数は、元の値に戻された後に呼び出されるので、さらに再計算などを組み込むことができる。
ローカルコンテキスト
IMLibLocalContext.clearAll()
ローカルコンテキストのオブジェクトを初期化して、記録された内容をクリアする
IMLibLocalContext.setValue(key, value)
指定したキーで値を保存する
IMLibLocalContext.getValue(key)
指定したキーの値を取り出す
IMLibLocalContext.archive()
ローカルコンテキストの内容をセッションストレージ（またはクッキー）に記録する
IMLibLocalContext.unarchive()
セッションストレージ（またはクッキー）に記録したデータからローカルコンテキストを復元する
IMLibLocalContext.update(idValue)
引数に指定したid属性値のノードがローカルコンテキストにバインドされていれば、その要素の値をコンテキストに反映させる。通常はchangeイベントで自動的にコンテキストに値が設定されるが、changeイベント以外での動作時に利用する必要が出る
コンテキストオブジェクト
IMLibContextクラスのオブジェクトに対するメソッドは以下の通りです。通常は、new IMLibContext(contextName)で生成された結果を使っています。《IMLibContext》は、IMLibContextクラスのインスタンスを示します。
《IMLibContext》.contextName
コンテキスト名
《IMLibContext》.enclosureNode
エンクロージャーの要素への参照
《IMLibContext》.setValue(recKey, key, value, nodeId, target)
コンテキストに値valueを設定する。キーとしてはrecKey（id=34、つまり主キーとイコール、その値を合成した文字列）およびkey（フィールド名）を指定する。最初は要素のid属性値nodeIdを伴ってい指定され、id属性値とターゲット指定targetで決定されるページ内のノードと、データベースの値の対応関係を記録する。nodeIdを省略すると、値を保存すると同時に、他のコンテキストの同じテーブルの同じレコードの同じフィールドとバインドしている値も更新し、要素に表示する値も更新する。
《IMLibContext》.getValue(recKey, key)
2種類のキーを指定して値を取り出す
《IMLibContext》.getContextInfo(nodeId, target)
要素のid属性値とターゲットから、コンテキスト情報（{context: this, record: recKey, field: key}形式のオブジェクト）を得る。コンテキスト名とフィールド名だけのターゲットの場合は、"" を指定する
《IMLibContext》.getContextValue(nodeId, target)
要素のid属性値とターゲットから、コンテキストでの値を得る
IMLibContextPool.poolingContexts
IMLibContextPoolは複数のコンテキストを管理するオブジェクト。このプロパティは配列で、管理しているそれぞれのIMLibContextクラスのオブジェクトが要素として記録されている
IMLibContextPool.getContextInfoFromId(idValue, target)
要素のid属性値とターゲットから、コンテキスト情報（{context: this, record: recKey, field: key}形式のオブジェクト）を得る。コンテキストをまたいで検索する
IMLibContextPool.updateContext(idValue, target)
id属性値とターゲットで示す要素の現在の値を、対応するコンテキストに書き込む
IMLibContextPool.contextFromEnclosureId(idValue)
指定したid属性を持つ要素がエンクロージャーのコンテキストオブジェクトを返す
IMLibContextPool.contextFromName(cName)
コンテキスト名からコンテキストを返すが、最初のコンテキストオブジェクトのみが返される
イベント対応
IMLibMouseEventDispatch.setExecute(idValue, exec)
指定したid属性値の要素に対してclickイベントが発生したときにexecに指定した関数が実行されるようにする
IMLibMouseEventDispatch.setTargetExecute(targetValue, exec)
指定したターゲット指定の要素に対してclickイベントが発生したときにexecに指定した関数が実行されるようにする
IMLibKeyEventDispatch.setExecute(idValue, charCode, exec)
指定したid属性値の要素に対して、charCodeのキーを押したことによるkeydonwイベントが発生したときにexecに指定した関数が実行されるようにする
クライアントからの直接的なデータベース処理
INTER-Mediatorは、INPUT、SELECT、TEXTAREAタグ要素を編集してフォーカスを離れる時（つまり、onchangeイベントを受けて）、自動的にデータを書き戻すようにしています。しかしながら、データベースの読み書きの処理はこれだけでは足りないと思われます。たとえば、DIVタグ要素をドラッグできるようにして、ドラッグ先の座標をデータベースに書き戻すようなことをしたいと思うかもしれません。その場合、イベント処理関数で、ノードの属性やスタイルの値を取り出して、データベース処理を自前でやりたくなります。そのために、以下のように、CRUDに対応した4つの関数を用意してあります。
なお、認証を必要とする状況では、別途WithAuthという名前が付加されたメソッドが用意されています。引数argは通常のメソッドと同じですが、引数completionには認証が成功した後に実行されるプログラムを関数リテラルの形式で与えておくことができます。
INTERMediator_DBAdapter.db_query(args)
INTERMediator_DBAdapter.db_queryWithAuth(args, completion)
データベースからの取り出しを行います。関数の返り値は1レコードがオブジェクトとなった配列です。
| 属性 | 指定する値 |
|---|---|
| name | 定義ファイルのIM_Entry関数の第1引数に指定する配列のname属性の値 |
| records | 取り出すレコードの数（レコード数の上限） |
| fields | 取り出すフィールドの名前の配列（現在はすべて*でアクセスしており無視される） |
| parentkeyvalue | 外部キーフィールドの値 |
| conditions | {field:xx, operator:xx, value:xx} の形式のオブジェクトの配列。検索条件をANDで追加する |
| useoffset | trueならオフセットの値を利用する。falseなら利用しない |
INTERMediator_DBAdapter.db_update(args)
INTERMediator_DBAdapter.db_updateWithAuth(args, completion)
データベースのレコードの更新を行います。
| 属性 | 指定する値 |
|---|---|
| name | 定義ファイルのIM_Entry関数の第1引数に指定する配列のname属性の値 |
| conditions | {field:xx, operator:xx, value:xx} の形式のオブジェクトの配列。検索条件をANDで追加する |
| dataset | {field:xx, value:xx}の形式のオブジェクトの配列。設定するフィールドとその値を指定する |
INTERMediator_DBAdapter.db_delete(args)
INTERMediator_DBAdapter.db_deleteWithAuth(args, completion)
データベースのレコード削除を行います。
| 属性 | 指定する値 |
|---|---|
| name | 定義ファイルのIM_Entry関数の第1引数に指定する配列のname属性の値 |
| conditions | {field:xx, operator:xx, value:xx} の形式のオブジェクトの配列。検索条件をANDで追加する |
INTERMediator_DBAdapter.db_createRecord(args)
INTERMediator_DBAdapter.db_createRecordWithAuth(args, completion)
データベースに新しいレコードを作成します。関数の返り値は、作成したレコードのキーフィールドの値です。
| 属性 | 指定する値 |
|---|---|
| name | 定義ファイルのIM_Entry関数の第1引数に指定する配列のname属性の値 |
| dataset | {field:xx, value:xx} の形式のオブジェクトの配列。新しいレコードに対して指定フィールドに値を設定する |
非同期通信によるネットワーク処理
以下のメソッドはいずれも、ネットワーク処理を非同期で行います。通信のためのパラメータは、argsに指定します。それぞれ、直前に示した、同期通信の対応するAPIと同じように、argsを指定します。successProcとfailProcはそれぞれ、通信が成功した時、エラーが発生した時に呼び出されるメソッドを指定します。何もしないなら、nullを指定します。通信処理は非同期で実行されるため、これらのメソッドの直後にステートメントは、通常は通信終了前に実施されるでしょう。原則として、このメソッド以降はプログラムを何も書かない、つまり、一連の処理がこのメソッドの呼出で終わるように記述する必要があります。これらのメソッドは認証が必要な場合でも、不要な場合でも利用されます。認証が必要な場合、認証が失敗すると、繰り返しログインパネルが表示する仕組みも組み込んであります。
INTERMediator_DBAdapter.db_query_async(args, successProc, failProc)
INTERMediator_DBAdapter.db_update_async(args, successProc, failProc)
INTERMediator_DBAdapter.db_delete_async(args, successProc, failProc)
INTERMediator_DBAdapter.db_createRecord_async(args, successProc, failProc)
INTERMediator_DBAdapter.db_copy_async(args, successProc, failProc)
通信が失敗した時に呼び出されるfailProcの関数は引数がありません。成功した時に呼び出されるメソッドは、引数が1つあり、通信結果を含むオブジェクトを引数で得られます。そのオブジェクトは、以下のプロパティを持っています。このsuccessProcに、通信結果をもとにした処理を記述することが可能です。
| プロパティ | 内容 |
|---|---|
| dbresult | 検索結果あるいは処理したレコードを示すオブジェクトの配列 |
| resultCount | 検索あるいは処理したレコード数 |
| totalCount | 現在の検索条件で得られる総レコード数 |
| newRecordKeyValue | 新しいレコードを作ったり複製をした時、新しいレコードのキーフィールドの値 |
| newPasswordResult | パスワードの変更が成功したかどうかを示す論理値 |
| registeredId | クライアント間連携で利用する登録ID |
| nullAcceptable | フィールドの値にnullが許可されているかどうか |
IMLibQueue.setTask(function(completeTask){...})
INTER-Mediator内部での更新処理のためのサーバーへの通信は、全てキューに投入して処理されます。これにより、更新処理が複数同時に稼働してしまう問題を避けることができます。独自にJavaScriptでプログラムを組む時、非同期通信を上記のメソッドで実装する場合、通信処理自体をこのメソッドでキューへ登録するのが確実です。引数の関数の処理ブロック内で、非同期通信処理を呼び出します。なお、関数の引数はキューを終了することを示すためのクロージャーが設定されて呼び出されます。通信処理後などに「completeTask();」のように呼び出しを記述する必要があります。これが呼び出されないと、次のキューの処理に移行しません。