Souke/vendor/bower/leaflet/PLUGIN-GUIDE.md

Leaflet Plugin Authoring Guide

One of the greatest things about Leaflet is its powerful plugin ecosystem. The Leaflet plugins page lists dozens of awesome plugins, and more are being added every week.

This guide lists a number of best practices for publishing a Leaflet plugin that meets the quality standards of Leaflet itself.

1. Presentation
   • Repository
   • Name
   • Demo
   • Readme
   • License
2. Code
   • File Structure
   • Code Conventions
   • Plugin API

Presentation

Repository

The best place to put your Leaflet plugin to is a separate GitHub repository. If you create a collection of plugins for different uses, don’t put them in one repo — it’s usually easier to work with small, self-contained plugins in individual repositories.

Name

Most existing plugins follow the convention of naming plugins (and repos) like this: Leaflet.MyPluginName. You can use other forms (e.g. “leaflet-my-plugin-name”), just make sure to include the word “Leaflet” in the name so that it’s obvious that it’s a Leaflet plugin.

Demo

The most essential thing to do when publishing a plugin is to include a demo that showcases what the plugin does — it’s usually the first thing people will look for.

The easiest way to put up a demo is using GitHub Pages. A good starting point is creating a gh-pages branch in your repo and adding an index.html page to it — after pushing, it’ll be published as http://<user>.github.io/<repo>.

Readme

The 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). At a minimum it should contain the following items:

• name of the plugin
• a simple, concise description of what it does
• requirements
  • Leaflet version
  • other external dependencies (if any)
  • browser / device compatibility
• links to demos
• instructions for including the plugin
• simple usage code example
• API reference (methods, options, events)

License

Every open source repository should include a license. If you don’t know what open source license to choose for your code, MIT License and BSD 2-Clause License are both good choices. You can either put it in the repo as a LICENSE file or just link to the license from the Readme.

Code

File Structure

Keep the file structure clean and simple, don’t pile up lots of files in one place — make it easy for a new person to find their way in your repo.

A barebones repo for a simple plugin would look like this:

my-plugin.js
README.md

An example of a more sophisticated plugin file structure:

/src        - JS source files
/dist       - minified plugin JS, CSS, images
/spec       - test files
/lib        - any external libraries/plugins if necessary
/examples   - HTML examples of plugin usage
README.md
LICENSE
package.json

Code Conventions

Everyone’s tastes are different, but it’s important to be consistent with whatever conventions you choose for your plugin.

For a good starting point, check out Airbnb JavaScript Guide. Leaflet follows pretty much the same conventions except for using smart tabs (hard tabs for indentation, spaces for alignment) and putting a space after the function keyword.

Plugin API

Never expose global variables in your plugin.
If you have a new class, put it directly in the L namespace (L.MyPlugin).
If you inherit one of the existing classes, make it a sub-property (L.TileLayer.Banana).
If you want to add new methods to existing Leaflet classes, you can do it like this: L.Marker.include({myPlugin: …}).

Function, method and property names should be in camelCase.
Class names should be in CapitalizedCamelCase.

If you have a lot of arguments in your function, consider accepting an options object instead (putting default values where possible so that users don’t need specify all of them):

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

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

And most importantly, keep it simple. Leaflet is all about simplicity.