ポップアップ・ウィンドウとダイアログ

この章では、メイン・アプリケーションのページの上にコンテンツを “ポップアップ” 表示する Zen コンポーネントについて説明します。これらのコンポーネントにより得られる柔軟性と引き換えに、これらのコンポーネントを有効にするために、ページ・クラスでより多くのプログラミング作業が必要になります。この章では、以下のコンポーネントについて説明します。

“モーダル・グループ” — ユーザ・イベントに応答して、HTML コンテンツを表示します。
“ポップアップ・ウィンドウ” — Zen ページなどの任意のコンテンツを新しいウィンドウでポップアップ表示します。
“ダイアログ” — ユーザ入力の要求や受け入れのためのダイアログをポップアップ表示します。

モーダル・グループ

モーダル・グループは特別なグループ・コンポーネントで、通常はコンテンツは表示されていません。モーダル・グループが表示状態になると、ユーザ・イベントを受け取るのはこのグループのコンテンツのみになります。モーダル・グループ外部でマウスのクリックなどの何らかのイベントが発生すると、自動的にこのモーダル・グループは非表示になります。Zen では、ドロップダウン・メニューやドロップダウン combobox コントロールを作成する際、このモーダル・メカニズムを使用します。このメカニズムは、ポップアップ項目にも使用できます。

モーダル・グループのコンテンツを定義するには、<modalGroup> コンポーネントをページ・クラスに配置するか、プログラム処理で %ZEN.Component.modalGroupOpens in a new tab クラスのインスタンスを作成します。これには以下の 3 つのオプションがあります。

“静的” — <modalGroup> コンポーネントをページ・クラスの XData Contents ブロックに配置します。ページ上のクライアント側メソッドが modalGroup show メソッドを呼び出すまで、コンテンツは非表示のままになります。
“動的” — ページで createComponent メソッドを呼び出し、modalGroup コンポーネントを動的に作成するようにします。コンポーネントをグループに追加します。そのコンポーネントを表示するには、modalGroup の show メソッドを呼び出します。
“組み込み” — ページで modalGroup の show メソッドを呼び出し、組み込みモーダル・グループの "msgBox" または "calendar" のいずれかを表示するようにします。

現在のモーダル・グループを閉じるには、ページで endModal メソッドを呼び出す必要があります。通常、endModal は、モーダル・グループにあるいずれかのボタン ([OK]、[キャンセル] など) のイベント・ハンドラでトリガされます。モーダル・グループが表示されていないときに endModal を呼び出すとエラーになります。

モーダル・グループに編集フォーカスがある間は、キーボード・コントロールは無効になります。例えば、Tab キーを使用してモーダル・グループ内のフィールド間を移動することはできません。これにより、モーダル・グループにフォーカスがあるにもかかわらず、誤って Tab キーを押して、すべてのフィールド間を移動し、ページに戻ってしまうことがなくなります。ユーザがモーダル・グループの外部をクリックするか、モーダル・グループを閉じるよう設定されているボタンをクリックするまで、モーダル・グループのフォーカスが保持されます。

Note:

Internet Explorer (IE) のみ：モーダル・グループを表示すると、すべての <embed> 要素のコンテンツ、つまり SVG コンテンツは非表示になります。この理由は、IE では <embed> 要素の zindex 設定が無視されるからです。

モーダル・グループ内のコンポーネントの動作をカスタマイズするには、そのコンポーネントの次のモーダル・コールバック・メソッドを変更します。

onStartModalHandler(zindex) — このメソッドが存在する場合は、このコンポーネントがモーダル状態になろうとしていることが通知される際にこのメソッドが発行されます。つまり、このコンポーネントはディスプレイの最前面に配置されます。呼び出し元は、ブラウザで現在表示されている他のすべてのコンポーネントより前面にこのコンポーネントが配置されることを保証するのに十分な大きさの zindex 値を提供します。
onEndModalHandler(zindex) — このメソッドが存在する場合は、このコンポーネントがモーダル状態から脱しようとしていることが通知される際にこのメソッドが発行されます。つまり、このコンポーネントはディスプレイの最前面に配置されなくなります。呼び出し元は、ブラウザで表示されている他のコンポーネントを基準にした標準層にこのコンポーネントが戻ることを保証するのに十分な小ささの zindex 値を提供します。

静的なモーダル・グループ

静的モードでは、モーダル・グループは XML 文を使用してページ・クラスの XData Contents ブロック内で定義されます。このグループのコンテンツは、モーダル・グループ・コンポーネントの show メソッドが呼び出されるまで非表示になり、呼び出されるとポップアップ・ウィンドウに表示されます。

これをページ・クラスで設定するには、以下の手順を実行します。

<modalGroup> 定義を XData Contents の <page> 内で指定します。以下はその例です。

<modalGroup id="mgStatic" groupTitle="Popup">
  <text id="mgText" label="Value:" />
  <button id="mgButton" caption="OK" onclick="zenPage.mgBtnClick();"/>
</modalGroup>

モーダル・グループを表示するクライアント側メソッドを指定します。次に例を示します。
```
ClientMethod modalGroupStatic() [ Language = javascript ]
{
  var group = this.getComponentById('mgStatic');
  group.show();
}
```
このメソッドは、以下のように動作します。
- <modalGroup> の id 値を指定して getComponentById を呼び出し、<page> の <modalGroup> を探します。
- クライアント側 show メソッドを呼び出します。show に必要なすべての情報は <modalGroup> 定義で指定されるので、引数は不要です。
<page> 内の任意の場所で、modalGroupStatic メソッドを呼び出してモーダル・グループを表示するメカニズムをユーザに示す必要があります。以下は、ボタンを使用する例です。
```
<button caption="Enter a New Value"
        onclick="zenPage.modalGroupStatic();"
        title="Display a modal group using a static definition." />
```

