leaflet-js 0.7.9 → 0.8.dev2

data/lib/leaflet/CONTRIBUTING.md

@@ -0,0 +1,155 @@
+Contributing to Leaflet
+=======================
+
+ 1. [Getting Involved](#getting-involved)
+ 2. [Reporting Bugs](#reporting-bugs)
+ 3. [Contributing Code](#contributing-code)
+ 4. [Improving Documentation](#improving-documentation)
+
+## Getting Involved
+
+Third-party patches are absolutely essential on our quest to create the best mapping library that will ever exist.
+However, they're not the only way to get involved with the development of Leaflet.
+You can help the project tremendously by discovering and [reporting bugs](#reporting-bugs),
+[improving documentation](#improving-documentation),
+helping others on the [Leaflet forum](https://groups.google.com/forum/#!forum/leaflet-js)
+and [GitHub issues](https://github.com/Leaflet/Leaflet/issues),
+showing your support for your favorite feature suggestions on [Leaflet UserVoice page](http://leaflet.uservoice.com),
+tweeting to [@LeafletJS](http://twitter.com/LeafletJS)
+and spreading the word about Leaflet among your colleagues and friends.
+
+## Reporting Bugs
+
+Before reporting a bug on the project's [issues page](https://github.com/Leaflet/Leaflet/issues),
+first make sure that your issue is caused by Leaflet, not your application code
+(e.g. passing incorrect arguments to methods, etc.).
+Second, search the already reported issues for similar cases,
+and if it's already reported, just add any additional details in the comments.
+
+After you made sure that you've found a new Leaflet bug,
+here are some tips for creating a helpful report that will make fixing it much easier and quicker:
+
+ * Write a **descriptive, specific title**. Bad: *Problem with polylines*. Good: *Doing X in IE9 causes Z*.
+ * Include **browser, OS and Leaflet version** info in the description.
+ * Create a **simple test case** that demonstrates the bug (e.g. using [JSFiddle](http://jsfiddle.net/)).
+ * Check whether the bug can be reproduced in **other browsers**.
+ * Check if the bug occurs in the stable version, master, or both.
+ * *Bonus tip:* if the bug only appears in the master version but the stable version is fine,
+   use `git bisect` to find the exact commit that introduced the bug.
+
+If you just want some help with your project,
+try asking [on the Leaflet forum](https://groups.google.com/forum/#!forum/leaflet-js) instead.
+
+## Contributing Code
+
+### Considerations for Accepting Patches
+
+While we happily accept patches, we're also commited to keeping Leaflet simple, lightweight and blazingly fast.
+So bugfixes, performance optimizations and small improvements that don't add a lot of code
+are much more likely to get accepted quickly.
+
+Before sending a pull request with a new feature, first check if it's been discussed before already
+(either on [GitHub issues](https://github.com/Leaflet/Leaflet/issues)
+or [Leaflet UserVoice](http://leaflet.uservoice.com/)),
+and then ask yourself two questions:
+
+ 1. Are you sure that this new feature is important enough to justify its presense in the Leaflet core?
+    Or will it look better as a plugin in a separate repository?
+ 2. Is it written in a simple, concise way that doesn't add bulk to the codebase?
+
+If your feature or API improvement did get merged into master,
+please consider submitting another pull request with the corresponding [documentation update](#improving-documentation).
+
+### Setting up the Build System
+
+To set up the Leaflet build system, install [Node](http://nodejs.org/),
+then run the following commands in the project root:
+
+```
+npm install -g jake
+npm install
+```
+
+You can build minified Leaflet by running `jake` (it will be built from source in the `dist` folder).
+For a custom build with selected components, open `build/build.html` in the browser and follow the instructions from there.
+
+### Making Changes to Leaflet Source
+
+If you're not yet familiar with the way GitHub works (forking, pull requests, etc.),
+be sure to check out the awesome [article about forking](https://help.github.com/articles/fork-a-repo)
+on the GitHub Help website — it will get you started quickly.
+
+You should always write each batch of changes (feature, bugfix, etc.) in **its own topic branch**.
+Please do not commit to the `master` branch, or your unrelated changes will go into the same pull request.
+
+You should also follow the code style and whitespace conventions of the original codebase.
+In particular, use tabs for indentation and spaces for alignment.
+
+Before commiting your changes, run `jake lint` to catch any JS errors in the code and fix them.
+If you add any new files to the Leaflet source, make sure to also add them to `build/deps.js`
+so that the build system knows about them.
+
+Also, please make sure that you have [line endings configured properly](https://help.github.com/articles/dealing-with-line-endings) in Git! Otherwise the diff will show that all lines of a file were changed even if you touched only one.
+
+Happy coding!
+
+## Running the Tests
+
+To run the tests from the command line,
+install [PhantomJS](http://phantomjs.org/) (and make sure it's in your `PATH`),
+then run:
+
+```
+jake test
+```
+
+To run all the tests in actual browsers at the same time, you can do:
+
+```
+jake test --ff --chrome --safari --ie
+```
+
+To run the tests in a browser manually, open `spec/index.html`.
+
+## Code Coverage
+
+To generate a detailed report about test coverage (which helps tremendously when working on test improvements), run:
+
+```
+jake test --cov
+```
+
+After that, open `spec/coverage/<environment>/index.html` in a browser to see the report.
+From there you can click through folders/files to get details on their individual coverage.
+
+## Improving Documentation
+
+The code of the live Leaflet website that contains all documentation and examples is located in the `gh-pages` branch
+and is automatically generated from a set of HTML and Markdown files by [Jekyll](https://github.com/mojombo/jekyll).
+
+The easiest way to make little improvements such as fixing typos without even leaving the browser
+is by editing one of the files with the online GitHub editor:
+browse the [gh-pages branch](https://github.com/Leaflet/Leaflet/tree/gh-pages),
+choose a certain file for editing (e.g. `reference.html` for API reference),
+click the Edit button, make changes and follow instructions from there.
+Once it gets merged, the changes will immediately appear on the website.
+
+If you need to make edits in a local repository to see how it looks in the process, do the following:
+
+ 1. [Install Ruby](http://www.ruby-lang.org/en/) if don't have it yet.
+ 2. Run `gem install jekyll`.
+ 3. Run `jekyll serve --watch` in the root `Leaflet` folder.
+ 4. Open `localhost:4000` in your browser.
+
+Now any file changes will be updated when you reload pages automatically.
+After commiting the changes, just send a pull request.
+
+If you need to update documentation according to a new feature that only appeared in the master version (not stable one),
+you need to make changes to `gh-pages-master` branch instead of `gh-pages`.
+It will get merged into the latter when released as stable.
+
+## Thank You
+
+Not only are we grateful for any contributions, &mdash; helping Leaflet and its community actually makes you AWESOME.
+Join [this approved list of awesome people](https://github.com/Leaflet/Leaflet/graphs/contributors)
+and help us push the limits of what's possible with online maps!

data/lib/leaflet/FAQ.md

@@ -0,0 +1,138 @@
+# Leaflet FAQ
+
+This is a collection of answers to the most frequently asked questions about Leaflet.
+
+ 1. [Data Providers](#data-providers)
+ 2. [Commercial Use and Licensing](#commercial-use-and-licensing)
+ 3. [Features](#features)
+ 4. [Performance](#performance)
+ 5. [Misc](#misc)
+
+## Data Providers
+
+#### The map is wrong in my neighborhood, could you fix it?
+
+Nope, but you can.
+The map you see on Leaflet examples is based on [OpenStreetMap](http://openstreetmap.org),
+a free editable map of the world.
+Signing up and editing the map there is easy,
+and the changes will be reflected on the map in a few minutes.
+
+#### What map tiles can I use with Leaflet? Is it limited to OpenStreetMap?
+
+Leaflet is provider-agnostic, meaning you can use any map provider as long as you conform to its terms of use.
+You can roll your own tiles as well.
+[OpenStreetMap](http://openstreetmap.org) is the most popular data source among different tile providers,
+but there are providers that use other sources.
+
+Check out [this example](http://leaflet-extras.github.io/leaflet-providers/preview/)
+with half a hundred different layers to choose from.
+Popular commercial options, free up to a particular number of requests, include
+[MapBox](http://mapbox.com),
+[CloudMade](http://cloudmade.com),
+[Bing Maps](http://www.microsoft.com/maps/choose-your-binge's-maps-API.aspx) (using a [plugin](https://github.com/shramov/leaflet-plugins)),
+[Esri ArcGIS](http://www.arcgis.com/features/maps/imagery.html) ([official plugin](https://github.com/Esri/esri-leaflet))
+and [Nokia Here](http://developer.here.com/web-experiences).
+A notable exception is [MapQuest Open](http://developer.mapquest.com/web/products/open/map), which is free for any number of requests.
+
+Always be sure to **read the terms of use** of a chosen tile provider, **know its limitations**, and **attribute it properly** in your app.
+
+#### I'm looking for satellite imagery to use with my Leaflet map, any options?
+
+[MapBox](http://mapbox.com),
+[Bing Maps](http://www.microsoft.com/maps/choose-your-bing-maps-API.aspx),
+[ArcGIS](http://www.arcgis.com/features/maps/imagery.html)
+and [MapQuest Open](http://developer.mapquest.com/web/products/open/map) provide satellite imagery among others.
+
+#### I want to use Google Maps API tiles with Leaflet, can I do that?
+
+The problem with Google is that its [Terms of Use](https://developers.google.com/maps/terms?hl=ru) forbid any means of tile access other than through the Google Maps API.
+
+You can add the Google Maps API as a Leaflet layer with a [plugin](https://github.com/shramov/leaflet-plugins). But note that the map experience will not be perfect, because Leaflet will just act as a proxy to the Google Maps JS engine, so you won't get all the performance and usability benefits of using Leaflet when the Google layer is on.
+
+#### I want to roll my own OSM tile server for Leaflet, where do I start?
+
+Check out [this excellent guide](http://switch2osm.org/serving-tiles/).
+
+#### I want to create tiles from my own data for use with Leaflet, what are the options?
+
+There's a number of services that allow you to do this easily,
+notably [MapBox](https://www.mapbox.com/), [CartoDB](http://cartodb.com/) and [GIS Cloud](http://www.giscloud.com/).
+If you want to make tiles on your own, probably the easiest way is using [TileMill](https://www.mapbox.com/tilemill/).
+TileMill can export your map as a single [.mbtiles](https://www.mapbox.com/developers/mbtiles/) file, which can be copied to a webserver and accessed by Leaflet with [a small PHP script](https://github.com/infostreams/mbtiles-php).
+Alternatively, you can [extract](https://github.com/mapbox/mbutil) the tiled images from the .mbtiles database and place them directly on your webserver with absolutely no server-side dependencies.
+
+## Commercial Use and Licensing
+
+#### I have an app that gets lots of hits a day, and I want to switch from Google/Bing/whatever to Leaflet. Is there a fee for using it?
+
+Leaflet, unlike Google Maps and other all-in-one solutions, is just a JavaScript library.
+It's free to use, but doesn't provide map imagery on its own —
+you have to choose a tile service to combine with it.
+
+There are [plenty of options](#what-map-tiles-can-i-use-with-leaflet-is-it-limited-to-openstreetmap) for a tile service,
+each with their own terms of use, prices (some of them free), features, limitations, etc.
+Choice is yours.
+
+#### I'm building a commercial app that I plan to sell. Can I use Leaflet in it?
+
+You're welcome, as the code is published under the very permissive [2-clause BSD License](https://github.com/Leaflet/Leaflet/blob/master/LICENSE).
+Just make sure to attribute the use of the library somewhere in the app UI or the distribution
+(e.g. keep the Leaflet link on the map, or mention the use on the About page or a Readme file, etc.) and you'll be fine.
+
+That only applies to the code though.
+Make sure you conform to the terms of use of the tile images provider(s) that you choose as well.
+
+
+## Features
+
+#### Why is there still no feature X in Leaflet?
+
+First of all, did you check out the [Leaflet plugins page](http://leafletjs.com/plugins.html)?
+It lists about a hundred plugins doing all kinds of crazy stuff,
+and there's a high possibility that it has what you're looking for.
+
+Generally, we do our best to keep the Leaflet core small, lightweight and simple,
+focusing on _quality_ instead of _quantity_, and leaving all the rest to plugin authors.
+
+Check out [this video](http://www.youtube.com/watch?v=_P2SaCPbJ4w) of a talk by the Leaflet creator for more background on the story and philosophy behind Leaflet.
+Another essential read is [Advocating Simplicity in Open Source](http://blog.universalmind.com/advocating-simplicity-in-open-source/) by the same guy.
+
+
+## Performance
+
+#### I have thousands of markers on my map. How do I make it faster and more usable?
+
+Check out the [Leaflet.markercluster](https://github.com/Leaflet/Leaflet.markercluster) plugin. It's amazing.
+
+#### I have vector data with many thousands of points on my map. Any performance tips?
+
+Leaflet generally does a pretty good job of handling heavy vector data
+with its real-time clipping and simplification algorithms,
+but browser technology still has its limits.
+Try [switching from SVG to Canvas as the default rendering back-end](http://leafletjs.com/reference.html#global),
+it may help considerably (depends on the app and the data).
+
+If you still have too much data to render, you'll have to use some help of a server-side service
+like [MapBox](https://www.mapbox.com/),
+[CartoDB](http://cartodb.com/)
+and [GIS Cloud](http://www.giscloud.com/)
+(they all work great with Leaflet).
+What they do under the hood is serving rendered data as image tiles,
+along with additional data to enable interactivity like hovering shapes
+(e.g. done using [UTFGrid](https://www.mapbox.com/developers/utfgrid/) —
+Leaflet [has a nice plugin](https://github.com/danzel/Leaflet.utfgrid) for it).
+
+
+## Misc
+
+#### I downloaded the Leaflet source but didn't find `leaflet.js` there. Why is that?
+
+You can download the built versions using links from the [download page](http://leafletjs.com/download.html).
+It even includes the latest build of the development version (`master` branch),
+updated automatically on each commit to the repo.
+
+We removed the built versions from the repository because it's a chore to build and commit them manually on each change,
+and it often complicates merging branches and managing contributions.
+
+There's a common complaint that Leaflet can't be used with [Bower](http://bower.io/) because of that, but we'll resolve the issue soon.

data/lib/leaflet/Jakefile.js

@@ -0,0 +1,56 @@
+/*
+Leaflet building, testing and linting scripts.
+
+To use, install Node, then run the following commands in the project root:
+
+    npm install -g jake
+    npm install
+
+To check the code for errors and build Leaflet from source, run "jake".
+To run the tests, run "jake test".
+
+For a custom build, open build/build.html in the browser and follow the instructions.
+*/
+
+var build = require('./build/build.js'),
+    version = require('./src/Leaflet.js').version;
+
+function hint(msg, paths) {
+	return function () {
+		console.log(msg);
+		jake.exec('node node_modules/jshint/bin/jshint -c ' + paths,
+				{printStdout: true}, function () {
+			console.log('\tCheck passed.\n');
+			complete();
+		});
+	}
+}
+
+desc('Check Leaflet source for errors with JSHint');
+task('lint', {async: true}, hint('Checking for JS errors...', 'build/hintrc.js src'));
+
+desc('Check Leaflet specs source for errors with JSHint');
+task('lintspec', {async: true}, hint('Checking for specs JS errors...', 'spec/spec.hintrc.js spec/suites'));
+
+desc('Combine and compress Leaflet source files');
+task('build', {async: true}, function (compsBase32, buildName) {
+	var v;
+
+	jake.exec('git log -1 --pretty=format:"%h"', {}, function () {
+		build.build(complete, v, compsBase32, buildName);
+
+	}).on('stdout', function (data) {
+		v = version + ' (' + data.toString() + ')';
+	})
+});
+
+desc('Run PhantomJS tests');
+task('test', ['lint', 'lintspec'], {async: true}, function () {
+	build.test(complete);
+});
+
+task('default', ['test', 'build']);
+
+jake.addListener('complete', function () {
+  process.exit();
+});

data/lib/leaflet/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2010-2014, Vladimir Agafonkin
+Copyright (c) 2010-2011, CloudMade
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice, this list of
+      conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright notice, this list
+      of conditions and the following disclaimer in the documentation and/or other materials
+      provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/lib/leaflet/PLUGIN-GUIDE.md

@@ -0,0 +1,127 @@
+# Leaflet Plugin Authoring Guide
+
+One of the greatest things about Leaflet is its powerful plugin ecosystem.
+The [Leaflet plugins page](http://leafletjs.com/plugins.html) 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](#presentation)
+	- [Repository](#repository)
+	- [Name](#name)
+	- [Demo](#demo)
+	- [Readme](#readme)
+	- [License](#license)
+2. [Code](#code)
+	- [File Structure](#file-structure)
+	- [Code Conventions](#code-conventions)
+	- [Plugin API](#plugin-api)
+
+## Presentation
+
+### Repository
+
+The best place to put your Leaflet plugin to is a separate [GitHub](http://github.com) 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](http://pages.github.com/).
+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  —
+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](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.
+
+## Code
+
+### File Structure
+
+Keep the file structure clean and simple,
+don't pile up lots of files in one place  &mdash;
+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](https://github.com/airbnb/javascript).
+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.<br>
+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`).<br>
+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`.<br>
+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):
+
+```js
+// 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*.