Sencha CmdにはSencha Package Managerが含まれます。パッケージには多くの使い方があり、それは作成したパッケージを配布しない場合でも同じです。このガイドでは、独自のパッケージの作成と配布のプロセスについて説明します。パッケージの使用については、Sencha Cmdパッケージをご覧ください。
パッケージの作成
新しいパッケージを作成する前に、まずそのホームであるワークスペースを作成しなくてはなりません。この例では、パッケージに Ext JSを使用し、次のコマンドで開始します。
sencha -sdk /path/to/ext-n.n.n generate workspace /path/to/workspace次に、新しいワークスペースに移動しパッケージを作成します。
cd /path/to/workspace
sencha -sdk ext generate package fooパッケージの構造
上の手順では、一般に使われるパーツを多く含むスターターパッケージが作成されます。これらの多くは削除することができますが、".sencha"フォルダは手つかずで残しておくことが重要です。
sencha generate packageで作成されたパッケージの構造は次のようになります。
packages/
foo/ # Top-level folder for the package
.sencha/
package/
sencha.cfg # Sencha Cmd configuration for this package
build-impl.xml # Generated build script for package
plugin.xml # Sencha Cmd plugin for this package
codegen.json # Data to support 3-way merge in code generator
docs/ # Documentation for the package
screenshots/ # Screen shots for Sencha Market
licenses/ # License agreement
overrides/ # Folder for automatically activated overrides
resources/ # Static resources (typically has images folder)
sass/ # Container for Sass code
etc/ # General, non-component oriented Sass
src/ # Sass rules and mixins named by component
var/ # Sass variables named by component
src/ # Folder for normal JavaScript code
build.xml # Build script (called by `sencha package build`)
package.json # Package descriptor
Readme.md # High-level information about this package上記は極めて膨大ですが、パッケージとなるために必要な部分は"package.json"および ".sencha/package/sencha.cfg"だけです。
"package.json"ファイルはパッケージの記述を含んでいます。"ext-theme-neptune"パッケージの場合の例は次のとおりです。
{
"name": "ext-theme-neptune",
"type": "theme",
"creator": "Sencha",
"summary": "Ext JS Neptune Theme",
"detailedDescription": "The Neptune Theme provides a clean, modern style for Ext JS",
"version": "n.n.n",
"compatVersion": "n.n.n",
"format": "1",
"extend": "ext-theme-neutral"
}creatorプロパティは、パッケージの作成者として設定する必要があります。このテキストの検証はありませんが、後に説明するローカルパッケージのリポジトリに設定する名前と合っていなくてはなりません。
".sencha/package/sencha.cfg"ファイルは、sencha package build中にSencha Cmdが使用するため、パッケージの開発者にとって非常に重要です。それはまた、sencha app buildプロセス中にユーザーアプリケーションでも使用されます。
アプリケーションビルドにパッケージを統合
ほとんどのパッケージの目的は（最終的に）アプリケーションに統合されることです。これを達成するため、Sencha Cmdは、必要な各パッケージの様々なパーツを、sencha app buildプロセス中にアプリケーションに組み込みます。
正確にどう行われるかはパッケージのtypeによって異なります。
パッケージタイプ
パッケージのタイプが異なると役割も異なります。Sencha Cmdは次のタイプのパッケージを扱います。
code- アプリケーションや他のパッケージで使用する任意のコードパッケージ。これらのパッケージは汎用性があり、それらを選択するrequire文がある場合に含まれます。theme- アプリケーションのテーマとして使用するパッケージ。テーマの特別な点は、themeタイプのパッケージはビルド内で1つだけしか「アクティブ」になれないことです。このテーマはapp.themeプロパティで選択され、require内にある他のすべてのテーマパッケージをフィルタリングして除外させます。テーマはextendを使って、Sassとリソースを別のテーマパッケージから継承することができます。locale- ローカリゼーション文字列または地域固有のコードを含むパッケージ。これらのパッケージはthemeパッケージと類似した選択メソッドを使用します。このタイプのパッケージは"locale"と呼ばれる"package.json"にプロパティを追加します。これは、このパッケージが適用されるロケールの名前として設定する必要があります（ヘブライ語の"he"など）。app.localeプロパティが設定されている場合、そのlocale内で異なる値を持つこのタイプのパッケージがフィルタリングされ除外されます。これは、同じlocale値を持つ異なるロケールパッケージを複数作成し、すべて含められることを意味します。
ソースコード
"src"フォルダには、カスタムコンポーネントやその他の便利なコードなどのクラスを入れます。このコードは、アプリケーションまたは他のパッケージがrequireして使用するclasspathに自動的に含まれます。
これは、ほとんどのJavaScriptコードを入れるであろう場所です。このフォルダに入れられるクラスはコンパイラに優しいコードガイドラインに従っている必要があります。
Sass
"sass"フォルダには、Sassコンパイルを様々な点で処理するよう設計された3つのサブフォルダが含まれます。
"sass/etc"- JavaScriptクラスに直接関係していないコード"sass/var"- 変数定義（JavaScriptクラス階層のミラーリング）"sass/src"- ミックスインとルール（JavaScriptクラス階層のミラーリング）
"sass/var" および "sass/src" 内のフォルダとファイルは、適用される JavaScript クラスのミラーイメージとなるよう整理されています。この対応により、Sencha Cmdはアプリケーションで必要とされるファイルを含むことができます。こうしたフォルダ内でこれに適合しないファイルは決して含まれません。なぜならプロセスが、フォルダのスキャンではなく、JavaScriptクラス階層をファイルシステムにマッピングすることで進行するからです。
package.sass.namespace（ ".sencha/package/sencha.cfg"内）は、スタイルが適用されるトップレベルの名前空間を決定します。パッケージのデフォルトはExtです。Sassと、パッケージの名前空間内のクラスを関連付けるためには、おそらくこれを変更する必要が出てくるでしょう。
リソース
"resources"フォルダには、パッケージが必要とする静的リソースが入ります。アプリケーションがパッケージを消費するとき、これらのリソースを、そのパッケージ名が付いた自身の"resources"フォルダのサブフォルダにコピーします。このケースでは"resources/foo"です。提供されたtheme-background-imageメソッドを使う場合、Sassが使用する関連パスは自動的に修正されます。
オーバーライド
"overrides"フォルダは、特にパッケージが必須のオーバーライドを提供するためのもので、そのためこの名前がついています。このメカニズムの使用には注意が必要です。なぜなら、このフォルダに入れるコードはすべて、このパッケージを使用するアプリケーションに自動的に要求されるからです。
Ext JS Neptune Themeはこのメカニズムを使って、様々なコンポーネントの特定のデフォルトコンフィグプロパティを変更します。ロケールパッケージはこれを使って、様々なコンポーネントのプロトタイプに自身のテキストを挿入したり、日付の体裁などのための地域固有ロジックを提供したりします。
パッケージのバージョン
パッケージには、その現在のバージョン番号を記述するversionプロパティがあります。現在のバージョン（versionプロパティ内）に加え、パッケージもまた、compatVersionプロパティを使って下位互換性のレベルを示すことができます。
これらのバージョンは、パッケージ要求を解決すれるときに使用されます。パッケージの各リリースは最新のバージョン番号を持つべきです。Senchaがバージョン番号に与えた意味が役立つかもしれません。
x.y.z.b
x = Major release number (large, impacting changes and features)
y = Minor release number (new functionality but few if any breaking changes)
z = Patch release number (bug fix / maintenance release - goal of 100% compatible)
b = Build number (assigned by build system)versionプロパティは通常、メンテナンスが最も簡単です。しかしcompatVersionは、ユーザーが透過的にアップグレードできコード変更を必要としないレベルに関する意図的な文です。
パッケージ要求
パッケージは、アプリケーションがパッケージを要求するのと同様に他のパッケージを要求できます。これを行うには、requires配列に追加が必要です。
{
"name": "bar",
"type": "code",
"creator": "anonymous",
"summary": "Short summary",
"detailedDescription": "Long description of package",
"version": "1.0.0",
"compatVersion": "1.0.0",
"format": "1",
"local": true,
"requires": [
'ext-easy-button'
]
}注意：パッケージ作成者としてバージョン制限を設ける場合、アプリケーションと必要なすべてのパッケージは、一致して共通バージョンでなくてはなりません。制限を強めすぎると、このプロセスは、必要なすべてのパッケージについて相互に一致するバージョンを見つけられません。
パッケージ継承
パッケージの継承の概念は、テーマだけを対象としています。継承パッケージのコンテンツが派生パッケージに入り込む、最も重要なやり方がいくつかあります。
継承パッケージの* "resources"フォルダは、"build"出力フォルダ内の"resources"フォルダにコピーされます。 * ベースパッケージのoverridesは、派生パッケージのビルド出力に自動的に含まれます。
パッケージの構築
パッケージを公開するには、次を使って構築する必要があります。
sencha package buildこの手順で、パッケージ内に"build"フォルダを生成します。アプリケーションが「dev mode」で実行（コンパイルなしで）されているとき、アプリケーションがこれを必要とします。また、ワークスペースの"build"フォルダ内に"foo.pkg"を作成します。このファイルは、次の理由でパッケージの"build"フォルダには入れられません。
- パッケージの ZIPファイルである。
- パッケージのユーザーに必要とされていない。
"foo.pkg"ファイルは、ローカルリポジトリにパッケージを追加するために使われます。次をご覧ください。
注意：Sencha Cmdの旧バージョンでは、テーマに依存するSassを持つ場合、sencha package buildが失敗する場合があります。この制限に対処するため、skip.sassおよびskip.sliceプロパティを".sencha/package/sencha.cfg"に設定できます。テーマがsencha app buildに含まれるため、パッケージがアプリケーションで使用できるようになります。
ローカルリポジトリ
ローカルリポジトリはSencha Cmdパッケージで紹介されていますが、作成したパッケージを配布したい場合はさらに詳しく知る必要があります。
構造
Sencha Cmdで作成されたローカルリポジトリは次のようになります。
.sencha/
repo/
sencha.cfg # Sencha Cmd configuration for the repo
plugin.xml # Plugin for repository hooks
private-key.json # Private key for repo
remotes/ # Storage for remote repositories
remoteName/ # Name given at `sencha repo add`
catalog.json # Last catalog from this remote
trust/ # Unused in this release
<somename>.cert.json # Copy of `cert.json` (a public key)
pkgs/
catalog.json # Catalog of all packages in this repo
cert.json # Public key for this repo
Foo/
catalog.json # Catalog for all versions of Foo package
cert.json # Public key for creator of Foo package
1.0/ # Folder containing version 1.0
Foo.pkg # Zip file of package
package.json # Extracted package descriptor
1.1/
...
Bar/
...作成者の識別
Sencha Cmdがデフォルトのローカルリポジトリを作成すると、識別というものの提供を要求しなくなります。これはキャッシュとしての役割には良いことですが、パッケージ作成者としては、公開するパッケージに名前を入れる必要があります。パッケージを公開する前に、ローカルリポジトリを識別で初期化する必要があります。
sencha package repo init -name "My Company" -email "[email protected]"この手順後、名前と電子メールアドレスが、新しい公開鍵／秘密鍵のペアとともにローカルリポジトリに記録されます。
注意：name引数は、"package.json"で設定したcreatorプロパティの値と一致しなくてはなりません。
公開鍵／秘密鍵
名前、電子メールおよび公開鍵は、"pkgs/cert.json"ファイルに格納されます。このファイルは作成するパッケージに自動的に追加され、パッケージ作成者を識別します。
名前で明らかなように、秘密鍵は他者と共有するためのものではありません。それは".sencha/repo/private-key.json"内のローカルリポジトリに格納されています。
将来のリリースでさらに重要な役割を担うため、これら2つのファイルはバックアップしてもかまいません。
コンテンツ
"pkgs"フォルダには、すべてのパッケージが格納されています。これらは作成したパッケージやダウンロードしたパッケージです。
パッケージの".pkg"ファイルを追加すると、"pkgs"フォルダツリーにコピーされます。
リポジトリフック
".sencha/repo/plugin.xml"ファイルは、sencha package addなどのリポジトリアクションにフックを提供できるAntスクリプトです。この詳細については、作成されたファイルのコメントをご覧ください。
初版:Sencha Cmd vn.n.n
パッケージの追加
ビルドから".pkg"ファイルを入手し、ローカルリポジトリに識別として設定したnameが、"package.json"で定義したcreatorと一致するとすれば、このコマンドを実行できます。
sencha package add foo.pkgSencha Cmdは、秘密鍵を使って".pkg"ファイルのハッシュを生成し、指定する".pkg"に追加できます。それから、そのファイルをローカルリポジトリにコピーします。
パッケージがリポジトリ内にあり、自分のリポジトリをリモートとして追加した場合、他の開発者がそれをrequireできます。
Senchaが".pkg"をSencha Package Repositoryに追加することを要求するプロセスはファイナライズ処理中ですが、これについての更新をSencha Marketにより確認できます。
パッケージリポジトリのホスティング
"pkgs"フォルダの構造は、リモートリポジトリを想定しています。作成したパッケージを他者がrequireするために必要なのは、パッケージをリモートリポジトリに追加することです。
sencha package repo add my-company http://my.company.com/packagesつまり、上のHTTP URLで"pkgs"フォルダのコンテンツをホストしたと想定できます。HTTP GETアクセスを超えたホスティングに必要なものがないため、静的ファイルサーバーまたはCDNが働きます。