Adding Properties

プロパティの追加

Next, we'll find out how to add custom properties to XBL-defined elements.

次は、XBL で定義された要素にカスタムプロパティを追加する方法を見ることにしましょう。

The XBL Interface

XBL インターフェイス

JavaScript and the DOM provide access to get and set the properties of elements. With XBL, you can define your own properties for the elements you create. You can also add methods that can be called. That way, all you need is to get a reference to the element (using GetElementById or a similar function) and then get or set the additional properties and call the methods on it.

JavaScript と DOM には、要素のプロパティの取得と設定のためのアクセス手段があります。 XBL を使えば、自分で作った要素に自分のプロパティが定義できます。呼び出すことの できるメソッドを追加することもできます。このために必要なのは、 (GetElementById かそれに似た関数を使って) 要素への参照を取得し、次に 追加プロパティの取得と設定を行ない、メソッドを呼び出すだけです。

There are three types of items you can add. Fields are used to hold a simple value. Properties can also be used to hold a value but may have code execute when an attempt is made to retrieve or modify the value. Methods are functions which may be executed.

追加できる項目には 3 つのタイプがあります。フィールドは単純な値を保持するのに 使います。プロパティも値を保持するのに使いますが、値を戻そうとしたり変更しよう としたりしたときに、コードが実行される場合があります。メソッドは実行される関数です。

All three are defined within an implementation element, which should be a child of the binding element. Within the implementation, you define individual field, property, and method elements, one for each one that you want. The general syntax is as follows:

この 3 つとも全て、 implementation 要素内で定義できます。これは、 binding 要素の子供にします。 implementation 内には、それぞれ必要な個々の要素、 fieldpropertymethod を定義します。 一般的な構文は次の通りです。

<binding id="element-name">
  <content>
    -- content goes here --
  </content>
  <implementation>
    <field name="field-name-1"/>
    <field name="field-name-2"/>
    <field name="field-name-3"/>

    <property name="property-name-1"/>
    <property name="property-name-2"/>
    <property name="property-name-3"/>
    .
    .
    .
    <method name="method-name-1/>
      -- method content goes here --
    </method>
    .
    .
    .
  </implementation>
</binding>

Fields

フィールド

Each field is defined using the field element. Often, fields would correspond to an attribute placed on the element such as label or disabled, but they do not have to.

個々のフィールドは、 field 要素を使って定義します。しばしば、フィールドは labeldisabled など、要素に置かれた属性に対応しますが、 そうでなければならないという訳ではありません。

The name attribute on the field element is used to indicate the name of the field. You can use the name from a script to get and set the value. The example below creates a button which generates and stores a random number. You can retrieve this same number multiple times by getting the number property from the button. Most of the work here is done in the oncommand handlers. Later, we'll find out how to move this to XBL.

field 要素の name 属性を使って、フィールドの名前を指示します。 この名前は、その値の取得と設定のためスクリプトから使用することができます。 下の例は、乱数を生成し保存するためのボタンを作っています。ボタンの number プロパティを取得することにより、同じ数を 何度も取得することができます。ここでの仕事のほとんどは、 oncommand ハンドラで行なわれています。後で、これを XBL に移す方法を見ることにします。

XUL:

<box id="random-box" class="randomizer"/>

<button label="Generate"
           oncommand="document.getElementById('random-box').number=Math.random();"/>
<button label="Show"
           oncommand="alert(document.getElementById('random-box').number)"/>

XBL:

<binding id="randomizer">
  <implementation>
    <field name="number"/>
  </implementation>
</binding>

A number field has been defined in the binding, which stores the random number. The two extra buttons set and get the value of this field. The syntax is very similar to getting and setting the properties of HTML elements. In this example, no content has been placed inside either the XUL box or its definition in XBL, which is perfectly valid.

number フィールドは、バインディングで定義されています。 これは、乱数を保存するものです。追加した 2 つのボタンを使って、このフィールド の値の設定と取得を行ないます。その構文は、HTML 要素のプロパティの取得と設定に よく似ています。この例では、XUL ボックスにも XBL 内のその定義にも、まったく内容はありませんが、これは完全に妥当です。

