Adding Methods

メソッドの追加

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

次に、XBL で定義された要素にカスタムメソッドを追加する方法を見ることにしましょう。

Methods

メソッド

In addition to adding script properties to the XBL-defined element, you can also add methods. These methods can be called from a script. Methods are the functions of objects, such as 'window.open()'. You can define custom methods for your elements using the method element. The general syntax of methods is as follows:

XBL で定義された要素は、スクリプトプロパティを追加する以外に、メソッドを 追加することもできます。これらのメソッドは、スクリプトから呼び出すことができます。 メソッドとは、'window.open()' など、オブジェクトの関数です。 method 要素を使えば、 自分の要素のためのカスタムメソッドの定義ができます。メソッドの一般的な構文は 次の通りです。

<implementation>
  <method name="method-name">
    <parameter name="parameter-name1"/>
    <parameter name="parameter-name2"/>
    .
    .
    .
    <body>
      -- method script goes here --
    </body>
  </method>
</implementation>

A method declaration goes inside the implementation element, like the fields and properties do. The method element contains two type of child elements, parameter elements which describe the parameters to the method and body which contains the script for the method.

メソッドの宣言は、フィールドやプロパティの場合と同様に、 implementation 要素の中で行ないます。 method 要素には 2 種類の子供要素があります。メソッドへのパラメータを記述する parameter 要素と、 メソッドのスクリプトからなる body 要素です。

The value of the name attribute becomes the name of the method. Similarly, the name attributes on the parameter elements become the names of each parameter. Each parameter element is used to declare one parameter for the method. For example, if the method had three parameters, there would be three parameter elements. You do not need to have any though, in which case the method would take no parameters.

name 属性の値がメソッドの名前になります。同様に、 parameter 要素の name 属性が個々のパラメータの名前になります。個々の parameter 要素を使って、 メソッドへのパラメータのそれぞれを宣言します。例えば、メソッドにパラメータが 3 つある場合、parameter 要素が 3 つ必要です。パラメータが必要ない場合、parameter 要素は使いません。

The body element contains the script that is executed when the method is called. The names of the parameters are defined as variables in the script as if they had been passed as parameters. For example, the following JavaScript function would be written as an XBL method like so:

body 要素には、メソッドが 呼ばれたときに実行されるスクリプトを置きます。パラメータの名前は、あたかも パラメータとして渡されたかのように、スクリプト内の変数として定義します。 例えば、以下の JavaScript 関数は、XBL メソッドとして書くことができます。

function getMaximum(num1,num2)
{
  if (num1<=num2) return num2;
  else return num1;
}

XBL:

<method name="getMaximum">
  <parameter name="num1"/>
  <parameter name="num2"/>
  <body>
    if (num1&lt;=num2) return num2;
    else return num1;
  </body>
<method>

This function, getMaximum, returns the largest of the values, each passed as an parameter to the method. Note that the less-than symbol has to be escaped because otherwise it would look like the start of a tag. You can also use a CDATA section to escape the entire block of code. You can call the method by using code such as 'element.getMaximum(5,10)' where element is a reference to an element defined by the XBL containing the getMaximum method. (The bound element.)

getMaximum というこの関数は、メソッドにパラメータとして渡された値のうち、最大のものを返します。小なり記号をエスケープしなければならない点に注意して下さい。 そうしないと、タグの始まりと見られてしまいます。CDATA セクションを使って、コードブロック全てをエスケープすることもできます。メソッドは、'element.getMaximum(5,10)' のようなコードを使って呼び出すことができます。ここで、 element とは、XBL で定義された getMaximum メソッドをもつ要素 (XBL に結び付けられた要素) の参照です。

The parameter tag allows you to define parameters for a method. Because Mozilla uses JavaScript as its scripting language, and JavaScript is a non-typed language, you do not need to specify the types of the parameters. However, in the future, other languages may be used with XBL.

parameter タグを使って、 メソッドへのパラメータの定義ができます。Mozilla はスクリプト言語として JavaScript を使うので、また JavaScript は型のない言語なので、パラメータの型を指定する必要は ありません。しかし、将来、XBL で別の言語が使われるかもしれません。

Accessing the Anonymous Content

無名内容にアクセスする

There may be times when you want to modify some aspect of the elements defined in the content element, either from a method body or elsewhere. These elements are created anonymously and are not accessible from the regular DOM functions. They are hidden so that developers do not need to know how the element is implemented to use it. However, there is a special way of getting this anonymous content.

メソッド本体やその他の場所で、 content 要素内で 定義された幾つかの部分を変更したい場合があるかもしれません。これらの要素は 無名のまま作られているので、通常の DOM 関数からアクセスすることはできません。 これは隠されており、開発者は、これを使う上で、要素がどのように実装されているのか 知る必要はありません。しかし、この無名内容を取得する特別な方法があります。

Elements with an XBL behavior attached to them have a special property which holds an array of the anonymous child elements inside it. Each element of the array stores each direct child element of the XBL-defined element. This special property cannot be accessed directly. Instead, you must call the document's getAnonymousNodes method:

