1# Leaflet Plugin Authoring Guide
  2
  3One of the greatest things about Leaflet is its powerful plugin ecosystem.
  4The [Leaflet plugins page](http://leafletjs.com/plugins.html) lists dozens of awesome plugins, and more are being added every week.
  5
  6This guide lists a number of best practices for publishing a Leaflet plugin that meets the quality standards of Leaflet itself.
  7
  81. [Presentation](#presentation)
  9	- [Repository](#repository)
 10	- [Name](#name)
 11	- [Demo](#demo)
 12	- [Readme](#readme)
 13	- [License](#license)
 142. [Code](#code)
 15	- [File Structure](#file-structure)
 16	- [Code Conventions](#code-conventions)
 17	- [Plugin API](#plugin-api)
 18
 19## Presentation
 20
 21### Repository
 22
 23The best place to put your Leaflet plugin to is a separate [GitHub](http://github.com) repository.
 24If you create a collection of plugins for different uses,
 25don't put them in one repo —
 26it's usually easier to work with small, self-contained plugins in individual repositories.
 27
 28### Name
 29
 30Most existing plugins follow the convention of naming plugins (and repos) like this: `Leaflet.MyPluginName`.
 31You can use other forms (e.g. "leaflet-my-plugin-name"),
 32just make sure to include the word "Leaflet" in the name so that it's obvious that it's a Leaflet plugin.
 33
 34### Demo
 35
 36The most essential thing to do when publishing a plugin is to include a demo that showcases what the plugin does —
 37it's usually the first thing people will look for.
 38
 39The easiest way to put up a demo is using [GitHub Pages](http://pages.github.com/).
 40A good [starting point](https://help.github.com/articles/creating-project-pages-manually) is creating a `gh-pages` branch in your repo and adding an `index.html` page to it  —
 41after pushing, it'll be published as `http://<user>.github.io/<repo>`.
 42
 43### Readme
 44
 45The next thing you need to have is a descriptive `README.md` in the root of the repo (or a link to a website with a similar content).
 46At a minimum it should contain the following items:
 47
 48- name of the plugin
 49- a simple, concise description of what it does
 50- requirements
 51	- Leaflet version
 52	- other external dependencies (if any)
 53	- browser / device compatibility
 54- links to demos
 55- instructions for including the plugin
 56- simple usage code example
 57- API reference (methods, options, events)
 58
 59### License
 60
 61Every open source repository should include a license.
 62If you don't know what open source license to choose for your code,
 63[MIT License](http://opensource.org/licenses/MIT) and [BSD 2-Clause License](http://opensource.org/licenses/BSD-2-Clause) are both good choices.
 64You can either put it in the repo as a `LICENSE` file or just link to the license from the Readme.
 65
 66## Code
 67
 68### File Structure
 69
 70Keep the file structure clean and simple,
 71don't pile up lots of files in one place  &mdash;
 72make it easy for a new person to find their way in your repo.
 73
 74A barebones repo for a simple plugin would look like this:
 75
 76```
 77my-plugin.js
 78README.md
 79```
 80
 81An example of a more sophisticated plugin file structure:
 82
 83```
 84/src        - JS source files
 85/dist       - minified plugin JS, CSS, images
 86/spec       - test files
 87/lib        - any external libraries/plugins if necessary
 88/examples   - HTML examples of plugin usage
 89README.md
 90LICENSE
 91package.json
 92```
 93
 94### Code Conventions
 95
 96Everyone's tastes are different, but it's important to be consistent with whatever conventions you choose for your plugin.
 97
 98For a good starting point, check out [Airbnb JavaScript Guide](https://github.com/airbnb/javascript).
 99Leaflet follows pretty much the same conventions
100except for using smart tabs (hard tabs for indentation, spaces for alignment)
101and putting a space after the `function` keyword.
102
103### Plugin API
104
105Never expose global variables in your plugin.<br>
106If you have a new class, put it directly in the `L` namespace (`L.MyPlugin`).<br>
107If you inherit one of the existing classes, make it a sub-property (`L.TileLayer.Banana`).<br>
108If you want to add new methods to existing Leaflet classes, you can do it like this: `L.Marker.include({myPlugin: …})`.
109
110Function, method and property names should be in `camelCase`.<br>
111Class names should be in `CapitalizedCamelCase`.
112
113If you have a lot of arguments in your function, consider accepting an options object instead
114(putting default values where possible so that users don't need specify all of them):
115
116```js
117// bad
118marker.myPlugin('bla', 'foo', null, {}, 5, 0);
119
120 // good
121marker.myPlugin('bla', {
122	optionOne: 'foo',
123	optionThree: 5
124});
125```
126
127And most importantly, keep it simple. Leaflet is all about *simplicity*.