最近では、XPagesで使用されるJavaScriptのサンプルコードも増えてきています。JavaScriptを読んで理解したり、書いたりするうえで、まずグローバルオブジェクト、Dominoオブジェクト、XSP オブジェクトを理解することはとても重要です。
ヘルプには「グローバルオブジェクトは、サーバーサイドスクリプトへのエントリポイントを提供します。 グローバルオブジェクトの名前を入力すると、そのグローバルオブジェクトがインスタンス化されます。」とあります。
グローバルオブジェクトとは、簡単に言えば、XPage 内でいつでもどこでも使えるオブジェクトです。
スコープ変数を扱う、「applicationScope」、「requestScope」、「sessionScope」、「viewScope」はわかりやすいと思います。
その他、実際のアプリケーション開発で使用されるグローバルオブジェクトで使用頻度の高いものを見ると、
- context
- currentDocument
- database
- dominoDocument1
- session
があげられます。実際、グローバルオブジェクトから派生するオブジェクトや変数が実際の開発では多く使用されます。
コンテキストを簡単に言うと、ユーザーがどのブラウザを使用しているか、そのバージョンは何か、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
データソースとして現在使用されている 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.<メソッドまたはプロパティ>
以下はその使用例のコードです。
database.getServer() //サーバー名の取得
database.getTitle() //データベースタイトルの取得
database.getURL() //データベースのURL取得
var ag = database.getAgent("YourAgent") //エージェントの取得
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」でテキストとして値の取得のみでしたが。
Domino オブジェクトライブラリは、LotusScript のバックエンドクラスと同じと考えてよいでしょう。
LotusScript でバックエンドプロセスを書き始める際に、
Dim session As New NotesSession
Dim db As NotesDatabase
Set db = session.CurrentDatabase
3 行目で現在のデータベースを取得するには、すでに SSJS では「database」というグローバルオブジェクトが用意されているのでこの「session」からデータベースを取得するコードをわざわざ書く必要はありません。
他のデータベースを参照する場合はどうでしょうか？
LotusScript では NotesSession を new していましたが、これも SSJS の中ではで他のデータベースの取得に「session」というグローバルオブジェクトが用意されていますので、new せず、そのままエントリーポイントになります。
var db:NotesDatabase = session.getDatabase("Japan/Acme", "Sales\\sales", false);
var dc:NotesDocumentCollection = db.getAllDocuments();
上のコードのように、バックエンドで処理するようなケースがあった場合、現在のデータベースの取得には、LotusScript と SSJS ではエントリーポイントが違う点が混乱しやすいので再確認してください。
特別な処理が必要なければ、データベースオブジェクト取得後には、さほど LotusScript で使用できるクラスと SSJS での Domino ライブラリ内のクラスとの違いがありませんのでコーディングに違和感を覚えることはないと思いますが、一度確認しておくとよいでしょう。