カスタムコントロール プロパティ定義にNotesDocumentを渡す方法

XPages開発でカスタムコントロールによる設計の分離を行う際、StringやBoolean意外にもNotesDocumentなどのデータソースをプロパティ定義する方法をご紹介します。

カスタムコント,ロールにデータソースを渡したい場面

そもそも、XPage本体でデータソースを定義していればNotesXSPDocument(デフォルトでは"document1"としてアクセス可)はカスタムコントロール側でも同様の方法でアクセスが可能になっています。
document1.getDocument() としてやればNotesDocumentへもアクセスが可能です。

ではNotesDocumentをカスタムコントロールに渡す必要があるシチュエーションというのはどのような場面でしょうか？

一番想定されるケースとして、ビューやRepeatコントロール内で各文書データを出力（もしくは編集）させるカスタムコントロールの作成です。

こちらにデモ用のサンプルを作ってみました。

サンプルURL： http://minato.ktrick.com/demo.nsf/ccWithNdocProperty.xsp

サンプルではテーブル内で文書がある分だけRepeatコントロールで行出力します。各文書の詳細情報として各行の下の緑のエリアがカスタムコントロールで実装している箇所です。

カスタムコントロールでデータソースをプロパティ定義

以下のようにしてカスタムコントロールでデータソースをプロパティ定義してやります。

1. カスタムコントロールを作成
2. 「Property Definition(プロパティ定義)」から「New Property(新しいプロパティ)」をクリック
3. 「Name(名前)」に任意の名前をつけます
4. 「Type（タイプ）」から右のアイコンをクリック
5. 「Data Source（データソース）」から「Domino Document（Domino文書）」を選択
6. 「Editor（エディター）」から右のアイコンをクリックし「Deta」⇒「Data Source Picker」を選択します。

以上でカスタムコントロールでデータソース定義は完了です。 ここで重要になるのは「Editor（エディター）」の部分で「Data Source Picker」を選択してやることです。

サンプルXPAGEの解説

サンプルXPageのコードからカスタムコントロールで定義したデータソースの呼び出し方、使い方をみていきます。

まずは呼び出し元になるXPageのソースコードです。

[xml highlight="29,30"]
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core"
xmlns:xc="http://www.ibm.com/xsp/custom">
<xp:this.data>
<xp:dominoView var="view1" viewName="AllContacts" />
</xp:this.data>

<xp:div style="margin:20px;">
<xp:table style="width:50%;">
<xp:tr>
<th>ID</th>
<th>First name</th>
<th>Last name</th>
</xp:tr>
<xp:repeat id="repeat1" rows="30" value="#{view1}" var="entry">
<xp:tr>
<xp:td>
<xp:text escape="true" id="computedField1" value="#{entry.Id}"></xp:text>
</xp:td>
<xp:td>
<xp:text escape="true" id="computedField2" value="#{entry.FirstName}"></xp:text>
</xp:td>
<xp:td>
<xp:text escape="true" id="computedField3" value="#{entry.LastName}"></xp:text>
</xp:td>
</xp:tr>
<xp:tr>
<xp:td colspan="3">
<xc:ccNdocProperty ndoc="#{javascript:entry.getDocument()}">
</xc:ccNdocProperty>
</xp:td>
</xp:tr>
</xp:repeat>
</xp:table>
</xp:div>
</xp:view>
[/xml]

29行目でカスタムコントロールを呼び出しています。先ほど作ったndocのプロパティにRepeatコントロールでループさせている各行の文書を設定しています。

以下はカスタムコントロールのソースコードです。

