APIドキュメントの読み進め方



[Sencha Advent Calendar 2012](http://www.adventar.org/calendars/23)の17日目担当の神代です。

sencha touch始めたてのとき、Ext.define時に指定する各プロパティはおまじないのようにお覚えていました。（またはスニペット化）

そのような状況はよくないので、[APIドキュメント](http://docs.sencha.com/touch/2-0/)をどのように参照しながら、Ext.defineの指定をすればよいのか。メモしておきたいと思います。

## Ext.defineの構造

慣例でもあるのか、だいたい設定するプロパティの順番は決まっているような気がします。
その是非は置いておいて、とりあえずこんな感じ。

※下部で記載する「●●定義エリア」は私が勝手に名付けたものなので、公式な名称ではありません

```javascript:SamplePanel.js
Ext.define('Sample.view.SamplePanel',{

	/*---------------------------------
		クラス定義エリア
	----------------------------------*/

	config: {
		/*---------------------------------
			各クラスのプロパティ定義エリア
		----------------------------------*/
	},

	/*---------------------------------
		独自メソッド定義エリア
	----------------------------------*/
});
```

## クラス定義エリア

こちらは、クラスそのものの振る舞いを設定するエリア。
[Ext.Class](http://docs.sencha.com/touch/2-0/#!/api/Ext.Class)のConfigsの値を設定しています。

例えば、Ext.Panelを継承してクラスを定義したい場合は、下記のように記載します

```javascript:SamplePanel.js
Ext.define('Sample.view.SamplePanel',{

	/*---------------------------------
		クラス定義エリア
	----------------------------------*/
	extend: 'Ext.Panel',  // ★Ext.Panelを継承

	config: {
		/*---------------------------------
			各クラスのプロパティ定義エリア
		----------------------------------*/
	},

	/*---------------------------------
		独自メソッド定義エリア
	----------------------------------*/
});
```

そのほか、どのようなプロパティがあるのかは、[Ext.Class](http://docs.sencha.com/touch/2-0/#!/api/Ext.Class)のConfigsの内容をみるとわかります

![スクリーンショット](https://pbs.twimg.com/media/A-TIx_FCAAAp99U.png:large)

## 各クラスのプロパティ定義エリア

継承したクラスのプロパティを上書きするエリア。

上記例で言えば、Ext.Panelは作成時は表示(display:block)します。
これを作成時に非表示（display:none）にするように設定を上書くことができます

```javascript:SamplePanel.js
Ext.define('Sample.view.SamplePanel',{

	/*---------------------------------
		クラス定義エリア
	----------------------------------*/
	extend: 'Ext.Panel',

	config: {
		/*---------------------------------
			各クラスのプロパティ定義エリア
		----------------------------------*/
		hidden: true // ★初期表示で非表示にする
	},

	/*---------------------------------
		独自メソッド定義エリア
	----------------------------------*/
});
```

どのような設定ができるかを確認するには、継承したクラスのConfigsの部分をみることで把握できましす。[Ext.Panel](http://docs.sencha.com/touch/2-0/#!/api/Ext.Panel)では下記部分です。

![スクリーンショット](https://pbs.twimg.com/media/A-TI45dCIAAm-_B.png:large)

## 独自メソッド定義エリア

該当のクラスで利用するメソッドを定義するエリア。

例えば、定義したSamplePanelが表示した時にポップアップ(alert)を表示するようにするには
このエリアに、ポップアップ部分の関数を定義しておきます

```javascript:SamplePanel.js
Ext.define('Sample.view.SamplePanel',{

	/*---------------------------------
		クラス定義エリア
	----------------------------------*/
	extend: 'Ext.Panel',

	config: {
		/*---------------------------------
			各クラスのプロパティ定義エリア
		----------------------------------*/
		hidden: true
	},

	/*---------------------------------
		独自メソッド定義エリア
	----------------------------------*/
	/**
	 * ★表示時にコールされる関数
	 */
	onShowAlert: function(){
		alert('show SamplePanel !!!');
	}
});
```

実際は**表示時のイベントの登録**が必要なのでその部分も追記します

※イベント登録に関しては、[Sencha Advent Calendar 2012の9日目、Sencha Touchでイベントを登録する方法](http://qiita.com/items/76e1b634f6b490a64900)をご覧ください

```javascript:SamplePanel.js
Ext.define('Sample.view.SamplePanel',{

	/*---------------------------------
		クラス定義エリア
	----------------------------------*/
	extend: 'Ext.Panel',

	config: {
		/*---------------------------------
			各クラスのプロパティ定義エリア
		----------------------------------*/
		hidden: true,

		// 表示時のイベント登録
		listeners: {
			show: 'onShowAlert'
		}
	},

	/*---------------------------------
		独自メソッド定義エリア
	----------------------------------*/

	/**
	 * 表示時にコールされる関数
	 */
	onShowAlert: function(){
		alert('show SamplePanel !!!');
	}
});
```

ここで、注意点が1点あります。

APIドキュメントの**Methods**の部分に記載されているメソッド名と同じメソッド名を定義してしまうと、メソッドも上書きしてしまうので必ず、重複しないような名前にしましょう。

![スクリーンショット](https://pbs.twimg.com/media/A-TJ_ILCAAAiY-i.png:large)


## その他APIドキュメントのTIPS

### ソースコードを直接参照する

各Configsの値、Methodsの値をAPIで参照し、説明がよくわからない場合は、
該当の部分にマウスオーバーすると右側に**view source**なるリンクが表示します

クリックすることで、実際のソースコードが閲覧できますので、そちらから内容を確認する手もあります

![スクリーンショット](https://pbs.twimg.com/media/A-TKp-PCcAAsmdL.png:large)

### コメント
APIドキュメントのConfigs,Methods,Eventsにはそれぞれコメントを書き込めるようになっています。APIドキュメントを参照する際にはこのコメントも同時に参照するといいことがあります

たとえば、

* サンプルが紹介されていたり
* ドキュメントの誤りが指摘されていていたりします

![スクリーンショット](https://pbs.twimg.com/media/A-TLLZ4CcAI7t2E.png:large)