This example isn't quite correct because the field is not assigned a default value. To do this, add the default value as the content of the field tag. For example:

この例は、まったく正しいという訳ではありません。フィールドにデフォルト値が 割り当てられていないからです。このため、 field タグの内容として デフォルト値を追加します。次の例を見て下さい。

<field name="number">
  25
</field>

This will assign the value 25 as the default value of the number field. Actually, you can instead place a script inside the field tag that evaluates to the default value. That might be necessary if the value needs to be computed. For example, the following field is given a default value equal to the current time:

ここでは、number フィールドのデフォルト値に 25 を割り当てています。 実際には、こうする代わりに field タグ内に、 デフォルト値を評価するスクリプトを置くこともできます。値を計算する必要が ある場合には、こうする必要があるかもしれません。例えば、次のフィールドは、 現在時刻と同じ値をデフォルトにしています。

<field name="currentTime">
  new Date().getTime();
</field>

Properties

プロパティ

Sometimes you will want to validate the data that is assigned to a property. Or, you may want the value to be calculated dynamically as it's asked for. For example, if you want a property that holds the current time, you would want to have its value generated as needed. In these cases, you need to use a property tag instead of a field tag. Its syntax is similar but has additional features.

時には、プロパティに割り当てるデータをチェックしたい場合があるでしょう。 また、必要に応じて、動的に値の計算がしたいかもしれません。例えば、現在時刻を 保持するプロパティが欲しい場合、必要な時に値を生成したいはずです。こういう場合には、 field タグではなくて property タグを使う 必要があります。構文は似ていますが、追加機能があります。

You can use the onget and onset attributes to have code execute when the property is retrieved or modified. Add each to the property element and set its value to a script which either gets or sets the value of the property.

プロパティを元に戻したり変更したりするときにコードを実行する、 ongetonset 属性が使えます。それぞれを property 要素に追加し、 その値を、プロパティの値の取得や設定を行なうスクリプトに設定します。

For example, you could assign a script to the value of onget to calculate the current time. Whenever a script attempts to access the value of the property, the onget script will be called to retrieve the value. The script should return the value that should be treated as the value of that property.

例えば、現在時刻を計算するため、スクリプトを onget に割り当てます。スクリプトがプロパティの値にアクセスするたびに、その値を取得 するため、onget のスクリプトが呼び出されます。 スクリプトは、そのプロパティの値として扱われるべき値を返します。

The onset handler is similar but is called whenever a script attempts to assign a new value to the property. This script should store the value somewhere, or validate the value. For example, some properties might only be able to store numbers. Attempting to assign alphabetic text to such a property should fail.

onset ハンドラも似ていますが、スクリプトを使って プロパティに新しい値を割り当てる場合に呼び出されます。このスクリプトは、値を どこかに保存するか、あるいはその値をチェックするべきものでしょう。例えば、 プロパティによっては、数値だけを保存できるものがあります。こうしたプロパティ にアルファベットからなるテキストを割り当てようとすると、エラーにすべきです。

<property name="size"
          onget="return 77;"
          onset="alert('Changed to:'+val); return val;"/>

This property will always return 77 when retrieved. When set, an alert will be displayed which displays the value to assign to the property. The special variable val holds the value that the property should be assigned to. Use this to validate it or store it. The onset property should also return the new value.

このプロパティは、取得するときには常に 77 を返します。 set するときには、 値がプロパティに割り当てられたことを示すアラートが表示されます。特殊変数 val は、プロパティに割り当てるべき値を保持します。 これを使って、値のチェックを行なったり、値を保存したりします。 onset プロパティも新しい値を返すべきでしょう。

The following decribes what happens in a typical case:

以下では、典型的な場合、何が起こるのか説明します。

There are two elements, one called 'banana' and the other 'orange'. They each have a custom property called 'size'. When the following line of script is executed:

'banana' と 'orange' という名前の 2 つの要素があります。それぞれに、'size' という名前のカスタムプロパティがあります。次のスクリプトを実行します。

