slack

テクてく Lotus 技術者 Slack に参加しよう!

2011/05/30

Notes 開発者のための XPages SSJS 解説 (3)

今回は XPages 開発の JavaScript コーディングで頻繁に出てくる XSP ライブラリとバックエンドライブラリをしっかりと理解したいと思います。

XPages は LotusScript のクラスと同様、オブジェクトにはフロントエンドの文書/ビューを扱う XSP ライブラリバックエンドの文書/ビューを扱う Domino ライブラリがあります。

Domino ライブラリを使用して、現在ページ表示しているデータベースとは違う他のデータベースを参照したり、今ページ上で開いている文書以外の文書にアクセスできます。要は、ユーザーインタフェース(ページ)に見えていないものを扱います。
これに対して、フロントエンドの XSP ライブラリはヘルプで「XSP」、「Xsp」というオブジェクトの名前がついています。。XSP や Xsp という言葉を見つけたら、それはフロントエンドのオブジェクトだと思ってください。
LotusScript クラスでフロントエンドというと「UI」にあたるんですが、考え方は同様です。
ブラウザ中にまさに表示されているページで扱えるものです。Domino 文書をデータソースで使用していれば文書を、Domino ビューをページで表示していればそのビューが XSP オブジェクトとして扱えます。

(補足: ここで「XSP ライブラリ」と「XSP オブジェクト」という言葉を使用していますが、ライブラリはそれぞれのオブジェクトの集まりと理解してください。)


話をグローバルオブジェクトに戻しますが、
ヘルプでのグローバルオブジェクトおよびグローバル関数
currentDocument と dominoDocument1 のそれぞれの説明にこうあります。
currentDocument 現行コンテキストで最も近くにある文書を表す NotesXspDocument オブジェクト。
dominoDocument1 Lotus Domino 文書データソースを表す NotesXspDocument オブジェクト。
ちなみに dominoDocument1 は仮の名前で、XPage でデータソースの名前を指定しますが、そのデータソース名です。仮りに皆さんの指定したデータソース名を dominoDocument1 として説明しています。

currentDocument も dominoDocument1 も NotesXspDocument を表していることから、使用できるメソッド、プロパティはヘルプの NotesXspDocument のこちらの章になります。
メソッド、プロパティの数はそんなに多くないのでヘルプで確認してください。

NotesXspDocument ではページ上の文書アイテムの値を取得する関数が、データ型によって厳密に操作できるようになっています。LotusScript の NotesUIDocument クラスでは「FieldGetText」でテキストとして値の取得のみでしたが。


ヘルプにはサンプルのコードが少ないので、Lotus Notes and Domino Application Development wiki の「NotesXSPDocument sample JavaScript code for XPages」が役に立つと思います。



次回は Domino ライブラリを取り上げる予定です。

2011/05/26

Notes 開発者のための XPages SSJS 解説 (2)

前回は content グローバルオブジェクトを見ましたが、今回からデータベース内の文書などにアクセスするためのオブジェクトを見ていきます。

データベースオブジェクトにアクセするには、「database」オブジェクトを使用します。


まずは、Lotus Domino Designer 8.5 の「グローバルオブジェクトおよびグローバル関数」の章を見てください。
ヘルプには、

database
データソースとして現在使用されている Lotus Domino データベースを表す

とあります。
つまり、「database」は今 XPage を開いてるデータベース自体のオブジェクトということになります。LotusScript で言い換えるとこの「database」グローバルオブジェクトは LotusScript の NotesDatabase クラスが、コーディング中、初期化することなく  XPage の中で使用できるのと同じです。
Dim session As New NotesSession 
Dim db As NotesDatabase 
Set db = session.CurrentDatabase
上記のコードのように、LotusScript では現在のデータベースオブジェクトを取得するのに、NotesSession を new して CurrentDatabase で取得していましたが、XPages では直接現在のデータベースを database グローバルオブジェクトからコーディングできます。
そういった観点から LotusScript の NotesUIDatabase クラス がイベントで Source としてすぐ使用できるイメージですが、混同しやすいので、ここでは LotusScript の NotesDatabase と同じようなものだと覚えたほうが得策です。

また、JavaScript でこのオブジェクトを利用する際、
database.<メソッドまたはプロパティ>
の文法になります。メソッドは Domino オブジェクトの下の NotesDatabase オブジェクトのメソッド、プロパティが使用できます。
以下はその使用例のコードです。
database.getServer() //サーバー名の取得
database.getTitle() //データベースタイトルの取得
database.getURL() //データベースのURL取得
var ag = database.getAgent("YourAgent") //エージェントの取得

言い忘れましたが、JavaScript ではコード中の変数名、コントロール名などを厳密に大文字小文字の区別をしますので、database を Database や DATABASE などとするとビルド時あるいは実行時にエラーとなりますのでくれぐれも注意してください。

2011/05/24

Notes 開発者のための XPages SSJS 解説 (1)

4 月から今月にわたり、大阪、東京、名古屋で「Teamstudio Bootcamp for XPages」ワークショップで XPages 開発のハンズオンを実施させていただきました。ご参加いただいた皆さんには重ねて御礼申し上げます。