次のように、テストを目的として <page> にポップアップからのデータをエコーするフィールドを指定できます。

<html id="mgHtml">No data entered yet. </html>

ページの XData Contents ブロックは次のようになります。

<page xmlns="http://www.intersystems.com/zen"
      xmlns:demo="http://www.intersystems.com/zendemo" height="100%">
  <html id="mgHtml">No data entered yet. </html>
  <button caption="Enter a New Value"
          onclick="zenPage.modalGroupStatic();"
          title="Display a modal group using a static definition." />
  <modalGroup id="mgStatic" groupTitle="Popup">
    <text id="mgText" label="Value:" />
    <button id="mgButton" caption="OK" onclick="zenPage.mgBtnClick();"/>
  </modalGroup>
</page>

ユーザに、ポップアップを閉じるメカニズムを示す必要があります。さらに、ポップアップでユーザに値の入力を求める場合は、その値を取得し、使用する必要があります。これは、ページ・クラスの以下のクライアント側メソッドで実行します。
```
ClientMethod mgBtnClick() [ Language = javascript ]
{
  // get value from text field
  var ctrl = zen('mgText');

  // write user value into HTML component
  zenSetProp('mgHtml','content','User entered: ' + ctrl.getValue());

  // hide the modal group
  zenPage.endModal();
}
```
このメソッドは、以下のように動作します。
- ポップアップでユーザが [OK] をクリックすると、実行されます。これが動作する理由は、手順 1 でこのメソッドを <modalGroup> の <button> に対する onclick イベント・ハンドラとして指定したからです。
- <text> の id 値を指定して JavaScript 関数 zen を呼び出すことで、<modalGroup> の <text> コントロールを探します。
- getValue を呼び出して、<text> コントロールに入力された値を取得します。
- <html> の id 値を指定して JavaScript ユーティリティ関数 zenSetProp() を呼び出すことで、<page> 上の <html> コンポーネントを探して、<html> コンポーネントの content プロパティを設定します。新しい <html> の content 値は、リテラル文字列と新たに取得した <text> 値を連結したものになります。
- ページの endModal メソッドを呼び出して、ポップアップを閉じます。

ユーザは、このサンプル・ページを以下のように使用できます。

まず最初に、ユーザに対して以下のように表示されます。
このページのボタンをクリックすると、modalGroupStatic メソッドが呼び出されます。これにより、メイン・ページの前にポップアップ・ウィンドウが表示されます。このポップアップのコンテンツは、<modalGroup> のコンテンツです。このポップアップのタイトルは、<modalGroup> の groupTitle のテキストです。
以下の図では、ユーザがポップアップの <text> コントロールに値を入力しています。
このポップアップの [OK] ボタンをクリックすると、mgBtnClick メソッドが呼び出されます。これによりポップアップが閉じ、<page> の <html> コンポーネントのコンテンツが、ユーザの入力内容を反映して以下のように変更されます。

上記の例は、SAMPLES ネームスペースのクラス ZENDemo.MethodTestOpens in a new tab にあるものに似ています。このサンプルを試すには、Zen デモのメイン・ページで、[ホーム]→[概要]→[メソッド]→[モーダル・グループ：静的] の順に選択します。始めるには、"Zen の使用法" の “Zen の概要” の章で説明している “Zen デモ” を参照してください。

動的なモーダル・グループ

動的モードでは、クライアント側 JavaScript メソッドの createComponent、addChild、および setProperty を呼び出すプログラム処理によって、ページでモーダル・グループ・コンポーネントを作成します。このシーケンスは、適切な引数で modalGroup show メソッドを呼び出すと終了します。

これをページ・クラスで設定するには、以下の手順を実行します。

モーダル・グループを表示するクライアント側メソッドを指定します。次に例を示します。
```
ClientMethod modalGroupDynamic() [ Language = javascript ]
{
  // create a modal group
  var group = this.createComponent('modalGroup');

  // add components dynamically
  var col = this.createComponent('colorPicker');
  group.addChild(col);
  col.setProperty('id','myCol');

  var radio = this.createComponent('radioSet'); 
  radio.setProperty('id','myRadio'); 
  group.addChild(radio); 

  zenPage.addChild(group);
  zenPage.refreshContents(true);
  radio.setProperty('valueList','elm,maple,oak'); 

  var btn = this.createComponent('button'); 
  group.addChild(btn); 
  btn.setProperty('caption','Save'); 
  btn.setProperty('onclick','zenPage.btnClick();'); 

  // Show the group in "dynamic" mode. 
  zenPage.refreshContents(true); 
  group.show();
}
```
このメソッドは、以下のように動作します。
- ページの createComponent メソッドを呼び出して、modalGroup コンポーネントを追加します。
- colorPicker をグループに追加します。
  - ページの createComponent メソッドを呼び出して、colorPicker コントロールを作成します。
  - モーダル・グループの addChild メソッドを呼び出して、colorPicker をグループに追加します。
  - カラー・ピッカの setProperty メソッドを呼び出して、colorPicker に id 値を指定します。
