test

Sun Desktop Manager 1.0 開発者ガイド

付録  B 要素の辞書

この付録では、テンプレートで使用可能な要素と属性すべてのリファレンスを提供します。

Header 要素: apt:template, resImport, helpImport

<!ELEMENT apt:template (resImport*, category)>
<!ATTLIST apt:template
    xmlns:apt CDATA #FIXED "http://www.sun.com/jds/apoc/2004/template"
    xmlns:oor CDATA #FIXED "http://openoffice.org/2001/registry"
    xmlns:xs  CDATA #FIXED "http://www.w3.org/2001/XMLSchema"
    xmlns:xsi CDATA #FIXED "http://www.w3.org/2001/XMLSchema-instance"
>

<!ELEMENT resImport EMPTY><!ATTLIST resImport
    apt:packagePath NMTOKEN #REQUIRED
>

ルート要素テンプレートには 2 つのサブ要素 resImport と category があり、これらについては、「Structure 要素: category, page, section」で説明しています。

resImport 要素はリソースファイルのインポートに使用します。インポートされたリソースバンドルのリソースキーは、すべてテンプレートに通知されます。リソースキーを使用するリソースを、たとえば apt:label 属性にインポートする必要があります。「Structure 要素: category, page, section」を参照してください。apt:packagePath 属性は、パスを使用してリソースの場所を指定します。区切り文字はドット (.) です。ファイルの接尾辞 (.properties) は、ISO 言語コード (ISO-639) および ISO 国コード (ISO 3166) と同様に指定してはいけません。パスのルートディレクトリは、package の下にある res ディレクトリです。「ローカライズ」も参照してください。

Structure 要素: category, page, section

<!ELEMENT category (category | page)>
<!ATTLIST category
    apt:name ID #REQUIRED
    apt:scope (user | host | global) #IMPLIED
    apt:label NMTOKEN #IMPLIED
    apt:inlineHelp NMTOKEN #IMPLIED
>
<!ELEMENT page ((section | set)+, xmlHandler*)><!ATTLIST page
    apt:name ID #REQUIRED
    apt:scope (user | host | global) #IMPLIED
    apt:label NMTOKEN #IMPLIED
    apt:inlineHelp NMTOKEN #IMPLIED
    apt:onlineHelp CDATA #IMPLIED
>
<!ELEMENT section (property+)>
<!ATTLIST section
    apt:name ID #REQUIRED
    apt:scope (user | host | global) #IMPLIED
    apt:label NMTOKEN #IMPLIED
>

category 要素は、構成プロファイルツリーでページの一意な配置を定義するために使用します。その最初の属性は apt:name 属性です。name 属性は、要素の一意な名前を定義するために使用します。大きいテンプレートの方向付けと要素の参照を円滑にします。

category 要素の 2 番目の属性は apt:scope です。scope 属性は、構成設定を適用できるツリーを指定します。スコープが "user" の場合は、組織ツリーのみに構成設定が適用されます。スコープが "host" の場合は、ドメインリーのみに構成設定が適用されます。スコープが "global" の場合は、両方のツリーに構成設定が適用されます。デフォルト設定は "global" です。要素は、独自のスコープを定義する場合を除いて、親要素からスコープを継承します。要素のスコープが "user" で、ドメインツリーに接続している構成プロファイルツリーが「コンテンツ区画」に表示されている場合、その要素はユーザーに表示されません。要素のスコープが "host" で、組織ツリーに接続している構成プロファイルツリーが表示されている場合も、同様です。

category 要素の 3 番目の属性は apt:label です。label 属性は、ユーザーに表示可能な要素の名前を指定し、ローカライズをサポートしています。label 属性で指定される文字列は、最初にリソースバンドルで検索されます。文字列と一致するキーが見つかった場合は、その値が GUI に表示されます。どのリソースバンドルにも文字列と一致するキーがない場合は、その文字列が GUI に表示されます。label 属性を指定しなければ、name 属性で指定された文字列が GUI に表示されます。属性を両方とも定義しない場合は、出力が表示されません。

category 要素の 4 番目の属性は apt:inlineHelp です。inlineHelp 属性は、GUI に表示されるヘルプテキストを指定します。ヘルプはカテゴリ名の右にある「コメント」列に表示されます。前述のlabel 属性と同様に、ローカライズをサポートしています。