そのハンズオンで、サーバーサイド JavaScript (SSJS) が今ひとつよくわからないという感想をいただくことがありました。とかくハンズオンではコードの入力に忙しく、SSJS の十分な理解を得られないまま進めざるをえない状況に陥りがちです。ご参加いただいた方は、ほとんどがすでにLotusScript での開発経験がある方なので、SSJS をまったく新しい言語として覚えるよりは、LotusScript との違いや類似点に焦点をあててご説明したほうがよりご理解いただけることがわかってきました。今回は、その勘所を皆さんにもご紹介したいと思います。

私が LotusScript を覚えたときは、皆さんもそうだと思いますが、とにもかくにも Designer ヘルプをよく見ました。全てを覚えるというよりは、出てきたコードをその都度ヘルプと照らし合わせながら、またサンプルを見ながら理解するのがもっとも効率的だと思っています。ヘルプの見方を覚えるだけで、急に全容がわかるということも期待できます。

今回は「IBM Lotus Domino and Notes Information Center」のヘルプを使います。このサイトは、Domino Designer にインストールされているヘルプよりも最新の情報が最新の状態で入手できるのでブックマークしておくと便利です。


JavaScript の構文や書き方よりは、むしろグローバルオブジェクト、Domino オブジェクト、XSP オブジェクトの理解していただきたいと思います。

グローバルオブジェクト
ヘルプには「グローバルオブジェクトは、サーバーサイドスクリプトへのエントリポイントを提供します。 グローバルオブジェクトの名前を入力すると、そのグローバルオブジェクトがインスタンス化されます。」とあります。
簡単な言葉で言えば、XPage 内でいつでもどこでも使えるオブジェクト。
スコープ変数を扱う、「applicationScope」、「requestScope」、「sessionScope」、「viewScope」はわかりやすいと思います。
詳細は、Lotus Notes and Domino Application Development wiki の「XPagesのスコープ変数のタイムアウト」を参照してください。

その他、実際のアプリケーション開発で使用されるグローバルオブジェクトで使用頻度の高いものを見ると、
  • context
  • currentDocument
  • database
  • dominoDocument1
  • session

があげられます。私の経験では90%以上が、このグローバルオブジェクトから派生するオブジェクトや変数が実際の開発では使用されるのではと思っています。今回のポストから数回にわたって、このグローバルオブジェクトを解説したいと思います。
まず今回は context から。

context
ヘルプにある context の説明には「データベースサーバー、ユーザーブラウザ、およびその他のオブジェクトにアクセスできるようにする XSPContext オブジェクト。」とあります。コンテキストを簡単に言うと、ユーザーがどのブラウザを使用しているか、そのバージョンは何か、OSは何かといった Web ページを表示するうえでのユーザー環境を取得したり確認したりするため使用します。Webアプリならではのオブジェクトで、もちろんノーツクライアントアプリの作成には出てこない新しいものです。どういう使い方があるかというと、たとえば、ブラウザが FireFox か IE かによってページの表示が多少異なる場合があるかもしれません。そんな時には、この context オブジェクトからユーザーが使用するブラウザの種類を検知して、制御できます。
次は context の 3 つの使用例です。
var browser = context.getUserAgent().getBrowser(); //ブラウザの種類
var bversion = context.getUserAgent().getBrowserVersion(); //ブラウザのバージョン
var locale = context.getLocale().getDisplayName(); //言語ロケール
また context は以下のようにテーマ設計の中にブラウザの種類によって読み込む CSS ファイルを制御する際にも使われます。
 <resource rendered="#{javascript:context.getUserAgent().isIE(0, 6) == true}">

            <content-type>text/css</content-type>

            <href>blue_ie06.css</href>

      </resource>



      <resource rendered="#{javascript:context.getUserAgent().isIE(7, 8) == true}">

            <content-type>text/css</content-type>

            <href>blue_ie78.css</href>

      </resource>

ヘルプにあるとおり、
context = XSPContext
なので、この context で使用できるメソッドやプロパティは、ヘルプの
「XSP」-「 XSPContext」の中を展開すると確認できます。
XSPContext オブジェクトのメソッドやプロパティのヘルプをひとつひとつ見ていくと、
「構文」というところがあります。
構文
filterHTML(html:string) : string

filterHTML関数の後の「:」に string という戻り値の型が指定されているます。string は文字列ですが、他にも boolean、何も返さない void (実行するのみ)などいろんな型があります。
ここで注意するのは、この型指定が大文字で始まっているものは、また違うオブジェクトを参照しているので、その先のオブジェクトを利用して値の取得などを行う点が勘所です。
その他には、
getLocale は「Locale」
getTimeZone は「TimeZone」
getUrl は「XSPUrl」
getUser は「DirectoryUser」
getUserAgent は「XSPUserAgent」

テーマ設計でみた、以下のコードは context オブジェクトから getUserAgent() メソッドを呼び出しますが、ここでは終わりではなく「.」を付け XSPUserAgent オブジェクトのインスタンス参照をし isIE() メソッドでブラウザが IE の 6 以下かどうかをチェックしています。
context.getUserAgent().isIE(0, 6)


今回はグローバルオブジェクトをとりあげました。次回は、 database オブジェクトです。