- 同様に radioSet をグループに追加します。
- 同様に button をグループに追加します。
- ボタンの setProperty メソッドを呼び出して、その onclick 値を、このボタンをユーザがクリックしたときに実行されるクライアント側メソッドの名前に設定します。
- 以下の引数でモーダル・グループの show メソッドを呼び出します。
  - ポップアップ・ウィンドウのタイトル
  - キーワード 'dynamic'
  - 引数の位置 3、4、および 5 が null であるキーワード
  - オプションの幅の値 '236'
  引数の詳細は、この章の “show メソッド” を参照してください。
<page> 内の任意の場所で、modalGroupDynamic メソッドを呼び出してモーダル・グループを表示するメカニズムをユーザに示す必要があります。以下は、ボタンを使用する例です。
```
<button caption="Choose Plantings"
        onclick="zenPage.modalGroupDynamic();"
        title="Display a modal group using a dynamic definition." />
```

次のように、テストを目的として <page> にポップアップからのデータをエコーするフィールドを指定できます。

<html id="mgHtml">No data entered yet. </html>

ページの XData Contents ブロックは次のようになります。

<page xmlns="http://www.intersystems.com/zen"
      xmlns:demo="http://www.intersystems.com/zendemo" height="100%">
  <html id="mgHtml">No data entered yet. </html>
  <button caption="Choose Plantings"
          onclick="zenPage.modalGroupDynamic();"
          title="Display a modal group using a dynamic definition." />
</page>

ユーザに、ポップアップを閉じるメカニズムを示す必要があります。さらに、ポップアップでユーザに値の入力を求める場合は、その値を取得し、使用する必要があります。これは、ページ・クラスの以下のクライアント側メソッドで実行します。
```
ClientMethod btnClick() [ Language = javascript ]
{
  // get values from controls
  var col = zen('myCol');
  var radio = zen('myRadio');

  // write user values into HTML component
  zenSetProp('mgHtml','content','User entered: ' +
                    col.getValue() + ' ' + radio.getValue());

  // hide the modal group
  zenPage.endModal();
}
```
このメソッドは、以下のように動作します。
- ポップアップでユーザが [保存] をクリックすると、実行されます。これが動作する理由は、手順 1 でこのメソッドをモーダル・グループの [保存] ボタンに対する onclick イベント・ハンドラとして指定したからです。
- 検索対象コントロールの id 値を指定して JavaScript ユーティリティ関数 zen() を呼び出すことで、カラー・ピッカ・コントロールとラジオ・セット・コントロールを探します。
- <html> の id 値を指定して JavaScript ユーティリティ関数 zenSetProp() を呼び出すことで、<page> 上の <html> コンポーネントを探して、<html> コンポーネントの content プロパティを設定します。新しい <html> の content 値は、リテラル文字列と、getValue() を使用して取得したカラー・ピッカ値とラジオ・セット値を連結したものになります。
- ページの endModal() メソッドを呼び出して、ポップアップを閉じます。

ユーザは、このサンプル・ページを以下のように使用できます。

まず最初に、ユーザに対して以下のように表示されます。
このページのボタンをクリックすると、modalGroupDynamic メソッドが呼び出されます。これにより、メイン・ページの前にポップアップ・ウィンドウが表示されます。このポップアップのコンテンツは、modalGroupDynamic で追加した子コンポーネントです。このポップアップのタイトルは、modalGroupDynamic が show メソッドに渡した最初の引数です。
以下の図では、ユーザが色とラジオ・ボタンをクリックしています。
このポップアップの [保存] ボタンをクリックすると、btnClick メソッドが呼び出されます。これによりポップアップが閉じ、<page> の <html> コンポーネントのコンテンツが、以下のように変更されます。

組み込みモーダル・グループ

組み込みモードでは、組み込みモーダル・グループの 1 つが、Zen で動的に作成され、表示されます。このオプションは、動的なモーダル・グループの手順よりもはるかに簡単です。組み込みモーダル・グループには以下の 2 つのオプションがあります。

"calendar" — 組み込み“カレンダー・ボックス” を表示します。
"msgBox" — 組み込み“メッセージ・ボックス” を表示します。

カレンダー

以下の手順では、Zen ページ・クラスにカレンダー・ポップアップを追加します。

モーダル・グループを表示するクライアント側メソッドを指定します。
```
ClientMethod modalGroupCalendar() [ Language = javascript ]
{
  var group = zenPage.createComponent('modalGroup');
  group.setProperty('onaction','zenPage.calendarAction(group);');
  group.show('Select a date:','calendar','2005-12-12');
}
```
このメソッドは、以下のように動作します。
- ページの createComponent メソッドを呼び出して、modalGroup コンポーネントを追加します。
- onaction 値をクライアント側メソッドの名前に設定するモーダル・グループの setProperty メソッドを呼び出します。setProperty は、このポップアップでユーザが任意のアクション (カレンダーから日付の値を選択するなど) を行ったときに実行されます。このメソッドでは、modalGroup インスタンスを表す引数 group をとります。
- 以下の 3 つの引数でモーダル・グループの show メソッドを呼び出します。
  - ポップアップ・ウィンドウのタイトル
  - キーワード 'calendar'
  - ポップアップ時に表示する、カレンダーであらかじめ選択された日付 (オプション)