カテゴリ階層の終わりに 1 つだけページ要素があります。この要素はオプション 1 ページを表し、これには、category 要素で認識される 4 つの属性 name、 scope、label、inlineHelp が含まれています。inlineHelp 属性の値はページタイトルの下に表示されます。label 属性の値はページのタイトルとして表示されます。カテゴリ名とページ名は、構成プロファイルツリーでページの一意な場所と名前を定義します。

apt:onlineHelp 属性は、オンラインヘルプを含む HTML ファイルを Desktop Manager で利用できるようにします。この要素によって参照される HTML ページは、ユーザーが Desktop Manager のマストヘッドにある「ヘルプ」のリンクをクリックすると、コンテキスト依存のヘルプとして表示されます。apt:filePath 属性は、パスを使用してヘルプファイルの場所を指定します。区切り文字はスラッシュ ("/") です。ファイルの接尾辞 (.html) は、ISO 言語コード (ISO-639) および ISO 国コード (ISO 3166) と同様に指定してはいけません。パスのルートディレクトリは、package ディレクトリの下にある web ディレクトリです。「ローカライズ」も参照してください。

ページには任意の数のセクションやセットを含めることができ、そのあとにオプションとして xmlHandlers のリストを付加することもできます。したがって、page 要素にはサブ要素の section、set (「動的データ要素 : set」を参照) と xmlHandler (「Interaction 要素: xmlHandler, event, action, choose, command」を参照) が含まれます。

section 要素は、そのプロパティーのサブ要素すべてをテーブルに似たレイアウトで視覚的にグループ化します。これには category 要素から認識される 3 つの属性 name、scope、label が含まれています。label 属性の値はセクションタイトルとして表示されます。

Basic Data 要素: property, value, constraints

<!ELEMENT property (constraints?, value*, visual)>
<!ATTLIST property
    apt:name ID #REQUIRED
    apt:scope (user | host | global) #IMPLIED
    apt:label NMTOKEN #IMPLIED
    apt:inlineHelp NMTOKEN #IMPLIED
    apt:dataPath CDATA #REQUIRED
    oor:type (xs:boolean | xs:short | xs:int | xs:long | xs:double | 
              xs:string | xs:hexBinary |
              oor:any | oor:boolean-list | oor:short-list | oor:int-list | 
              oor:long-list | oor:double-list | oor:string-list | oor:hexBinary-list)
              #IMPLIED
    apt:storeDefault (true | false) #IMPLIED
    apt:xmlHandler IDREF #IMPLIED
    apt:extendsProperty CDATA #IMPLIED
>
<!ELEMENT visual (checkBox | chooser)?>
<!ATTLIST visual
 apt:type (textField | password | textArea | radioButtons | comboBox | stringList | 
           colorSelector | hidden) #IMPLIED
>

<!ELEMENT checkBox EMPTY>
<!ATTLIST checkBox
 apt:labelPost NMTOKEN #IMPLIED
>

<!ELEMENT chooser EMPTY>
<!ATTLIST chooser
 apt:labelPopup NMTOKEN #IMPLIED
 apt:listDataPath CDATA #IMPLIED
 apt:extendsChooser CDATA #IMPLIED
>
<!ELEMENT constraints (enumeration*, length?, minLength?, maxLength?, minInclusive?, 
                       maxInclusive?, minExclusive?, maxExclusive?)>
<!ELEMENT enumeration EMPTY>
<!ATTLIST enumeration 
    oor:value CDATA #REQUIRED
    apt:label NMTOKEN #IMPLIED