XBL の振る舞いを貼り付けられた要素には、内部に無名子供要素の配列をもつ特殊な プロパティがあります。配列の個々の要素には、XBL で定義された要素の直接の 無名子供要素それぞれが保存されています。この特殊プロパティに直接アクセス することはできません。その代わりに、document の getAnonymousNodes メソッドを 呼び出す必要があります。

var value=document.getAnonymousNodes(element);

Here, 'element' should be set a to reference to the element that you want to get the anonymous content of. The function returns an array of elements, which is the anonymous content. To get elements below that, you can use the regular DOM functions because they aren't hidden. Note that it is possible for an XBL-bound element to be placed inside another one, in which case you will have to use the getAnonymousNodes function again.

ここで、'element' には、無名内容を取得したい要素への参照を設定します。 関数は、要素の配列を返します。これは、無名内容です。その下の要素を取得するには、 通常の DOM 関数が使えます。それらの要素は隠されていないからです。XBL に 結び付けられた要素を別の要素の中に置くことができる点に注意して下さい。 その場合、getAnonymousNodes 関数を再度使用する必要があります。

The following example creates a row of buttons:

下の例は、ボタンの行を作ります。

<binding id="buttonrow">
  <content>
    <button label="Yes"/>
    <button label="No"/>
    <button label="Sort Of"/>
  </content>
</binding>

To refer to each button, you can use the getAnonymousNodes function, passing it a reference to the element the binding is bound to as the parameter. In the returned array, the first button is stored in the first array element ('getAnonymousNodes(element)[0]'), the second button is stored in the second array element and the third button is stored in the third array element. For code inside a binding method, you can pass 'this' as the parameter to getAnonymousNodes.

個々のボタンを参照するには、getAnonymousNodes 関数が使えます。そのためには、 パラメータとして、バインディングが結び付けられている要素への参照を渡します。 返される配列には、最初のボタンが最初の配列 ('getAnonymousNodes(element)[0]') に保存され、2 つ目のボタンが 2 番目の配列要素に、3 つ目のボタンが 3 番目の 配列要素に保存されます。バインディングメソッド内のコードでは、'this' を getAnonymousNodes へのパラメータとして渡すことができます。

The next example can be used to create text with a label. The method 'showTitle' can be used to show or hide the label. It works by getting a reference to the title element using the anonymous array and changing the visibility of it.

次の例を使えば、ラベル付きのテキストを作ることができます。メソッド 'showTitle' を使って、ラベルを表示したり隠したりできます。これは、無名配列を使ってタイトル 要素への参照を取得し、その可視性 (visibility) を変更することによって機能します。

XUL:

<box id="num" class="labeledbutton" title="Number of Things:" value="52"/>

<button label="Show" oncommand="document.getElementById('num').showTitle(true)"/>
<button label="Hide" oncommand="document.getElementById('num').showTitle(false)"/>

XBL:

<binding id="labeledbutton">
  <content>
    <xul:label xbl:inherits="value=title"/>
    <xul:label xbl:inherits="value"/>
  </content>
  <implementation>
    <method name="showTitle">
      <parameter name="state"/>
      <body>
        if (state) document.getAnonymousNodes(this)[0].
          setAttribute("style","visibility: visible");
        else document.getAnonymousNodes(this)[0].
          setAttribute("style","visibility: collapse");
      </body>
    </method>
  </implementation>
</binding>

Two buttons added to the XUL have oncommand handlers which are used to change the visibility of the label. Each calls the 'showTitle' method. This method checks to see whether the element is being hidden or shown from the 'state' parameter that is passed in. In either case, it grabs the first element of the anonymous array. This refers to the first child in the content element, which here is the first label widget. The visibility is changed by modifying the style on the element.

XUL に追加された 2 つのボタンには、ラベルの可視性を変更するのに使われる oncommand ハンドラがあります。それぞれのボタンは、 'showTitle' メソッドを呼び出します。このメソッドは、渡された 'state' パラメータを チェックして、ラベル要素を表示するか隠すかを判断します。どの場合も、無名配列の 最初の要素を捉えます。これは、 content 要素の最初の 子供を参照しています。ここでは、これは最初のラベルウィジェットです。可視性は、 要素のスタイルを変更することによって変更されています。

To go the other way, and get the bound element from inside the anonymous content, use the DOM 'parentNode' property. This gets the parent element of an element. For example, we could move the Show and Hide buttons into the XBL file and do the following:

別のことをする準備として、無名内容の中から XBL に結び付けられた要素を取得するため、 DOM の 'parentNode' プロパティを使います。これは、要素の親要素を取得します。 例えば、Show ボタンと Hide ボタンを XBL ファイルに移すには次のようにします。

Example 11.5.1: Source
<binding id="labeledbutton">
  <content>
    <xul:label xbl:inherits="value=title"/>
    <xul:label xbl:inherits="value"/>
    <xul:button label="Show" oncommand="parentNode.showTitle(true);"/>
    <xul:button label="Hide" oncommand="parentNode.showTitle(false);"/>
  </content>
  <implementation>
    <method name="showTitle">
      <parameter name="state"/>
      <body>
        if (state) document.getAnonymousNodes(this)[0].setAttribute("style","visibility: visible");
        else document.getAnonymousNodes(this)[0].setAttribute("style","visibility: collapse");
      </body>
    </method>
  </implementation>
