You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221
  1. # Leaflet Plugin Authoring Guide
  2. One of the greatest things about Leaflet is its powerful plugin ecosystem.
  3. The [Leaflet plugins page](http://leafletjs.com/plugins.html) lists dozens of awesome plugins, and more are being added every week.
  4. This guide lists a number of best practices for publishing a Leaflet plugin that meets the quality standards of Leaflet itself.
  5. 1. [Presentation](#presentation)
  6. - [Repository](#repository)
  7. - [Name](#name)
  8. - [Demo](#demo)
  9. - [Readme](#readme)
  10. - [License](#license)
  11. 2. [Code](#code)
  12. - [File Structure](#file-structure)
  13. - [Code Conventions](#code-conventions)
  14. - [Plugin API](#plugin-api)
  15. 3. [Publishing on NPM](#publishing-on-npm)
  16. 4. [Module Loaders](#module-loaders)
  17. 5. [Adding to the plugins list](#adding-to-the-plugins-list)
  18. ## Presentation
  19. ### Repository
  20. The best place to put your Leaflet plugin to is a separate [GitHub](http://github.com) repository.
  21. If you create a collection of plugins for different uses,
  22. don't put them in one repo —
  23. it's usually easier to work with small, self-contained plugins in individual repositories.
  24. ### Name
  25. Most existing plugins follow the convention of naming plugins (and repos) like this: `Leaflet.MyPluginName`.
  26. You can use other forms (e.g. "leaflet-my-plugin-name"),
  27. just make sure to include the word "Leaflet" in the name so that it's obvious that it's a Leaflet plugin.
  28. ### Demo
  29. The most essential thing to do when publishing a plugin is to include a demo that showcases what the plugin does —
  30. it's usually the first thing people will look for.
  31. The easiest way to put up a demo is using [GitHub Pages](http://pages.github.com/).
  32. A 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 —
  33. after pushing, it'll be published as `http://<user>.github.io/<repo>`.
  34. ### Readme
  35. The next thing you need to have is a [good `README.md`](https://github.com/noffle/art-of-readme) in the root of the repo (or a link to a website with a similar content).
  36. At a minimum it should contain the following items:
  37. - name of the plugin
  38. - a simple, concise description of what it does
  39. - requirements
  40. - Leaflet version
  41. - other external dependencies (if any)
  42. - browser / device compatibility
  43. - links to demos
  44. - instructions for including the plugin
  45. - simple usage code example
  46. - API reference (methods, options, events)
  47. ### License
  48. Every open source repository should include a license.
  49. If you don't know what open source license to choose for your code,
  50. [MIT License](http://opensource.org/licenses/MIT) and [BSD 2-Clause License](http://opensource.org/licenses/BSD-2-Clause) are both good choices.
  51. You can either put it in the repo as a `LICENSE` file or just link to the license from the Readme.
  52. ## Code
  53. ### File Structure
  54. Keep the file structure clean and simple,
  55. don't pile up lots of files in one place &mdash;
  56. make it easy for a new person to find their way in your repo.
  57. A barebones repo for a simple plugin would look like this:
  58. ```
  59. my-plugin.js
  60. README.md
  61. ```
  62. An example of a more sophisticated plugin file structure:
  63. ```
  64. /src - JS source files
  65. /dist - minified plugin JS, CSS, images
  66. /spec - test files
  67. /lib - any external libraries/plugins if necessary
  68. /examples - HTML examples of plugin usage
  69. README.md
  70. LICENSE
  71. package.json
  72. ```
  73. ### Code Conventions
  74. Everyone's tastes are different, but it's important to be consistent with whatever conventions you choose for your plugin.
  75. For a good starting point, check out [Airbnb JavaScript Guide](https://github.com/airbnb/javascript).
  76. Leaflet follows pretty much the same conventions
  77. except for using smart tabs (hard tabs for indentation, spaces for alignment)
  78. and putting a space after the `function` keyword.
  79. ### Plugin API
  80. Never expose global variables in your plugin.<br>
  81. If you have a new class, put it directly in the `L` namespace (`L.MyPlugin`).<br>
  82. If you inherit one of the existing classes, make it a sub-property (`L.TileLayer.Banana`).<br>
  83. Every class should have a factory function in camelCase, e.g. (`L.tileLayer.banana`).<br>
  84. If you want to add new methods to existing Leaflet classes, you can do it like this: `L.Marker.include({myPlugin: …})`.
  85. Function, method, property and factory names should be in `camelCase`.<br>
  86. Class names should be in `CapitalizedCamelCase`.
  87. If you have a lot of arguments in your function, consider accepting an options object instead
  88. (putting default values where possible so that users don't need to specify all of them):
  89. ```js
  90. // bad
  91. marker.myPlugin('bla', 'foo', null, {}, 5, 0);
  92. // good
  93. marker.myPlugin('bla', {
  94. optionOne: 'foo',
  95. optionThree: 5
  96. });
  97. ```
  98. And most importantly, keep it simple. Leaflet is all about *simplicity*.
  99. ## Publishing on NPM
  100. NPM (Node Packaged Modules) is a package manager and code repository for JavaScript. Publishing your module on NPM allows other developers to quickly find and install your plugin as well as any other plugins it depends on.
  101. NPM has an excellent [developers guide](https://www.npmjs.org/doc/misc/npm-developers.html) to help you through the process.
  102. When you publish your plugin you should add a dependency on `leaflet` to your `package.json` file. This will automatically install Leaflet when your package is installed.
  103. Here is an example of a `package.json` file for a Leaflet plugin.
  104. ```json
  105. {
  106. "name": "my-leaflet-plugin",
  107. "version": "1.0.0",
  108. "description": "A simple leaflet plugin.",
  109. "main": "my-plugin.js",
  110. "author": "You",
  111. "license": "IST",
  112. "peerDependencies": {
  113. "leaflet": "^1.0.0"
  114. }
  115. }
  116. ```
  117. If possible, do not commit your minified files (e.g. `dist`) to a repo; this can
  118. lead to confussion when trying to debug the wrong file. Instead, use `npm` to
  119. trigger a build/minification just before publishing your package with a
  120. [`prepublish` script](https://docs.npmjs.com/misc/scripts#common-uses), for example:
  121. ```json
  122. {
  123. "name": "my-leaflet-plugin",
  124. ...
  125. "scripts": {
  126. "prepublish": "grunt build"
  127. }
  128. }
  129. ```
  130. You can then use the [`.gitignore`](https://help.github.com/articles/ignoring-files/)
  131. file to make sure the minified files are not versioned, and an
  132. [empty `.npmignore`](https://docs.npmjs.com/misc/developers#keeping-files-out-of-your-package)
  133. to ensure that they are published to NPM.
  134. ## Module Loaders
  135. Module loaders such as [RequireJS](http://requirejs.org/) and [Browserify](http://browserify.org/) implement module systems like AMD (Asynchronous Module Definition) and CommonJS to allow developers to modularize and load their code.
  136. You can add support for AMD/CommonJS loaders to your Leaflet plugin by following this pattern based on the [Universal Module Definition](https://github.com/umdjs/umd/blob/master/templates/returnExportsGlobal.js)
  137. ```js
  138. (function (factory, window) {
  139. // define an AMD module that relies on 'leaflet'
  140. if (typeof define === 'function' && define.amd) {
  141. define(['leaflet'], factory);
  142. // define a Common JS module that relies on 'leaflet'
  143. } else if (typeof exports === 'object') {
  144. module.exports = factory(require('leaflet'));
  145. }
  146. // attach your plugin to the global 'L' variable
  147. if (typeof window !== 'undefined' && window.L) {
  148. window.L.YourPlugin = factory(L);
  149. }
  150. }(function (L) {
  151. var MyLeafletPlugin = {};
  152. // implement your plugin
  153. // return your plugin when you are done
  154. return MyLeafletPlugin;
  155. }, window));
  156. ```
  157. Now your plugin is available as an AMD and CommonJS module and can used used in module loaders like Browserify and RequireJS.
  158. ## Adding to the plugins list
  159. Once your plugin is published, it is a good idea to add it to the [Leaflet plugins list](http://leafletjs.com/plugins.html). To do so:
  160. * [Fork](https://help.github.com/articles/fork-a-repo/) the Leaflet repo.
  161. * In the `docs/plugins.md` file, find the section your plugin should go in, and add a table row with information and links about your plugin.
  162. * Commit the code to your fork.
  163. * [Open a pull request](https://help.github.com/articles/creating-a-pull-request/) from your fork to Leaflet's original repo.
  164. Once the pull request is done, a Leaflet maintainer will have a quick look at your
  165. plugin and, if everything looks right, your plugin will appear in the list shortly thereafter.