Leafletプラグイン作成ガイド

2013年6月28日投稿者: Vladimir Agafonkin

Leafletの最も素晴らしい点の一つは、強力なプラグインエコシステムです。 Leafletプラグインページには、数十もの素晴らしいプラグインがリストされており、毎週さらに追加されています。

このガイドでは、Leaflet自体の品質基準を満たすLeafletプラグインを公開するためのベストプラクティスをいくつか示します。リポジトリでも入手可能です。

公開

リポジトリ

Leafletプラグインを配置する最適な場所は、個別のGitHubリポジトリです。異なる用途のためのプラグインのコレクションを作成する場合は、それらを1つのリポジトリに配置しないでください。通常、小さな独立したプラグインを個々のリポジトリで扱う方が簡単です。

デモ

プラグインを公開する際に最も重要なことは、プラグインの機能を示すデモを含めることです。これは通常、人々が最初に探すものです。

GitHub Pagesを使用すると、デモを簡単に公開できます。良い出発点は、リポジトリにgh-pagesブランチを作成し、index.htmlページを追加することです。プッシュ後、http://<user>.github.io/<repo>として公開されます。

README

次に必要なのは、リポジトリのルートにある説明的なREADME.md（または同様のコンテンツを持つウェブサイトへのリンク）です。最低限、次の項目を含める必要があります。

プラグインの名前
その機能を簡潔に説明したもの
要件
- Leafletバージョン
- その他の外部依存関係（存在する場合）
- ブラウザ/デバイスの互換性
デモへのリンク
プラグインの組み込み手順
簡単な使用方法のコード例
APIリファレンス（メソッド、オプション、イベント）

ライセンス

すべてのオープンソースリポジトリにはライセンスを含める必要があります。コードにどのオープンソースライセンスを選択するか分からない場合は、MITライセンスとBSD 2-Clauseライセンスの両方が良い選択肢です。LICENSEファイルとしてリポジトリに配置するか、READMEからライセンスにリンクするかのいずれかを選択できます。

コード

ファイル構造

ファイル構造を清潔でシンプルに保ち、多くのファイルを1箇所に積み重ねないでください。新しい人がリポジトリ内を簡単に移動できるようにします。

シンプルなプラグインのための最小限のリポジトリは次のようになります。

my-plugin.js
README.md

より高度なプラグインのファイル構造の例

/src        JS source files
/dist       minified plugin JS, CSS, images
/spec       test files
/examples   HTML examples of plugin usage
README.md
LICENSE
package.json

コード規約

個々の好みは異なりますが、プラグインで選択した規約に一貫性を持たせることが重要です。

Airbnb JavaScript Guideを確認すると、良い出発点になります。Leafletは、スマートタブ（インデントにはハードタブ、配置にはスペースを使用）を使用し、functionキーワードの後にスペースを入れることを除いて、ほぼ同じ規約に従っています。

プラグインAPI

プラグインでグローバル変数を公開しないでください。
新しいクラスがある場合は、L名前空間（L.MyPlugin）に直接配置します。
既存のクラスを継承する場合は、サブプロパティにします（L.TileLayer.Banana）。
既存のLeafletクラスに新しいメソッドを追加する場合は、次のように行うことができます。L.Marker.include({myPlugin: …})。

関数、メソッド、プロパティの名前はcamelCaseにする必要があります。
クラス名はCapitalizedCamelCaseにする必要があります。

関数に多くの引数がある場合は、代わりにオプションオブジェクトを受け入れることを検討してください（可能な限りデフォルト値を設定することで、ユーザーがすべてを指定する必要がなくなります）。

// bad
marker.myPlugin('bla', 'foo', null, {}, 5, 0);

// good
marker.myPlugin('bla', {
	optionOne: 'foo',
	optionThree: 5
});

そして最も重要なのは、シンプルさを保つことです。Leafletはすべてシンプルさです。

敬具
Vladimir。