Skip to content

Latest commit

 

History

History
153 lines (104 loc) · 9.91 KB

Alloy_Widgets.md

File metadata and controls

153 lines (104 loc) · 9.91 KB
Raw

Alloy Widget

本文書はAlloy Widgetsの日本語訳です。

はじめに

Widget は Alloy で実装された Titanium プロジェクトに簡単に追加できる自己完結型のコンポーネントです。Widget は、複数のアプリケーションでコードを再利用したり、同一アプリケーション内で複数回利用するための方法として、考え出されました。Widget は独自の View や Controller, style, asset を保持しており、 Alloy プロジェクトの app ディレクトリと同じように配置されています。

Widget を使う

プロジェクトで Widget を使う方法については [Importing Widgets] を参照してください。

Widget を作る

Widget は Alloy プロジェクトの app/widgets/ ディレクトリの中の個別のディレクトリに作成される必要があります。Widget はそれぞれ独自の View や Controller, Model, style, asset を保持しており、Alloy プロジェクトの app ディレクトリと同じように配置されています。配置については 設定より規約 を参照してください。また、Widget は自己完結しているので、i18n フォルダに配置される国際化・地域化ファイルを除いて、パスに含まれるコードや asset 以外を参照すべきではありません。Alloy プロジェクトと異なる点や、役立つ知見について、以下の項目で説明します。

Asset とライブラリ

assets フォルダや libs フォルダにあるファイルについては、Widget のルートフォルダからの相対パスを指定するのに、Alloy プロジェクトの app ディレクトリとは違って、 WPATH() マクロを利用してください。たとえば app/widgets/foo/lib/helper.js にライブラリがある場合、それを require するには require(WPATH('helper')); を使い、また、app/widgets/foo/assets/images/foo.png に画像がある場合、それを参照するには ```WPATH('images/foo.png') を使ってください。

設定

Widget はそれぞれ、 widget.json と呼ばれる設定ファイル設定ファイルを Widget のルートディレクトリに持っています。このファイルのフォーマットについては Widget 設定ファイル (widget.json) を参照してください。

Controller

メインの Controller は index.js ではなく widget.js です。

widget.js/widget.xml 以外の View Controller を使う場合には、Controller の新しいインスタンスを生成するのには Widget.createController(controller_name, [params]) メソッドを利用し、Titanium proxy オブジェクトにアクセスするには getView() メソッドを利用してください。たとえば、 Button View Controller を foo Widget で持っていたとします。これをメインの Widget View に追加するには、以下のようにしてください。

app/widgets/foo/controllers/widget.js

var button = Widget.createController('button').getView();
$.widget.add(button);

Widget Controller にあるメソッドは、 $ の prefix を付けて Alloy プロジェクトや他の Widget からアクセスできるようにしない限り、すべて private です。たとえば、Widget の Controller で以下のコードが定義されていた場合、

$.init = function (args) {
    // Button object with id=button
    $.button.title = args.title || 'Si';
    $.button.color = args.color || 'black';
    // global variable
    message = args.message || 'Hola mundo';
}

Alloy プロジェクトの中で、 Alloy プロジェクトの View (訳注: Widget の間違い！？)で指定された Widget ID を前につけて、 init を呼び出してください。この例では、その Widget ID は foo となります。

$.foo.init({title:'Yes', color:'gray', message:'I pity the foo.'});

Models

Widget.createModel(model_name, [params]) や Widget.createCollection(model_name, [params]) メソッドを使って Widget の Controller 内で Model や Collection を作成する点を除き、一般の Alloy プロジェクトと同じように Model を利用してください。 Widget の View で Model や Collection のタグを利用することもできます。

Styles

メインの TSS ファイルとして、 index.tss の代わりに widget.tss を利用します。

Views

メインの View は index.xml の代わりに widget.xml と呼ばれます。

XML markup コンポーネントの中で id 属性を指定することで、 Titanium オブジェクトのプロパティにアクセスしたり、上書きしたりするのが簡単になります。たとえば、Widget View の中に button という id のついた Button オブジェクトがあり、その Alloy プロジェクトで Widget の id が foo だった場合、Button プロパティにアクセスするには下記のようにします。

Ti.API.info("button state: " + $.foo.button.enabled);

複数の View Controller を持つ Widget の場合、 Widget タグを使って View Controller から拡張子を外した名前を name 属性で指定してください。たとえば、以下の markup は Controller の節での例と似ています。

app/widgets/foo/views/widget.xml

<Alloy>
    <View>
        <Widget src="foo" name="button"/>
    </View>
</Alloy>

Widgets

Widget は他の Widget を含むこともできます。Widget では config.json の代わりに widget.json を設定ファイルとして利用する点を除き、 [Importing Widgets] の指示に従ってください。また、 Widget の Controller 内で別の Widget を作るには、 Widget.createWidget(widget_name, [controller_name], [params]) メソッドを利用してください。