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`).
+Every class should have a factory function in camelCase, e.g. (`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`.
+Function, method, property and factory 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): +(putting default values where possible so that users don't need to specify all of them): ```js // bad @@ -125,3 +129,94 @@ 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 dependency 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" + } +} +``` + +If possible, do not commit your minified files (e.g. `dist`) to a repo; this can +lead to confussion when trying to debug the wrong file. Instead, use `npm` to +trigger a build/minification just before publishing your package with a +[`prepublish` script](https://docs.npmjs.com/misc/scripts#common-uses), for example: + +```json +{ + "name": "my-leaflet-plugin", + ... + "scripts": { + "prepublish": "grunt build" + } +} +``` + +You can then use the [`.gitignore`](https://help.github.com/articles/ignoring-files/) +file to make sure the minified files are not versioned, and an +[empty `.npmignore`](https://docs.npmjs.com/misc/developers#keeping-files-out-of-your-package) +to ensure that they are published to NPM. + +## Module Loaders + +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. + +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/returnExportsGlobal.js) + +```js +(function (factory, window) { + + // define an AMD module that relies on 'leaflet' + if (typeof define === 'function' && define.amd) { + define(['leaflet'], factory); + + // define a Common JS module that relies on 'leaflet' + } else if (typeof exports === 'object') { + module.exports = factory(require('leaflet')); + } + + // attach your plugin to the global 'L' variable + if (typeof window !== 'undefined' && window.L) { + window.L.YourPlugin = factory(L); + } +}(function (L) { + var MyLeafletPlugin = {}; + // implement your plugin + + // return your plugin when you are done + return MyLeafletPlugin; +}, window)); +``` + +Now your plugin is available as an AMD and CommonJS module and can used used in module loaders like Browserify and RequireJS. + + +## Adding to the plugins list + +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: + +* [Fork](https://help.github.com/articles/fork-a-repo/) the Leaflet repo. +* Clone your repo locally, and switch to the [`gh-pages` branch](https://github.com/Leaflet/Leaflet/tree/gh-pages). +* In the `plugins.md` file, find the section your plugin should go in, and add a table row with information and links about your plugin. +* Commit the code to your fork. +* [Open a pull request](https://help.github.com/articles/creating-a-pull-request/) from your `gh-pages` branch to Leaflet's `gh-pages` branch. + +Once the pull request is done, a Leaflet maintainer will have a quick look at your +plugin and, if everything looks right, your plugin will appear in the list shortly thereafter. diff --git a/README.md b/README.md index 220b74ecc15..0d6eb8c5535 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,7 @@
-Leaflet is an open source JavaScript library for **mobile-friendly interactive maps**.
-It is developed by [Vladimir Agafonkin][] of [MapBox][] with a team of dedicated [contributors][].
-Weighing just about 30 KB of gzipped JS code, it has all the [features][] most developers ever need for online maps.
+Leaflet is the leading open-source JavaScript library for **mobile-friendly interactive maps**.
+Weighing just about 33 KB of gzipped JS code, it has all the mapping [features][] most developers ever need.
Leaflet is designed with *simplicity*, *performance* and *usability* in mind.
It works efficiently across all major desktop and mobile platforms out of the box,
@@ -19,11 +18,10 @@ If you want to **get involved** with Leaflet development, check out the [contrib
Let's make the best mapping library that will ever exist,
and push the limits of what's possible with online maps!
-[](https://travis-ci.org/Leaflet/Leaflet)
+[](https://travis-ci.org/Leaflet/Leaflet)
- [Vladimir Agafonkin]: http://agafonkin.com/en
[contributors]: https://github.com/Leaflet/Leaflet/graphs/contributors
- [features]: http://leafletjs.com/features.html
+ [features]: http://leafletjs.com/#features
[plugins]: http://leafletjs.com/plugins.html
[well-documented]: http://leafletjs.com/reference.html "Leaflet API reference"
[source code]: https://github.com/Leaflet/Leaflet "Leaflet GitHub repository"
@@ -31,4 +29,4 @@ and push the limits of what's possible with online maps!
[contribute]: https://github.com/Leaflet/Leaflet/blob/master/CONTRIBUTING.md "A guide to contributing to Leaflet"
[official website]: http://leafletjs.com
[download page]: http://leafletjs.com/download.html
- [MapBox]: https://mapbox.com
+
diff --git a/_config.yml b/_config.yml
new file mode 100644
index 00000000000..1d6eae1fedb
--- /dev/null
+++ b/_config.yml
@@ -0,0 +1,6 @@
+source: docs
+
+markdown: kramdown
+
+kramdown:
+ entity_output: as_input
diff --git a/_includes/frame.html b/_includes/frame.html
new file mode 100644
index 00000000000..c3e595c0cd0
--- /dev/null
+++ b/_includes/frame.html
@@ -0,0 +1,9 @@
+| + + |
| +See this example stand-alone. + |
-
-
-
-
-
diff --git a/build/build.js b/build/build.js
index c2da58a3d7d..e9b286a29e7 100644
--- a/build/build.js
+++ b/build/build.js
@@ -145,10 +145,22 @@ exports.build = function (callback, compsBase32, buildName) {
exports.test = function(callback) {
var karma = require('karma'),
- testConfig = {configFile : __dirname + '/../spec/karma.conf.js'};
+ testConfig = {configFile : __dirname + '/../spec/karma.conf.js'},
+ autoSlimer = false;
testConfig.browsers = ['PhantomJS'];
+ try {
+ var child = require('child_process').execFileSync(
+ require('slimerjs').path
+ );
+ console.log('Running tests with both PhantomJS and SlimerJS');
+ testConfig.browsers.push('SlimerJS');
+ autoSlimer = true;
+ } catch(e) {
+ console.log('Cannot start SlimerJS, will run tests only in PhantomJS');
+ }
+
function isArgv(optName) {
return process.argv.indexOf(optName) !== -1;
}
@@ -180,6 +192,19 @@ exports.test = function(callback) {
console.log('Running tests...');
var server = new karma.Server(testConfig, function(exitCode) {
+
+ // Work around https://github.com/karma-runner/karma-slimerjs-launcher/issues/1
+ if (autoSlimer && require('os').platform() !== 'win32' ) { // Kill process only in linux/osx, as win32 seems to work fine
+ var slimerjsPids = require('child_process').execSync('ps -Af | grep slimerjs | grep xulrunner | awk \'{print $2}\'').toString();
+ slimerjsPids = slimerjsPids.trim().split('\n');
+ for (var i=0; iLeaflet Build Helper
- -- Select All | - Deselect All -
- -Building using Node and UglifyJS
--
-
- Download and install Node -
- Run this in the command line:
-npm install -g jake -npm install
- - Run this command inside the Leaflet directory:
-
| CRS | +Description | +
|---|---|
{{name}} |
+ {{{markdown comments}}} | +
| Event | +Data | +Description | +
|---|---|---|
{{name}}
+ |
| Factory | +Description | +
|---|---|
{{name}}(
+ {{~#each params~}}
+ {{#if type}} |
+ {{{markdown comments}}} | +
| Function | +Returns | +Description | +
|---|---|---|
{{name}}(
+ {{~#each params~}}
+ {{#if type}} |
+ {{{type type}}} |
+ {{{markdown comments}}} | +
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/build/leafdoc-templates/inherited.hbs b/build/leafdoc-templates/inherited.hbs
new file mode 100644
index 00000000000..405988829c1
--- /dev/null
+++ b/build/leafdoc-templates/inherited.hbs
@@ -0,0 +1,7 @@
+
+Leaflet API reference
+
+
+
+ {{{ body }}}
+
+
+
+
+
+
+
+
+ Map
+-
+
- Usage example +
- Creation +
- Options +
- Events +
Map Methods
+-
+
- Modifying map state +
- Getting map state +
- Layers and controls +
- Conversion methods +
- Other methods +
Map Misc
+-
+
- Properties +
- Panes +
+
+ Other Layers
+-
+
- LayerGroup +
- FeatureGroup +
- GeoJSON +
- GridLayer +
Basic Types
+ +Controls
+-
+
- Zoom +
- Attribution +
- Layers +
- Scale +
+
+
+
+
+
+
+
+
+ Utility
+-
+
- Browser +
- Util +
- Transformation +
- LineUtil +
- PolyUtil +
DOM Utility
+-
+
- DomEvent +
- DomUtil +
- PosAnimation +
- Draggable +
+
+
diff --git a/build/leafdoc-templates/method.hbs b/build/leafdoc-templates/method.hbs
new file mode 100644
index 00000000000..865af019658
--- /dev/null
+++ b/build/leafdoc-templates/method.hbs
@@ -0,0 +1,19 @@
+
+
+{{{inherited}}}
+ | Method | +Returns | +Description | +
|---|---|---|
{{name}}(
+ {{~#each params~}}
+ {{#if type}} |
+ {{{type type}}} |
+ {{{rawmarkdown comments}}} | +
{{name}}
+{{~ else ~}} + +{{/if}} +{{{rawmarkdown comments}}} +{{{supersections}}} \ No newline at end of file diff --git a/build/leafdoc-templates/option.hbs b/build/leafdoc-templates/option.hbs new file mode 100644 index 00000000000..61d406591e2 --- /dev/null +++ b/build/leafdoc-templates/option.hbs @@ -0,0 +1,17 @@ +| Option | +Type | +Default | +Description | +
|---|---|---|---|
{{name}} |
+ {{{type type}}}
+ | {{defaultValue}} |
+ {{{markdown comments}}} | +
| Pane | +Type | +Z-index | +Description | +
|---|---|---|---|
{{name}} |
+ {{{type type}}}
+ | {{defaultValue}} |
+ {{{markdown comments}}} | +
| Projection | +Description | +
|---|---|
{{name}} |
+ {{{markdown comments}}} | +
| Property | +Type | +Description | +
|---|---|---|
{{name}}
+ |
{{name}}
{{/if}} + +{{#if comments~}} +{{{markdown comments}}}
+{{/if}}
+
+{{{documentables}}}
+
+