<page> 内の任意の場所で、モーダル・グループを表示するメソッドを呼び出すメカニズムをユーザに示す必要があります。以下は、ボタンを使用する例です。
```
<button caption="Display a Calendar"
        onclick="zenPage.modalGroupCalendar();" />
```
最後に、カレンダー・コントロールで取得した日付の値を取得および使用した後、ポップアップを閉じる必要があります。これは、ページ・クラスの以下のクライアント側メソッドで実行します。
```
ClientMethod calendarAction(group) [ Language = javascript ]
{
  alert("You selected: " + group.getValue());

  // write user value into HTML component
  zenSetProp('mgHtml','content','User entered: ' + group.getValue());
}
```
このメソッドは、以下のように動作します。
- ポップアップでユーザが特定の日付の値をクリックすると、実行されます。これが動作する理由は、手順 1 でこのメソッドをモーダル・グループの onaction イベント・ハンドラとして指定したからです。
- モーダル・グループの getValue メソッドを呼び出して、カレンダーに入力された日付の値を取得します。
- 値を確認する JavaScript 警告メッセージを発行します。
- <html> の id 値を指定して JavaScript ユーティリティ関数 zenSetProp() を呼び出すことで、<page> 上の <html> コンポーネントを探して、<html> コンポーネントの content プロパティを設定します。新しい <html> の content 値は、リテラル文字列と新たに取得した日付値を連結したものになります。
- ページの endModal メソッドは呼び出しません。組み込みカレンダー・モーダル・グループは、ユーザが日付を選択すると自動的に閉じます。

ユーザは、このサンプル・ページを以下のように使用できます。

まず最初に、ユーザに対して以下のように表示されます。
このページのボタンをクリックすると、modalGroupCalendar メソッドが呼び出されます。これにより、メイン・ページの前にポップアップ・ウィンドウが表示されます。このポップアップのタイトルは、modalGroupCalendar が show メソッドに渡した最初の引数です。現在選択されている日付は、3 番目の show 引数で指定されたものです。
事前選択されている値から、別の年、月、および日を選択すると、calendarAction メソッドが自動的に呼び出されます。これによりポップアップが閉じ、新しい日付の値をエコーする、ブラウザの警告メッセージが表示されます。
警告を閉じると、<page> の <html> コンポーネントのコンテンツが以下のように変更されたことがわかります。

上記の例は、SAMPLES ネームスペースのクラス ZENDemo.MethodTestOpens in a new tab にあるものに似ています。このサンプルを試すには、Zen デモのメイン・ページで、[ホーム]→[概要]→[メソッド]→[モーダル・グループ：カレンダー] の順に選択します。始めるには、"Zen の使用法" の “Zen の概要” の章で説明している “Zen デモ” を参照してください。

メッセージ・ボックス

以下の手順では、Zen ページ・クラスにメッセージ・ボックス・ポップアップを追加します。

モーダル・グループを表示するクライアント側メソッドを指定します。
```
ClientMethod modalGroupMsg() [ Language = javascript ]
{
  var group = this.createComponent('modalGroup');
  group.show('My New Message','msgBox',
  'This<br>message<br>contains <span style="color: red">HTML</span>!');
}
```
このメソッドは、以下のように動作します。
- ページの createComponent メソッドを呼び出して、modalGroup コンポーネントを追加します。
- 以下の 3 つの引数でモーダル・グループの show メソッドを呼び出します。
  - ポップアップ・ウィンドウのタイトル
  - キーワード 'msgBox'
  - ポップアップ・メッセージ用の HTML 形式のメッセージ・コンテンツ
<page> 内の任意の場所で、モーダル・グループを表示するメソッドを呼び出すメカニズムをユーザに示す必要があります。以下は、ボタンを使用する例です。
```
<button caption="Display a Message"
        onclick="zenPage.modalGroupMsg();" />
```
ユーザがこのボタンをクリックすると、ポップアップが以下のように表示されます。
ポップアップの [OK] をクリックすると、ポップアップが閉じます。

上記の例は、SAMPLES ネームスペースのクラス ZENDemo.MethodTestOpens in a new tab にあるものに似ています。このサンプルを試すには、Zen デモのメイン・ページで、[ホーム]→[概要]→[メソッド]→[モーダル・グループ：メッセージ・ボックス] の順に選択します。始めるには、"Zen の使用法" の “Zen の概要” の章で説明している “Zen デモ” を参照してください。

show メソッド

show は、モーダル・グループを表示するクライアント側 JavaScript メソッドです。返り値がなく、オプションの引数は 8 つまでです。“モーダル・グループ” にある前のトピックでは、これらの引数のいくつかについて説明しました。一覧は以下のとおりです。

title — ポップアップ・ウィンドウのタイトル静的なモーダル・グループでは、<modalGroup> 定義の groupTitle 値をオーバーライドします。
type — 以下のキーワードのいずれかです。
- "calendar" — 組み込みカレンダー・ボックスを表示します。
- "dynamic" — 動的に作成されたモーダル・グループを表示します。
- "msgBox" — 組み込みメッセージ・ボックスを表示します。
- "static" — 静的に定義された <modalGroup> を表示します。
引数 type を指定していない場合、<modalGroup> 定義が <page> に存在すれば、既定値は "static" です。それ以外の場合、既定値は "dynamic" です。
value — 組み込みモーダル・グループを使用する際に表示する値。type の種類に応じた値は以下のとおりです。
- "calendar" — value は YYYY-MM-DD 形式の日付になります。ウィンドウがポップアップ表示されると、カレンダーにはあらかじめ選択された日付として、この value の年と月が表示されます。
- "msgBox" — value は、ポップアップ・メッセージを HTML 形式で表示したメッセージ・コンテンツになります。
top — ポップアップ・ウィンドウの左上隅の垂直方向の座標 (0 が画面の最も上)。
left — ポップアップ・ウィンドウの左上隅の水平方向の座標 (0 が画面の左端)。
wid — ポップアップ・ウィンドウの幅。
hgt — ポップアップ・ウィンドウの高さ。
parms — modalGroup に名前と値の組み合わせのセットとして渡される、追加特性のセットを指定したオブジェクト。通常は、これを使用することにより、ポップアップ・カレンダーに追加のパラメータを渡すことができます。

