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 は、リポジトリの構成データの種類を指定するために使用します。次のタイプが定義されます。

以上のタイプは 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」を参照してください。