>
<!ELEMENT value (#PCDATA)>
<!ATTLIST value
    xsi:nil (true | false) #IMPLIED
    oor:separator CDATA #IMPLIED
>

property 要素は、チェックボックス、ラジオボタン、編集フィールドなどの GUI 要素を通して構成設定を視覚化します。これには、category 要素で認識される 4 つの属性 name、scope、label、inlineHelp が含まれています。インラインヘルプは、「値」列の入力フィールドの下に (または値文字列の下に編集不可の形で) 表示されます。label 属性の値は GUI 要素のラベルとして表示されます。カテゴリ名、ページ名、セクション名、プロパティー名は、構成プロファイルツリーでページの一意な場所と名前を定義します。

属性apt:dataPath は、プロパティーの値を保存するデータのバックエンドの場所を指すパスを定義します。dataPath 属性の値は、コンポーネントの絶対パス (たとえば org.openoffice.Office.Common/ExternalMailer/Program) です。付録 A 「構成パスのマッピング」を参照してください。property 要素の dataPath 属性は、データのバックエンドプロパティーを指す必要があります。データのバックエンドノードを指すと、実行時エラーが発生します。

apt:type は、リポジトリの構成データの種類を指定するために使用します。次のタイプが定義されます。

xs:boolean 

ブール値 (true/false) 

xs:short 

16 ビットの整数 

xs:int 

32 ビットの整数 

xs:long 

64 ビットの整数 

xs:double 

浮動小数点数 (IEEE 64 ビット double の値範囲) 

xs:string 

プレーンテキスト (印刷可能な Unicode 文字のシーケンス) 

xs:hexBinary 

未解釈オクテットのシーケンス、16 進数エンコード 

oor:any 

上記すべてのタイプを含む 

oor:*-list 

上記いずれかのタイプのリスト 

以上のタイプは StarSuite/OpenOffice.org Registry (OOR) 形式で定義されているタイプに似ています。再利用できるように、テンプレートでは可能な限り OOR 形式の構文を使用しています。タイプの詳細は、http://util.openoffice.org/common/configuration/oor-document-format.html で OpenOffice.org Registry Format (OOR) に関する文書を参照してください。

属性 apt:storeDefault は Desktop Manager にデフォルトデータをデータのバックエンドに保存するように指示します。デフォルトデータは value 要素によって定義され (以下を参照)、ユーザーにデフォルトを表示するために使用します。ユーザーが値を変更しない場合や、「コンテンツ区画」で「デフォルトの適用」アクションを実行してデフォルトデータの保存を明示的に要求した場合は、デフォルトデータがリポジトリに保存されません。storeDefault 属性の値を true に設定すると、ユーザーが値を変更しない場合や「デフォルトの適用」を実行した場合でも、デフォルトデータが保存されます。

property 要素には 3 つのサブ要素 constraints、value、visual があります。

visual 要素は、GUI のプロパティーの表示タイプを定義します。表示タイプには、checkBox、 radioButtons、comboBox、stringList、 textField、password、textArea、chooser、 colorSelector、hidden があります。GUI の各要素には、編集と編集不可の 2 種類の表示形態があります。編集不可の表示形態は、Desktop Manager を使用する管理者がそのプロパティーに対する書き込み権を持っていない場合に表示されます。

hidden プロパティーは、視覚的な GUI 要素を描画しませんが、プロパティーに関連付けられた値をブラウザの非表示フィールドに渡します。この機能は、たとえばフロントエンドで入力された 1 つの値をバックエンドの複数の場所で保存しなければならない場合に便利です。

表示タイプは visual 要素の apt:type 属性によって定義されます。ただし、checkBox と chooser は例外です。これら 2 つの GUI 要素を正しく表示するには追加情報が必要なので、これらの要素にはその情報を含める独自のサブ要素があります。

checkbox プロパティーはチェックボックスの前後に文字列を表示します。これは checkBox 要素で表します。checkBox GUI 要素を編集不可の形態 (上の表を参照) で表示するには、さらに 2 つ文字列が必要になります。したがって、checkBox GUI 要素には 4 つ文字列が必要で、次のように表示されます。

  1. チェックボックスの前。この文字列はproperty 要素の label 属性で定義される。

  2. チェックボックスの後。この文字列は checkBox サブ要素の apt:labelPost 属性で定義される。この属性を定義しなければ、label 属性で定義された文字列に「.post」が付加される。この文字列はリソースファイルでキーとして検索される。

  3. チェック付きのチェックボックスではなく、チェックボックスが編集不可の表示形態の場合。文字列は constraints 要素の最初の enumeration サブ要素の label 属性で定義される。制約を指定しなければ、property 要素 label 属性で定義された文字列に接尾辞「.checked」が付加される。この文字列はリソースファイルでキーとして検索される

  4. チェックなしのチェックボックスではなく、チェックボックスが編集不可の表示形態の場合。文字列は constraints 要素の 2 番目の enumeration サブ要素の label 属性で定義される。制約を指定しない場合は、property 要素 label 属性で定義された文字列に接尾辞「.unchecked」が付加される。この文字列はリソースファイルでキーとして検索される

chooser プロパティーを使用すると、エントリのリストの値が確定されます。これは chooser 要素で表します。コンボボックスと違って、エントリのリストは編集可能です。このリストは chooser 要素の apt:dataPath 属性で指定したバックエンドの場所に保存されます。

「編集」ボタンをクリックすると、ポップアップウィンドウが開き、リストを編集するための GUI が提供されます。ポップアップウィンドウの内容のタイトルは、apt:chooser 要素の labelPopup 属性で定義します。constraints 要素の enumeration サブ要素を使用すると、リストのデフォルト値を指定できます (下の制約に関する説明を参照)。

apt:extendsChooser プロパティーは、別の chooser 要素を参照するために使用します。このプロパティーを使用すると、以前に定義した chooser 要素を簡単に再利用できます。その参照先 chooser で定義されている要素と属性のすべてが、参照元 chooser で定義されているかのように解釈されます。参照元 chooser で定義されているサブ要素と属性が、参照先 chooser の要素や属性を上書きします。プロパティーのパスは、参照先 chooser の検索に使用されます。プロパティーのパスは、ルートカテゴリからプロパティまでのパスの全要素の apt:name の値をスラッシュ ("/") で区切って連ねたものです。次に例を示します。/StarSuite/Internet/Proxy/Settings/MyChooser

表示タイプが指定されていない場合は、type 属性から GUI 要素が引き出されます。タイプが xs:booleanの場合は、チェックボックスが使用されます。タイプがリストの種類 (たとえば oor:short-list) 、xs:hexBinary、または oor:any の場合は、テキスト領域が表示されます。その他のタイプの場合は、編集フィールドが使用されます。表示タイプもデータ型も指定されていない場合は、編集フィールドが表示され、バックエンドのデータ型が xs:string であるとします。

constraints 要素は入力フィールドに制約を加えます。たとえば、ユーザーが保存できる値を 1 から 5 までの整数に限定する場合は、oor:type 属性を「xs:int」と一緒に提供するだけでは不十分です。minInclusive 制約 1 と maxInclusive 制約 5 を指定して、必要な制約を与えます。

checkbox プロパティーと一緒に使用する場合は、列挙制約にもう 1 つの用途があります。最初の enumeration constraints サブ要素は、チェックボックスがオンになっている場合にバックエンドに保存する値を定義し、2 番目の enumeration constraints サブ要素は、チェックボックスがオフになっている場合にバックエンドに保存する値を定義します。制約を指定しなければ、保存されるデフォルト値は true と false です。編集不可の表示形態で GUI に表示されるデフォルトの文字列は、「使用する」と「使用しない」です。

列挙制約は、radiobutton プロパティーと combobox プロパティーの場合は必須である以外は、意味が checkbox プロパティーと同じです。これらの要素の内容は開発者が自由に決めることができます。GUI に表示される名前は、constraint 要素の label 属性で定義します。列挙制約では label 属性の省略が可能です。その場合は、property 要素の label 属性で定義した文字列に接尾辞を付加して追加のリソースを指定します。

たとえば、プロパティーのラベルが「securityList」で、列挙制約に「1」、「2」、「3」の値が含まれていても列挙制約のラベルが定義されていないドロップダウンボックスがあるとします。ユーザーに表示される文字列は、リソースキーの「securityList.1」、「securityList.2」、「securityList.3」のそれぞれを検索して決定されます。

chooser プロパティーのリストエントリはローカライズされません。その結果、列挙制約の apt:label 属性はこれらのプロパティーには影響しません。

その他の制約については、OpenOffice.org Registry Format (OOR) の文書の Property Constraints を参照してください。

value 要素には、プロパティーのデフォルト値が含まれています。このデフォルト値は、デフォルト階層に含まれている値と同じにするか、ここで新たに指定することができます。これは、データバックエンドにデータが見つからない場合に、Desktop Manager が表示する値を定義します。

value 要素の定義は、OOR 形式で与えられる定義と似ています。 value 要素にはサブ要素がなく、nil、 separator、 lang という 3 つの属性があります。xsi:nil 属性を true に設定すると、プロパティーの値が「値なし」として定義されます。oor:separator 属性は、value 要素にリスト型の値が含まれている場合に、リストトークンの区切り文字として使う文字列を指定するために使用します。

ヒント –

stringList プロパティーのリストエントリは、oor:string-list 型の値として保存されます。デフォルトの区切り文字は空白文字 1 つです。

apt:xmlHandler 属性については、「Interaction 要素: xmlHandler, event, action, choose, command」を参照してください。

動的データ要素 : set

<!ELEMENT set (page)>
<!ATTLIST set
    apt:name ID #REQUIRED
    apt:scope (user | host | global) #IMPLIED
    apt:label NMTOKEN #IMPLIED
    apt:labelPopup NMTOKEN #IMPLIED
    apt:dataPath CDATA #REQUIRED
    apt:elementNamePath CDATA #IMPLIED
>

これまでに紹介した要素はすべて、バックエンドの静的コンテンツを処理しました。set 要素は、動的コンテンツを処理するために使用します。これは section 要素のようにページのサブ要素で、プロパティーのセットをテーブルに表示します。

これには、category 要素で認識される 3 つの属性 name、scope、label が含まれています。label 属性の値はテーブルのタイトルとして表示されます。

apt:dataPath 属性は、要素のセットを含んだデータのバックエンドノードを指すパスを定義します。dataPath 属性の値は、org.openoffice.Office.Commands/Execute/Disabled 形式の絶対パスです (付録 A 「構成パスのマッピング」を参照)。set 要素の dataPath 属性は、バックエンドのノードを指す必要があります。バックエンドのプロパティーを指すと、エラーが発生します。

セットの子孫の dataPath 属性には動的な部分が含まれている必要があります。この動的な部分は、セットのメンバーであるバックエンドのノードの場所を指定します。バックエンドのセットのメンバーにアクセスするためには、名前が異なる必要があります。これを実現するには、変数が使用されます。

変数にはドル記号の接頭辞 $variable_name。有効な変数名は queriedId と silentId です。$queriedId 変数が指定された場合、Desktop Manager はユーザーに一意の ID を照会する追加の編集フィールドを表示します。$silentId 変数が指定された場合、ID はユーザーから照会されず、Desktop Manager は一意の ID を自身で生成します。

次に例を示します。property 要素の dataPath 属性の値が org.openoffice.Office.Commands/Execute/Disabled/$queriedId/Command であるとします。ユーザーが新しいセット要素を作成した場合は、セットメンバーの名前も要求されます。GUI に表示される実際の質問の文字列は apt:labelPopup 属性で指定します。この属性を省略した場合は、「新しい項目の名前を入力してください」 というプロンプトが表示されます。

パスの文字列の長さを最小限にするには、セットまたはプロパティーの dataPath 属性の値として相対パスを指定することも可能です。相対パスの例は ./$queriedId/Command です。絶対パスは、テンプレート要素ツリーを上に移動し、相対パスにその祖先の dataPaths の接頭辞を付けて構成します。たとえば、プロパティーの親がセットであるとします。このセットは dataPath の値 org.openoffice.Office.Commands/Execute/Disabled を指定します。Desktop Manager はこのパスを相対パス ./$queriedId/Command と組み合わせ、絶対パス org.openoffice.Office.Commands/Execute/Disabled/$queriedId/Command にします。

dataPath 属性 (set 要素と property 要素) をサポートしているセットのすべての子孫がその dataPath 属性の値として絶対パスを指定している場合は、セットの dataPath 属性を指定する必要はありません。

再帰的なセットの構造 (セットのセット) も処理できます。これは、セット要素に page 要素を含め、それにまた set 要素を含めることで実現します。サブセットの dataPath 属性では、スーパーセットに相対するパスを指定できます。

セットのメンバーがバックエンドプロパティーの場合、バックエンドプロパティーの oor: name 属性は、GUI でラベルとして表示されます。バックエンドプロパティーの値は GUI 要素のラベルとして表示されます。

セットのメンバーがバックエンドのノードの場合は、バックエンドノードの oor:name 属性は、リンクの名前として表示されます。apt:elementNamePath 属性を使用すると、この命名スキームを上書きできます。elementNamePath は、バックエンドのノードに相対するパスを指定します。このパスは、バックエンドのプロパティーを指している必要があり、その値はリンクの名前として表示されます。このようなリンクをユーザーがクリックすると、「コンテンツ区画」が更新されて、セットの page サブ要素で指定されたページが表示されます。

Interaction 要素: xmlHandler, event, action, choose, command

<!ELEMENT xmlHandler (event+, action+)>
<!ATTLIST xmlHandler apt:name ID #REQUIRED>

<!ELEMENT event EMPTY>
<!ATTLIST event apt:type (onChange) #IMPLIED>

<!ELEMENT action (choose|command)+>

<!ELEMENT choose (when+, otherwise?)>

<!ELEMENT when (command+)>
<!ATTLIST when apt:test CDATA #REQUIRED>

<!ELEMENT otherwise (command+)>

<!ELEMENT command (#PCDATA)>

xmlHandler 要素は、クライアント側で JavaScript コードを実行する場合に使用します。コードの実行は、環境の変化によってトリガーされます。このような変化はイベントで伝播されます。イベントは、状態が変わった場合にプロパティーによって発行されます。イベントタイプは変化の種類を示します。

XML ハンドラを定義するには、apt:template 要素のxmlHandler サブ要素を指定します。これは、apt:name 属性で定義された名前が必要です。XML ハンドラは、property 要素の apt:xmlHandler 属性を指定 (XML ハンドラの名前をその値として使用) して、プロパティーが発行したイベントを待機するように登録されます。

event 要素は、xmlHandler が待機するイベントを、その apt:type 属性を使用して指定する場合に使用します。ここでは、onChange 要素のみを定義します。このイベントは、ユーザーがその値を変更した場合にプロパティーによって発行されます。プロパティーの値は、たとえば、ユーザーが編集フィールドでキーを入力したり、チェックボックスをオフにしたり、リストボックスでエントリを選択してこの入力を変更した瞬間に変化します。GUI 要素にフォーカスを移したり、GUI 要素からフォーカスを外しても、このイベントはトリガーされません。

1 つまたは複数のプロパティーでイベントのハンドラが登録され、これらのプロパティーのいずれかでそのイベントが発生した場合に、action 要素で定義されているコードが実行されます。action 要素には、 choose 要素か command 要素が少なくとも 1 つ含まれています。

command 要素は、クライアント側で実行される命令を指定します。現時点で含めることができるのは代入式のみです。代入式の左辺および右辺でも計算は許可されていません。代入式のスキーマは次のとおりです。<variable>=<value>.

ドット表記 <property>.<qualifier>. <property> はプロパティーの名前である必要があります。<qualifier> は次の 2 つの値を持つことができます。「value」および「enabled」。value 修飾子はそのプロパティーの値を提供します。変数の値は、プロパティーで指定されているタイプと互換性がある限り、読み取ってどの値にでも確定できます。enabled 修飾子には、プロパティーが有効になっている (フォーカスを受け取れる) 場合は「true」が含まれ、そうでない場合は「false」が含まれます。これを読み取って「true」または「false」に設定できます。例: propname.enabled=false.

choose 要素は XSLT で定義される choose 要素に似ており、コマンドを条件付きで実行できます。when 要素を少なくとも 1 つ含んでいる必要があり、末尾に otherwise 要素を 1 つ含むことができます。

when 要素には、 1 つまたは複数の command サブ要素と 1 つの apt:test 属性があります。test 属性では、ブール値に評価される式を指定する必要があります。

式は、変数、数字、文字列、および次のトークンで構成できます。

= 

等しい 

!= 

等しくない 

&lt; 

より小さい 

&gt; 

より大きい 

&lt;= 

より小さい、または等しい 

&gt;= 

より大きい、または等しい 

( ) 

挿入要素 

not() 

ブール演算子 NOT 

and 

ブール演算子 AND 

or 

ブール演算子 OR 

true 

ブール肯定 

false 

ブール否定 

例: (propname.enabled!=false) and not(propname.value='foo').

式が「true」に評価される場合は、when 要素のコマンドが実行され、choose ステートメントが実行されます。「false」に評価される場合は、次の when 要素が評価されます。どの when 要素も true ではなく、otherwise 要素が指定されている場合は、otherwise 要素のコマンドが実行されます。