<modalGroup> の属性

<modalGroup> コンポーネントは、%ZEN.Component.modalGroupOpens in a new tab クラスの XML プロジェクションです。以下のテーブルは、ページ・クラスの XData Contents 定義内で <modalGroup> を定義すると使用できる、<modalGroup> の属性を示しています。

属性	説明
Zen グループの属性	<modalGroup> は、あらゆる Zen グループと同じスタイル属性およびレイアウト属性を持ちます。詳細は、"Zen の使用法" の “Zen のレイアウト” の章にある “グループのレイアウトとスタイルの属性” を参照してください。
groupTitle	モーダル・グループ上部に表示するタイトル。静的なモーダル・グループでは、<modalGroup> 定義の groupTitle 値で設定できます。それ以外の場合、この値は、show メソッドの最初の引数により動的に設定されます。この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。 “Zen 属性のデータ型” を参照してください。
okCaption	メッセージ・ボックスの [OK] ボタンに表示するキャプション。既定では "OK" です。この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %%ZEN.Datatype.captionOpens in a new tab が与えられます。 “Zen 属性のデータ型” を参照してください。
onaction	<modalGroup> の onaction イベント・ハンドラ。組み込みモーダル・グループのポップアップ ("msgBox" または "calendar") でユーザがアクションを行うたびに、Zen によってこのハンドラが呼び出されます。“Zen コンポーネントのイベント・ハンドラ” を参照してください。 <modalGroup> に seed 値を指定する場合、これは自動的に onaction イベント・ハンドラに渡されます。
onhideGroup	モーダル・グループが非表示になると実行されるクライアント側 JavaScript 式。
onshowGroup	モーダル・グループが表示されると実行されるクライアント側 JavaScript 式。
seed	onaction イベント・ハンドラに任意の値を渡せるようにします。
value	(読み取り専用) value は show メソッドによって設定されるため、アプリケーションによって設定してはいけません。ただし、例えば組み込みカレンダー・モーダル・グループを扱う場合などは、この値を取得すると便利な場合があります。

ポップアップ・ウィンドウ

ポップアップ・ウィンドウは、ユーザ・イベントに応答して現在のアクティブ・ウィンドウの上にポップアップ表示する、新しいブラウザ・ウィンドウです。ポップアップ・ウィンドウは表示されるとすぐにアクティブ・ウィンドウになり、ユーザが閉じるまでアクティブ状態を維持します。以下のテーブルは、ポップアップ・ウィンドウを制御するクライアント側 JavaScript メソッドを示しています。onPopupAction を除いて、これらの Zen ページ・メソッドはファイナル・メソッドであるためオーバーライドできません。onPopupAction は、ポップアップ動作を制御するためにオーバーライドされる必要のある Zen コンポーネント・メソッドです。Zen ページもコンポーネントであるため、Zen ページは onPopupAction というクライアント側メソッドをサポートしています。

既定では、Zen は、ポップアップ・ウィンドウを現在の Zen ページ上に描画される <div> 要素としてレンダリングします。ポップアップ・ダイアログを別のウィンドウに表示したい場合は、グローバル ^%ISC.ZEN.useSoftModals を 0 に設定するか、または 0 を返すようにメソッド %OnUseSoftModals をオーバーライドすることができます。

英数文字およびアンダースコア以外の文字をポップアップ・ウィンドウ名に使用しないように注意してください。これらの文字を使用すると、特定のブラウザとの互換性がなくなります。

ポップアップ・ウィンドウを制御するためのクライアント側メソッド

クライアント側メソッド	説明
launchPopupWindow(...)	ポップアップ・ウィンドウを開きます。親コンポーネントを識別するか、親コンポーネントの既定値として現在の Zen ページを使用可能にします。
firePopupAction(...)	現在のポップアップの親コンポーネントにユーザ・アクションが実行されたことを通知します。希望に応じて、ポップアップを閉じます。
onPopupAction(...)	親コンポーネントは、ポップアップ上でユーザ・アクションが実行されたことを通知されるたびに、このメソッドを呼び出します。
cancelPopup()	他のアクションは実行せずに、現在のポップアップを閉じます。

Zen ページからポップアップ・ウィンドウを表示するには、以下の手順を実行します。

