VladPolskiy/leaflet
1
0
Fork 0
mirror of https://github.com/Leaflet/Leaflet.git synced 2025-07-23 00:34:55 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

add info about name, minor updates

Browse Source
This commit is contained in:
Vladimir Agafonkin
2013-06-28 17:21:40 -04:00
parent 46356e73a7
commit d04f1e73e3
1 changed files with 22 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
PLUGIN-GUIDE.md
View File

@ -7,6 +7,7 @@ This guide lists a number of best practices for publishing a Leaflet plugin that
1. [Presentation](#presentation) 1. [Presentation](#presentation)
- [Repository](#repository) - [Repository](#repository)
- [Name](#name)
- [Demo](#demo) - [Demo](#demo)
- [Readme](#readme) - [Readme](#readme)
- [License](#license) - [License](#license)
@ -24,6 +25,12 @@ If you create a collection of plugins for different uses,
don't put them in one repo — don't put them in one repo —
it's usually easier to work with small, self-contained plugins in individual repositories. 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 ### Demo
The most essential thing to do when publishing a plugin is to include a demo that showcases what the plugin does — The most essential thing to do when publishing a plugin is to include a demo that showcases what the plugin does —
@ -53,7 +60,7 @@ At a minimum it should contain the following items:
Every open source repository should include a license. Every open source repository should include a license.
If you don't know what open source license to choose for your code, If you don't know what open source license to choose for your code,
[MIT License](http://opensource.org/licenses/MIT) and [BSD 2-Clause License](http://opensource.org/licenses/BSD-2-Clause) are both good choices. [MIT License](http://opensource.org/licenses/MIT) and [BSD 2-Clause License](http://opensource.org/licenses/BSD-2-Clause) 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. You can either put it in the repo as a `LICENSE` file or just link to the license from the Readme.
## Code ## Code
@ -64,20 +71,21 @@ Keep the file structure clean and simple,
don't pile up lots of files in one place — don't pile up lots of files in one place —
make it easy for a new person to find their way in your repo. make it easy for a new person to find their way in your repo.
A barebones repo for a simple plugin would like this: A barebones repo for a simple plugin would look like this:
``` ```
my-plugin.js my-plugin.js
README.md README.md
``` ```
An example of a file structure for a more sophisticated plugin: An example of a more sophisticated plugin file structure:
``` ```
/src JS source files /src - JS source files
/dist minified plugin JS, CSS, images /dist - minified plugin JS, CSS, images
/spec test files /spec - test files
/examples HTML examples of plugin usage /lib - any external libraries/plugins if necessary
/examples - HTML examples of plugin usage
README.md README.md
LICENSE LICENSE
package.json package.json
@ -94,15 +102,16 @@ and putting a space after the `function` keyword.
### Plugin API ### Plugin API
Never expose global variables in your plugin. Never expose global variables in your plugin.<br>
If you have a new class, put it directly in the `L` namespace (`L.MyPlugin`). If you have a new class, put it directly in the `L` namespace (`L.MyPlugin`).<br>
If you inherit one of the existing classes, make it a sub-property (`L.TileLayer.Banana`). If you inherit one of the existing classes, make it a sub-property (`L.TileLayer.Banana`).<br>
If you want to add new methods to existing Leaflet classes, you can do it like this: `L.Marker.include({myPlugin: …})`. 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`. Function, method and property names should be in `camelCase`.<br>
Class names should be in `CapitalizedCamelCase`. 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): 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):
```js ```js
// bad // bad
@ -110,7 +119,7 @@ marker.myPlugin('bla', 'foo', null, {}, 5, 0);
// good // good
marker.myPlugin('bla', { marker.myPlugin('bla', {
optionOne: 'foo', optionOne: 'foo',
optionThree: 5 optionThree: 5
}); });
``` ```