[xml highlight="4,6,9"]
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:panel style="border:5px dotted #00efef; background-color:#00dfdf; margin-left:20px; margin-bottom:20px;">
State: <xp:text escape="true" id="computedField3" value="#{compositeData.ndoc.state}"></xp:text>
<br />
City: <xp:text escape="true" id="computedField1" value="#{compositeData.ndoc.city}"></xp:text>
<br />
Email:
<xp:text escape="true" id="computedField2">
<xp:this.value><![CDATA[#{javascript:compositeData.ndoc.getItemValueString("email")}]]></xp:this.value>
</xp:text>
</xp:panel>
</xp:view>
[/xml]

4行目、6行目のようにcompositeData.ndoc.city と記述してデータソースバインディングしてやることもできますし、9行目のようにcompositeData.ndoc.getItemValueString("email") とSSJSで記述する方法も可能です。 処理速度としてはcompositeData.ndoc.xxx のデータバインディングの方が早いはずです。

サンプルXPAGEの解説

特に高度なテクニックを使っているわけではなくXPagesが持つ標準の機能の説明になりますが、意外とこのような利用方法ができることを書かれていたブログがなかったため書いてみました。 サンプルのようなシチュエーションで今回の方法を知らなければ、文書UNIDなどを渡してカスタムコントロール側で再度NotesDocumentを取得しなおす、といった回りくどい実装をしている場合もあるかもしれません。サーバー負荷、処理速度を考えてもこのように実装したほうがスマートなケースになりますので覚えておいてもらえればと思います。

by Tatsuki Kazunori

カスタムコントロール内でDocumentデータソースのフィールドを動的に定義する方法

カスタムコントロールをより汎用的なパーツ化したい

共通パーツ化の目的でカスタムコントロールを作成することが多いと思います。

今回のブログは、カスタムコントロール内で文書フィールドをハードコードせず、カスタムコントロールを呼び出し側のXPAGEがプロパティ定義でフィールド指定してやる方法です。

この方法を使うと、カスタムコントロール内で複雑なロジックを持ったフィールド、例えば

• 社内Emailアドレスのみを許可する入力チェックを行うフィールドの汎用化
• リピートコントロール内で動的にフィールドを定義してスコープ変数に格納する

といった方法が可能になります。

自分の場合はリッチテキストフィールドに対して常に素のJSONデータのみを格納するように振る舞うフィールド定義をしたいケースがあり実装した経緯がありました。その際、作成したカスタムコントロールは呼び出し側が指定したフィールド名に対して動的にデータバインドを行うようになるのが今回の主旨です、その名もダイナミック データバインディング！（勝手に呼んでますｗ）

毎度のごとく、トピックがニッチなので(笑)百聞は一見に如かず、カスタムコントロールのコードを見てみます。

まず、カスタムコントロールの前準備として今回の例では「fieldName (String値)」というプロパティ定義をしています。


以下がサンプルコードです。

[xml highlight="5"]
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">

<xp:inputText id="customEmailFld"
value="${javascript:'#{document1.' + compositeData.fieldName + '}';}">
<xp:this.validators>
<xp:validateConstraint
message="Emailが無効です。 Emailは'****@ktrick.***'の形式でなければいけません。">
<xp:this.regex><![CDATA[^[A-Za-z0-9._%-]*@ktrick.[A-Za-z]{2,4}]]></xp:this.regex>
</xp:validateConstraint>
</xp:this.validators>
</xp:inputText>

</xp:view>
[/xml]

重要な点はハイライトされている５行目に尽きます。
valueの値に対して、"${javascript:'#{document1.' + compositeData.fieldName + '}';}" と複雑な記述になっています。
まず着目してほしいのが、'#{document1.' + compositeData.fieldName + '}'の部分は文字列生成をしているということです。
もし直接データバインドをした場合、value="#{document1.Email}" となるところをあえてSSJS経由で渡してやることでこのように動的に記述することを可能にしています。

最後にこちらが呼び出し元のXPageです。
[xml highlight="4,5"]
<!--
<xp:inputText value="#{document1.Email}" id="email1"></xp:inputText>
-->
<xc:ccDynamicDataSource fieldName="Email">
</xc:ccDynamicDataSource>
[/xml]

鋭い人は「document1」がハードコードでは？と気づいたと思います。
前述のとおり'#{document1.' + compositeData.fieldName + '}'の部分は文字列を生成しているだけなのでfieldNameプロパティに「document1.Email」を指定し、'#{' + compositeData.fieldName + '}' としても動作します。

種明かしをするとなんだ～、と以外と簡単なのですが場合によってとても重宝する記述方法なので覚えておいてもらえればと思います。

参考

http://stackoverflow.com/questions/9913331/dynamic-data-binding

by Tatsuki Kazunori