ポップアップ・ウィンドウとして表示する Zen ページ・クラスを作成します。この例では、これは “ポップアップ・ページ” または次のクラスになります。
MyApp.MyDialog.cls
ポップアップ・ページを設計する際は、次の例のように、そのポップアップを呼び出す際にそのポップアップに渡すことを想定している URI パラメータに対応するプロパティをそのポップアップ・ページに追加します。
Property ABC As %String(ZENURL="ABC");
ポップアップの呼び出し元のウィンドウとして使用する予定の Zen ページ・クラスを開きます。この例では、これは “親ページ” となります。
親ページにクライアント側メソッドを追加して、このメソッドによって launchPopupWindow を呼び出します。
次の例では、ポップアップ・ページ・クラス名は、launchPopupWindow の呼び出しの最初の引数として登場し、zenLink の構文内で一重引用符で正しく囲まれています。この launchPopupWindow 呼び出しでは、22 という値が指定された ABC という単一の URI パラメータがポップアップ・ページに渡されます。
```
ClientMethod showPopupWindow() [ Language = javascript ]
{
  var parms = new Object();
  parms.ABC = 22;
  zenPage.launchPopupWindow(
    zenLink('MyApp.MyDialog.cls'),
    'A True Dialogue',
    'status,scrollbars,resizable,width=400,height=300',
    parms);
}
```
詳細は、これらの手順の後に掲載している引数のリストを参照してください。
launchPopupWindow を呼び出すクライアント側メソッドを呼び出す onclick 属性が設定されたコンポーネントを親ページ上に配置します。次に例を示します。
```
<button caption="Initiate Conversation"
        onclick="zenPage.showPopupWindow();"
        title="A demonstration of launching a popup window" />
```
ポップアップ・ページ・クラスを調べます。firePopupAction メソッドを呼び出すコンポーネントがこのクラスにより提供されていることを確認します。firePopupAction は、ポップアップでユーザ・アクションが実行されたことをポップアップ・ウィンドウの親に通知します。firePopupAction では、以下の 3 つの引数を指定できます。
- action — action パラメータが指定されていない場合は、リテラル文字列の ok がアクション・コードです。
- value — コードでは value を提供する必要があります。この value は、親の onPopupAction メソッドに引数として自動的に渡されます。
- close — close の既定値は True です。True の場合は、ポップアップ・ウィンドウは親ウィンドウへの通知後に閉じられます。
次に例を示します。
```
 // tell our parent window that OK was pressed; do not close this window.
 this.firePopupAction('apply',this.getDialogValue(),false);
```
親コンポーネント・クラスで、onPopupAction メソッドをオーバーライドして、ポップアップ・ページによりポップアップ・アクションが起動されたときに適切な応答を提供します。一般に考えられるのは、ポップアップ・ページによって返された value を取得して使用することです。親コンポーネントを指定しなかった場合は、親はポップアップを呼び出したページです。親がページである場合は、親ページ・クラス内の onPopupAction をオーバーライドする必要があります。onPopupAction メソッド・シグニチャ内では、次のようになります。
- popupName は、アクションを送信するポップアップ・ウィンドウの名前です。
- action は、アクションの名前です。
- value は、アクションに関連付けられた値です。
これらすべての引数は、ポップアップ・ページの firePopupAction メソッドから onPopupAction に自動的に渡されます。
onPopupAction メソッドでは、返された value を任意の方法で使用できます。次の例では、この値を <html> コンポーネントの content プロパティに保存しています。

Important:

ブラウザに Internet Explorer を使用している場合は、ポップアップ・ウィンドウから送信操作で値を保存しないでください。これらの値を単に保存してください。
```
ClientMethod onPopupAction(popupName, action, value) [ Language = javascript ]
{
  zenSetProp('mgHtml','content','User entered: ' + value);
}
```
上記の手順 4 で示したような親ページ上にボタンやリンクを作成した場合は、そのボタンをクリックすると、親ページ上に重ねて配置された別のウィンドウにポップアップ・ページが表示されるようになります。

クライアント側メソッド launchPopupWindow は、以下の引数をこの順序で受け取ります。