</binding>

The oncommand handlers here first get a reference to their parent element. This is not the content element but the XUL element that the XBL is bound to. (In this example, it is the box with the labeledbutton class). Then, the 'showTitle' method is called, which functions as it did before.

ここでは、oncommand ハンドラは、まず、その親要素への 参照を取得します。これは content 要素ではなく、 XBL が結び付けられている XUL 要素です。(この例では、 labeledbutton クラスをもつボックスです。) 次に、 'showTitle' メソッドが呼び出されます。その機能は前の場合と同じです。

Custom properties and methods are added only to the outer XUL element the XBL is bound to. None of the elements declared inside the content tag have these properties or methods. This is why we have to get the parent first.

カスタムプロパティとメソッドは、XBL が結び付けられている外側の XUL 要素だけに 追加されます。content タグ内で宣言された要素は、これらのプロパティやメソッドをもつことはできません。 このため、まず、親を取得しなければならなかったのです。

The children of an element placed in the XUL file can be retrieved in the normal way and don't move even if you use the children tag. For example:

XUL ファイルに置かれた要素の子供は、通常の方法で取得できます。 children タグを使う場合 でも、それは変わりません。次のコードはその例です。

XUL:

<box id="outer" class="container">
  <button label="One"/>
  <button label="Two"/>
  <button label="Three"/>
  <button label="Four"/>
</box>

XBL:

<binding id="labeledbutton">
  <content>
    <description value="A stack:"/>
    <stack>
      <children/>
    </stack>
  </content>
</binding>

If you use the DOM functions such as 'childNodes' to get the children of an element, you'll find that the XUL box, the one with the id of outer, has 4 children. These correspond to its four buttons, even through those buttons are drawn inside the stack. The stack has only one child, the children element itself. The length of the anonymous array of the outer box is two, the first element the description element and the second the stack element.

要素の子供を取得するために 'childNodes' などの DOM 関数を使うと、 outer という id をもつ XUL ボックスには、子供が 4 つあることが分かります。これらは、4 つのボタンに 対応します。これらのボタンがスタック内に描画されている場合であっても、それは 変わりません。スタックには、子供が一つだけあります。 children 要素自身です。 外側のボックスの無名配列の長さは 2 で、最初の要素は description 要素、 2 番目の要素は stack 要素です。

Constructors and Destructors

コンストラクタとデストラクタ

XBL supports two special methods created with separate tags, constructor and destructor. A constructor is called whenever the binding is attached to an element. It is used to initialize the content such as loading preferences or setting the default values of fields. The destructor is called when a binding is removed from an element. This might be used to save information.

XBL は、 constructordestructor の区切りタグ で作られる 2 つの特殊メソッドをサポートしています。コンストラクタ (constructor) は、 バインディングが要素に貼り付けられるたびに呼び出されます。これは設定をロードしたり、 フィールドのデフォルト値をセットしたりするような、内容を初期化するのに使います。 デストラクタ (destructor) は、バインディングが要素から取り除かれるときに 呼び出されます。これは情報を保存するのに使われるでしょう。

There are two points when a binding is attached to an element. The first occurs when a window is displayed. All elements that have XBL-bound content will have their constructors invoked. The order that they are called in should not be relied upon, as they are loaded from various files. The window's onload handler is not called until after all the bindings have been attached and their constructors finished. The second point a binding is attached is if you change the -moz-binding style property of an element. The existing binding will be removed, after its destructor is called. Then, the new binding will be added in its place and its constructor invoked.

バインディングが要素に貼り付けられるときは、2 回あります。1 つ目は、ウィンドウが 表示されるときに起きます。XBL に結び付けられた内容を持つ要素は全て、自身の コンストラクタを持っていて、実行されます。色々なファイルからロードされるため、 呼び出される順番に依存するべきではありません。window の onload ハンドラは、 全てのバインディングが貼り付けられてそのコンストラクタが終了する後まで、 呼び出されません。バインディングが貼り付けられる 2 つ目は、要素の -moz-binding スタイルプロパティを変更した場合です。 デストラクタが呼び出された後、既にある要素が取り除かれます。それから、新しい バインディングがその場所に追加されて、コンストラクタが実行されます。

The script for a constructor or destructor should be placed directly inside the appropriate tag. There should only be at most one of each per binding and they take no arguments. Here are some examples:

コンストラクタやデストラクタ用のスクリプトは、適切なタグ内に直接置くべきです。 バインディングごとにほぼ一つだけ置き、引数無しにするべきです。以下に数例示します。

<constructor>
  if (this.childNodes[0].getAttribute("open") == "true"){
    this.loadChildren();
  }
</constructor>

<destructor action="saveMyself(this);"/>

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

(進む) 次のセクションでは、XBL で定義された要素にイベントハンドラを追加する方法を示します。

Examples: 11.5.1


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