banana.size = orange.size;
  1. The onget script is called for the size property of the orange. The script calculates the value and returns it.
  2. The onset handler of the size property of the banana is called. This script uses the value passed in the val variable and assigns it to the size property of the banana in some manner.
  1. orange の size プロパティを取得するため、onget スクリプトが呼び出される。スクリプトは値を計算し、それを返す。
  2. banana の size プロパティの onset ハンドラが呼び出される。 このスクリプトは val 変数に保存された値を受け取り、 それを banana の size プロパティに割り当てる。

Note that unlike a field, a property does not hold a value. Attempting to set a property that does not have an onset handler will generate an error. You will often use a separate field to hold the actual value of the property. It is also common to have the properties match an attribute on the XBL-defined element. The following example maps a property to an attribute on an element.

フィールドとは異なり、プロパティは値を保持しないことに気をつけてください。 onset ハンドラのないプロパティを設定しようとすると、 エラーになります。プロパティの実際の値を保持するために、別にフィールドを使う ことがよくあります。プロパティを XBL で定義された要素の属性と一致させることも よくあります。次の例は、プロパティを要素の属性にマップしています。

<property name="size"
          onget="return this.getAttribute('size');"
          onset="return this.setAttribute('size',val);"
/>

Whenever a script attempts to get the value of the property, it is grabbed instead from the attribute on the element with the same name. Whenever a script attempts to set the value of a property, it is set as an attribute on the element. This is convenient because then you can modify the property or the attribute and both will have the same value.

スクリプトによってプロパティの値を取得しようとするときはいつでも、プロパティ ではなく要素の同じ名前の属性が取得されます。スクリプトによって値を設定しようと するときはいつでも、値は要素の属性に設定されます。このようにすると、プロパティ や属性を変更しても、両方は同じ値になるので便利です。

You can use an alternate syntax for the onget and onset attributes that is useful if the scripts are longer. You can replace the onget attribute with a child element called getter. Similarly, you can replace the onset attribute with a setter element. The example below shows this:

onget 属性と onset 属性には別の構文が使えます。これは、スクリプトが長い場合に役立ちます。 onget 属性は、 getter という名前の 子供要素で置き換えることができます。同様に、 onset 属性は、 setter 要素で置き換える ことができます。以下はこの例です。

<property name="number">
  <getter>
    return this.getAttribute('number');
  </getter>
  <setter>
    var v = parseInt(val,10);
    if (!isNaN(v)) return this.setAttribute('number',''+v);
    else return this.getAttribute('number');"
  </setter>
</property>

The property in this example will only be able to hold integer values. If other characters are entered, they are stripped off. If there are no digits, the value is not changed. This is done in the code inside the setter element. The real value of the property is stored in the number attribute.

この例のプロパティは整数値だけを保持できます。それ以外の文字を入力すると 拒否されます。数値でなければ、値は変更されません。これは、 setter 要素内のコードで 行なわれています。プロパティの実際の値は、number 属性に保存されます。

You can use either syntax for creating get and set handlers.

取得や設定を行なうハンドラを作る場合、どちらの構文でも使えます。

You can make a field or property read-only by adding a readonly attribute to the field tag or property tag and setting it to true. Attempting to set the value of a read-only property will fail.

field タグや property タグに readonly 属性を追加し、それを true に設定することにより、フィールドやプロパティを 読み取り専用にすることができます。読み取り専用のプロパティに値を設定しようとすると、 エラーになります。


(Next) The next section shows how to add methods to XBL-defined elements.

(進む) 次のセクションでは、XBL で定義された要素にメソッドを追加する方法を見ることにしましょう。


Copyright (C) 1999 - 2004 XulPlanet.com
訳者: kmine
このドキュメントのオリジナルは XULPlanet において英語で公布されています。
またドキュメントの管理の言語は現在も英語です。この日本語訳は、
利用者の利便のために Mozilla Japan 翻訳部門によって提供されたものです。
フィードバックは英語で、元の著者に送って下さい。
翻訳された文書の一覧は、現在以下のURLで見ることが出来ます。
http://www.mozilla.gr.jp/jt/xul/progress.html