url – 表示する内容が以下のどちらであるかを識別する文字列
- パッケージ名と .cls 拡張子を含む、Zen ページ・クラスの名前
- 目的の内容の URI
JavaScript 関数 zenLink により、セッションのトラッキング値などのあらゆる追加 URI パラメータは必ずリンクに含まれます。zenLink は、クラス名または任意の URI を指定して使用できます。以下の例では、クライアント側メソッドは、JavaScript による文字列連結を使用していくつかの要素から URI を構築した後、Zen ページ・メソッド launchPopupWindow を呼び出します。この例では、escape 関数も使用し、この文字列で使用するすべての変数値の形式を適切に設定します。
```
ClientMethod editCSSValue(context) [ Language = javascript ]
{
  var ctrl = this.getComponentById('value');
  var value = ctrl.getValue();
  var url = zenLink('%ZEN.Dialog.cssDeclarationEditor.cls?context='
            + escape(context) + '&declaration=' + escape(value) );
  zenPage.launchPopupWindow(url,
            'CSSDeclarationEditor',
            'resizable,width=500,height=700' );
}
```
pageName – ポップアップ・ウィンドウを識別する文字列。
features – JavaScript 関数 window_open に必要なウィンドウの属性のコンマ区切りリスト。
これらの属性の処理結果は、ブラウザにより異なります。一部の開発者には、真にモーダルな Internet Explorer の動作が好まれています。Internet Explorer では、モーダル・ウィンドウが一番上に留まり、ユーザがモーダル・ウィンドウを閉じるまでアプリケーションでは何もできなくなります。他の開発者にはモーダルではない動作が好まれます。Internet Explorer 以外のブラウザは、この呼び出しの設定に関係なくこの動作を使用します。ここでは、モーダル・ウィンドウはアプリケーション内の別のウィンドウになるだけで、ユーザが別のウィンドウをクリックすれば、それがモーダル・ウィンドウより優先されます。
Internet Explorer の動作を他のブラウザの動作と同様にする場合、launchPopupWindow のウィンドウ属性のリストに、文字列 modal=no を記述します。次に例を示します。
```
  zenPage.launchPopupWindow(url,
            'CSSDeclarationEditor',
            'resizable,width=500,height=700,modal=no'
            );
```
parms – parms には、ポップアップ・ウィンドウを呼び出す URI 文字列でパラメータとして使用される値の配列を指定します (省略可能)。parms 引数を使用して URI のパラメータを指定することで、url 引数内の URI パラメータを正しく書式設定して連結するという負担から解放されます。
parms 配列に値を格納する際の書式は次のとおりです。
```
var parms = new Object();
parms.Aaa = 10;
parms.Bbb = 20;
zenPage.launchPopupWindow(url,
          'CSSDeclarationEditor',
          'resizable,width=500,height=700,modal=no'
          parms);
```
上記のサンプル・コードに基づき、launchPopupWindow は、Aaa と Bbb を URI パラメータとして使用して、parms 配列の対応するメンバに割り当てられた値 (10 と 20) をこれらのパラメータに割り当てます。launchPopupWindow は、URI 文字列内のこれらのパラメータを適切にエスケープして、URI 文字列内の url 値と組み合わせる処理をすべて担当します。
parms 配列の各メンバは、次の例のように、ポップアップ・ページ・クラス内の ZENURL プロパティに対応している必要があります。
```
Property Aaa As %String(ZENURL="Aaa");
Property Bbb As %String(ZENURL="Bbb");
```
parent – parent には、firePopupAction メソッドの発行時に通知先となる Zen コンポーネントを指定します (省略可能)。これは、ページ上の任意のコンポーネントであっても、ページ・オブジェクト自体であってもかまいません。parent の値が指定されていない場合は、親は既定でページとなります。parent には、このコンポーネントを識別するために内部で使用されるシステム側で割り当てられたインデックス番号を指定します (省略可能)。繰り返しグループ内のコンポーネントの場合、parent の値は、ドットとそれに続く番号となります。この番号は、そのグループ内のこのコンポーネントの位置を示す 1 から始まる番号です。アプリケーションは parent の値を使用できますが、設定してはいけません。

ダイアログ

Zen には、ポップアップ・ダイアログ・ウィンドウとして機能するように設計された組み込みクラスがいくつかあります。Zen のダイアログ・ウィンドウでは、通常の Zen コンポーネントをすべて扱うことができます。すべてのダイアログ・ウィンドウは、Zen ページ・クラスである %ZEN.Dialog.standardDialogOpens in a new tab のサブクラスです。このベース・クラスは、ダイアログで従来から使用されてきた [OK]、[適用]、[キャンセル] などの各種ボタンや、[OK] がクリックされたときに、入力されているデータを取得するための規則などを提供します。

このトピックでは、Zen のダイアログ・ウィンドウで作業するための規則について説明します。

組み込みファイル選択ウィンドウの表示
組み込み色選択ウィンドウの表示
検索ダイアログ・ウィンドウの表示
%ZEN.Dialog.standardDialogOpens in a new tab に基づく新しいダイアログ・ウィンドウの作成
%ZEN.Dialog.standardDialogOpens in a new tab の代わりの新しいダイアログ・ウィンドウ・テンプレートの作成

ファイル選択ダイアログ・ウィンドウ

%ZEN.Dialog.fileSelectOpens in a new tab ウィンドウには、サーバ・システムにあるディレクトリとファイルのリストが表示されます。ここからファイルやディレクトリを選択できます。得られる値はフル・パスとファイル名です。

Important:

fileSelect ダイアログを使用してサーバ上のファイル・システムを表示するには、現在のユーザが、%Admin_Manage、%Admin_Operate、%Admin_Security、または %Development のいずれかのリソースで USE 特権を保有している必要があります。

fileSelect ダイアログをポップアップ・ウィンドウとして表示するには、この章の “ポップアップ・ウィンドウ” の手順を使用しますが、クライアント側メソッドの追加を説明する手順で、以下のようなメソッドを指定します。


ClientMethod showPopupFile() [ Language = javascript ]
{
var pathname = '\Temp';
var showdir = '0';
zenPage.launchPopupWindow(
  '%ZEN.Dialog.fileSelect.cls?Dir=' + escape(pathname) +
  '&showdirectoryonly=' + showdir,
  'FileSelectWindow',
  'status,scrollbars,resizable,width=660,height=700');
}

このメソッドは、以下の引数で Zen ページ・メソッド launchPopupWindow を呼び出します。

%ZEN.Dialog.fileSelectOpens in a new tab クラスのファイル名で始まる URI 文字列。必要な値はファイル名のみですが、この場合は、URI には以下のようなさまざまなパラメータが続きます。
- ファイル検索ウィンドウのパス名。これは、フル・パス名、または Caché システム管理ディレクトリ (Caché のインストール先ディレクトリにある \mgr) を基準とする相対パスのいずれかです。省略すると、既定は Caché システム管理ディレクトリとなります。
- ディスプレイにファイルを表示できるように、値を 0 とした showdirectoryonly。この引数は、既定値が 0 なので省略してもかまいません。ディレクトリのみを表示する場合は、showdirectoryonly を 1 に設定します。
ポップアップ・ウィンドウの識別子。
ポップアップ・ウィンドウの特性をコンマで区切って列挙したリスト。

