seperate NPM and module loader info. Condense module loader section
This commit is contained in:
Patrick Arlt
parent
cb551891bd
commit
1e3a535616
121
PLUGIN-GUIDE.md
121
PLUGIN-GUIDE.md
@ -15,13 +15,8 @@ This guide lists a number of best practices for publishing a Leaflet plugin that
|
||||
- [File Structure](#file-structure)
|
||||
- [Code Conventions](#code-conventions)
|
||||
- [Plugin API](#plugin-api)
|
||||
3. [Module Loaders](#module-loaders)
|
||||
- [Wrapping with UMD](#wrapping-with-umd)
|
||||
- [Using with RequireJS](#using-with-requirejs)
|
||||
- [Using with Browserify](#using-with-browserify)
|
||||
- [Best practices for RequireJS](#best-practices-for-requirejs)
|
||||
- [Best practices for Browserify](#best-practices-for-browserify)
|
||||
- [Module Loader Resources](#module-loader-resources)
|
||||
3. [Publishing on NPM](#publishing-on-npm)
|
||||
4. [Module Loaders](#module-loaders)
|
||||
|
||||
## Presentation
|
||||
|
||||
@ -133,15 +128,35 @@ marker.myPlugin('bla', {
|
||||
|
||||
And most importantly, keep it simple. Leaflet is all about *simplicity*.
|
||||
|
||||
## Publishing on NPM
|
||||
|
||||
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.
|
||||
|
||||
NPM has an excellent [developers guide](https://www.npmjs.org/doc/misc/npm-developers.html) to help you through the process.
|
||||
|
||||
When you publish your plugin you should add a depenency on `leaflet` to your `package.json` file. This will automatically install Leaflet when your package is installed.
|
||||
|
||||
Here is an example of a `package.json` file for a Leaflet plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-leaflet-plugin",
|
||||
"version": "1.0.0",
|
||||
"description": "A simple leaflet plugin.",
|
||||
"main": "my-plugin.js",
|
||||
"author": "You",
|
||||
"license": "IST",
|
||||
"dependencies": {
|
||||
"leaflet": "^1.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Module Loaders
|
||||
|
||||
Module loaders such as [RequireJS](http://requirejs.org/) and [Browserify](http://browserify.org/) impliment module systems like AMD (Asyncronous Module Definition) and CommonJS to allow developers to modularize and load their code.
|
||||
|
||||
Leaflet supports being loaded as either an AMD module or a CommonJS module. It does this by implimenting UMD (Universal Module Definition) which checks for the existance of an AMD/CommonJS and impliments the appropriate wrappers.
|
||||
|
||||
### Wrapping with UMD
|
||||
|
||||
You can add support for AMD/CommonJS loaders to your Leaflet plugin by follwoing this pattern.
|
||||
You can add support for AMD/CommonJS loaders to your Leaflet plugin by follwoing this pattern based on the [Universal Module Definition](https://github.com/umdjs/umd/blob/master/returnExportsGlobal.js)
|
||||
|
||||
```js
|
||||
(function (factory, window) {
|
||||
@ -159,88 +174,16 @@ You can add support for AMD/CommonJS loaders to your Leaflet plugin by follwoing
|
||||
}
|
||||
|
||||
// attach your plugin to the global 'L' variable
|
||||
window.L.YourPlugin = factory(L);
|
||||
|
||||
if(typeof window !== 'undefined' && window.L){
|
||||
window.L.YourPlugin = factory(L);
|
||||
}
|
||||
}(function (L) {
|
||||
// impliment your plguin
|
||||
var MyLeafletPlugin = {};
|
||||
|
||||
MyLeafeltPlugin.CustomLayer = L.Layer.extend({
|
||||
onAdd: function(map){
|
||||
|
||||
},
|
||||
onRemove: function(){
|
||||
|
||||
}
|
||||
});
|
||||
// impliment your plguin
|
||||
|
||||
// return your plugin when you are done
|
||||
return MyLeafletPlugin;
|
||||
}, window));
|
||||
```
|
||||
|
||||
### Using with RequireJS
|
||||
|
||||
Now users using RequireJS (which impliments the AMD module system) can use your plugin like this.
|
||||
|
||||
```js
|
||||
// define where the 'leaflet' and 'your-plugin' modules are located
|
||||
require.config({
|
||||
paths: {
|
||||
'leaflet': 'the/path/to/leaflet', //path to leaflet.js without the .js
|
||||
'your-plugin': 'the/path/to/your-plugin', //path to your-plguin.js without the .js
|
||||
}
|
||||
});
|
||||
|
||||
require([
|
||||
'leaflet',
|
||||
'your-plugin'
|
||||
], function(L, YourPlugin) {
|
||||
var map = new L.map('map').setView([45.5, -122.75], 9);
|
||||
var layer = new YourPlugin.CustomLayer().addTo(map);
|
||||
});
|
||||
```
|
||||
|
||||
### Using with Browserify
|
||||
|
||||
Users who are using Browserify (which impliments the CommonJS module system) can use your plugins following this example.
|
||||
|
||||
```js
|
||||
var L = require('leaflet');
|
||||
var YourPlugin = require('your-plugin');
|
||||
|
||||
var map = new L.map('map').setView([45.5, -122.75], 9);
|
||||
var layer = new YourPlugin.CustomLayer().addTo(map);
|
||||
```
|
||||
|
||||
### Best practices for RequireJS
|
||||
|
||||
Most AMD based module systesm (RequireJS, Dojo, ect...) have a mechanisum to name modules so they can be easily included with short strings rather then paths. In order to avoid confusion with many short names like `Leaflet` vs `leaflet` always use a lowercase `leaflet` for your module identifier.
|
||||
|
||||
### Best practices for Browserify
|
||||
|
||||
CommonJS module systems like Browserify rely on the [NPM (Node Package Modules)](https://www.npmjs.org/) registry to manage their dependencies. The means that when you `require('leaflet')` the proper module from the registry is returned to you.
|
||||
|
||||
This means that you must publish your plugin to the NPM repository. NPM has an excellent [developers guide](https://www.npmjs.org/doc/misc/npm-developers.html) to help you through the process.
|
||||
|
||||
When you publish your plugin you should add a depenency on `leaflet` to your `package.json` file. This will automatically install Leaflet when your package is installed.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-leaflet-plugin",
|
||||
"version": "1.0.0",
|
||||
"description": "A simple leaflet plugin.",
|
||||
"main": "my-plugin.js",
|
||||
"author": "You",
|
||||
"license": "IST",
|
||||
"dependencies": {
|
||||
"leaflet": "^1.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Resources
|
||||
|
||||
* [Get started with RequireJS](http://requirejs.org/docs/start.html#add)
|
||||
* [Get started Browserify](https://github.com/substack/browserify-handbook)
|
||||
* [Publishing on NPM](https://www.npmjs.org/doc/misc/npm-developers.html)
|
||||
Now your plugin is available as an AMD and CommonJS module and can used used in module loaders like Browserify and RequireJS.
|
||||
Loading…
Reference in New Issue
Block a user