%ZEN.Dialog.fileSelectOpens in a new tab を使用した完全な例については、SAMPLES ネームスペースの ZENTest.FormTest2Opens in a new tab を参照してください。launchPopupWindow メソッドに関する詳細は、この章の前半の “ポップアップ・ウィンドウ” を参照してください。

色選択ダイアログ・ウィンドウ

%ZEN.Dialog.colorSelectOpens in a new tab ウィンドウでは、色が設定された一連のセルから色を選択できます。得られる値は、#F3FDDA などの HTML カラー値です。fileSelect ダイアログをポップアップ・ウィンドウとして表示するには、この章の “ポップアップ・ウィンドウ” の手順を使用しますが、手順 2 で、以下のようなクライアント側メソッドを指定します。


ClientMethod showPopupColor() [ Language = javascript ]
{
  zenPage.launchPopupWindow(
    '%ZEN.Dialog.colorSelect.cls',
    'ColorPicker',
    'status,scrollbars,resizable,width=500,height=700');}

このメソッドは、以下の引数でクライアント側関数 launchPopupWindow を呼び出します。

%ZEN.Dialog.colorSelectOpens in a new tab クラスのファイル名。
ポップアップ・ウィンドウの識別子。
ポップアップ・ウィンドウの特性をコンマで区切って列挙したリスト。

launchPopupWindow メソッドに関する詳細は、この章の前半の “ポップアップ・ウィンドウ” を参照してください。

検索ダイアログ・ウィンドウ

%ZEN.Dialog.searchDialogOpens in a new tab ウィンドウを使用すると、ユーザは SQL クエリを作成して実行できます。このクラスには、以下のプロパティがあります。

query — 検索フォームを生成するための SQL 文。この値は、ZENURL パラメータとして渡すことはできません。代わりに、アプリケーションは %ZEN.Dialog.searchDialogOpens in a new tab をサブクラス化して、このサブクラス内のサーバ側ロジックを使用して query の値を提供する必要があります。
paramNames — 検索フォーム内のパラメータ用に表示する名前のコンマ区切りリストを提供します。

ダイアログ・ウィンドウの作成

%ZEN.Dialog.standardDialogOpens in a new tab に基づく新しいタイプの Zen ダイアログ・ウィンドウを作成するには、以下の手順を実行します。

%ZEN.Dialog.standardDialogOpens in a new tab のサブクラスを作成します。
以下を指定して、新しい XData ブロックを追加します。
- 名前 dialogBody
- コンテナとしての <pane>
- ユーザ入力のソースとして特定するコンポーネントの id 値
以下はその例です。
```
XData dialogBody
{
  <pane>
    <text label="I say: " value="What do you think?" />
    <textarea label="And you say: " id="yourReply" />
  </pane>
}
```
サーバ側コールバック・メソッド %OnGetTitle をオーバーライドします。例えば、以下のようになります。
```
Method %OnGetTitle() As %String
{
  Quit $$$TextHTML("This is My Dialog")
}
```
サーバ側コールバック・メソッド %OnGetSubtitle をオーバーライドします。例えば、以下のようになります。
```
Method %OnGetSubtitle() As %String
{
  Quit $$$TextHTML("by John Smith")
}
```
クライアント側 JavaScript メソッド getDialogValue をオーバーライドして、値を返します。例えば以下のようになります。
```
ClientMethod getDialogValue() [ Language = javascript ]
{
  return this.getComponentById('yourReply').getValue()
}
```
ダイアログに自動的に表示される [OK] ボタンと [キャンセル] ボタンに加え、[適用] ボタンを追加するには、APPLYBUTTON パラメータをオーバーライドして 1 に設定します。
```
Parameter APPLYBUTTON = 1;
```
$$$Text ローカライズ・マクロを有効にするには、次のように DOMAIN パラメータに有意な値を指定します。
```
Parameter DOMAIN = "MyDomain";
```
このダイアログを表示すると、以下のようになります。

ダイアログ・ウィンドウ・テンプレートの作成

Zen の標準のダイアログと同じレイアウトとグラフィックを使用するのではなく、独自のスタイルをダイアログに適用する必要があるとします。これを実現する最も簡単な方法は、新しいウィンドウ・テンプレート・クラスを作成し、それを前述の説明の %ZEN.Dialog.standardDialogOpens in a new tab の代わりに使用することです。その手順は以下のようになります。

%ZEN.Dialog.standardDialogOpens in a new tab のサブクラスを作成します。
このサブクラスで、必要に応じて別のスタイルを適用します。
この章の “ダイアログ・ウィンドウの作成” の説明に従ってダイアログを新規に作成する場合は、%ZEN.Dialog.standardDialogOpens in a new tab を拡張するのではなく、この新しいサブクラスを拡張します。
ファイル・セレクタ・クラスが必要な場合は、以下のようにします。
- %ZEN.Dialog.fileSelectOpens in a new tab クラスをコピーします。
- %ZEN.Dialog.standardDialogOpens in a new tab を拡張せずに、作成した新しいダイアログ・ウィンドウ・テンプレート・クラスを拡張するように、コピーしたクラスを編集します。
カラー・セレクタ・クラスが必要な場合は、以下のようにします。
- %ZEN.Dialog.colorSelectOpens in a new tab クラスをコピーします。
- %ZEN.Dialog.standardDialogOpens in a new tab を拡張せずに、作成した新しいダイアログ・ウィンドウ・テンプレート・クラスを拡張するように、コピーしたクラスを編集します。