From 1fb1aa4f2a227b1c9b2115e406e466f85c1941dd Mon Sep 17 00:00:00 2001 From: ghybs Date: Sat, 16 Sep 2017 16:00:59 +0400 Subject: [PATCH] Chore(README): use build script for README using a README template (in `build/readme.template.md`), so that new tag versions are automatically reflected in documentation. Close #8 --- Jakefile.js | 7 ++ README.md | 22 ++++++ build/build.js | 36 +++++++++ build/readme.template.md | 158 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 223 insertions(+) create mode 100644 build/readme.template.md diff --git a/Jakefile.js b/Jakefile.js index 28088f0..32cf096 100644 --- a/Jakefile.js +++ b/Jakefile.js @@ -35,4 +35,11 @@ task('build', {async: true}, function (compsBase32, buildName, officialRelease) }); }); +desc('Generate docs'); +task('buildDocs', {async: true}, function () { + var packageJsonData = require('./package.json'); + + build.buildDocs(complete, packageJsonData); +}); + task("default", ["build"]); diff --git a/README.md b/README.md index 93d341d..6729d61 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,10 @@ + + # Leaflet.MarkerCluster.Freezable Sub-plugin for [Leaflet.markercluster](https://github.com/Leaflet/Leaflet.markercluster) plugin (MCG in short); adds the ability to freeze clusters at a specified zoom. @@ -86,6 +93,21 @@ You can alternatively use the free [unpkg](https://unpkg.com) CDN service, but k ``` +#### npm +1. Add this package to your project: + ```bash + $ npm install leaflet.markercluster.freezable --save + ``` + +2. If you are using a bundling tool, import in your JavaScript. +It only performs the side effect of adding new methods to `L.markerClusterGroup`, +so you do not need to store it into a local variable or import a namespace. + ```javascript + require('leaflet.markercluster.freezable'); + // Or with ES6: + import 'leaflet.markercluster.freezable'; + ``` + ### Creation diff --git a/build/build.js b/build/build.js index 3f0fa84..ed816be 100644 --- a/build/build.js +++ b/build/build.js @@ -147,3 +147,39 @@ exports.build = function (callback, metaData, compsBase32, buildName) { } }); }; + + +////////////////////////////////////// +// Docs +////////////////////////////////////// + +function _fillFileTemplate(content, dataMap) { + for (var key in dataMap) { + //content = content.replace(key, dataMap[key]); + content = _replaceAll(content, key, dataMap[key]); + } + + return content; +} + +function _replaceAll(target, search, replacement) { + return target.split(search).join(replacement); +} + +exports.buildDocs = function (callback, metaData) { + + console.log('Generating docs...'); + + var readmeContent = _fillFileTemplate(fs.readFileSync('build/readme.template.md', 'utf8'), { + '{{TAG_NAME}}': 'v' + metaData.version, + '{{VERSION}}': metaData.version + }), + readmeFilepath = 'README.md'; + + console.log('Writing README'); + fs.writeFileSync(readmeFilepath, readmeContent); + + console.log('Done'); + + callback(); +}; diff --git a/build/readme.template.md b/build/readme.template.md new file mode 100644 index 0000000..c84d49b --- /dev/null +++ b/build/readme.template.md @@ -0,0 +1,158 @@ + + +# Leaflet.MarkerCluster.Freezable +Sub-plugin for [Leaflet.markercluster](https://github.com/Leaflet/Leaflet.markercluster) +plugin (MCG in short); adds the ability to freeze clusters at a specified zoom. + +[Leaflet.markercluster](https://github.com/Leaflet/Leaflet.markercluster) plugin +provides beautiful animated Marker Clustering functionality. + +[Leaflet](http://leafletjs.com/) is the leading open-source JavaScript library +for mobile-friendly interactive maps. + +[![GitHub releases](https://img.shields.io/github/release/ghybs/leaflet.markercluster.freezable.svg?label=GitHub)](https://github.com/ghybs/Leaflet.MarkerCluster.Freezable/releases) +[![npm](https://img.shields.io/npm/v/leaflet.markercluster.freezable.svg)](https://www.npmjs.com/package/leaflet.markercluster.freezable) + + + +## Requirements +This plugin should be compatible with both combinations: +- Leaflet 1.0.x + Leaflet.markercluster 1.0.0 +- Leaflet legacy (0.7.x) + Leaflet.markercluster legacy (0.5.x) + + + +## Demos +- [Leaflet.MarkerCluster.Freezable (Leaflet 1.0.1 + Leaflet.markercluster 1.0.0)](http://ghybs.github.io/Leaflet.MarkerCluster.Freezable/examples/mcg-freezable-leaflet1.0.0.html) +- [Leaflet.MarkerCluster.Freezable (Leaflet 0.7.7 + Leaflet.markercluster 0.5.0)](http://ghybs.github.io/Leaflet.MarkerCluster.Freezable/examples/mcg-freezable.html) + + +## Usage instructions + +### Quick Guide +**HTML:** +```html + + +``` + +**JavaScript:** +```javascript +var map = L.map("map"), + mcg = L.markerClusterGroup(options); + +mcg.addLayers(arrayOfMarkers); +mcg.addTo(map); + +mcg.freezeAtZoom(15); +mcg.freezeAtZoom("maxKeepSpiderfy"); +mcg.freezeAtZoom("max"); +mcg.unfreeze(); // shortcut for mcg.freezeAtZoom(false) + +mcg.disableClusteringKeepSpiderfy(); // shortcut for mcg.freezeAtZoom("maxKeepSpiderfy") +mcg.disableClustering(); // shortcut for mcg.freezeAtZoom("max") +mcg.enableClustering(); // alias for mcg.unfreeze() +``` + +When frozen / disabled, clusters will no longer split / merge on map zoom, but +retain their status as if they were on the specified zoom level. They will +directly spiderfy when clicked on, instead of zooming to bounds (since zooming +will not make them split apart). + +In particular, freezing at `maxZoom + 1` removes all clusters. + +Freezing at `maxZoom` removes all clusters except the bottom-most ones, so that +user can still spiderfy closely positioned markers. + +**CAUTION: make sure your operations makes sense before freezing to high zoom +whereas the map is at a low zoom. It may have to load _thousands_ of markers +suddenly!** + +_Note: while frozen, MCG will continue removing clusters and markers which are +far from the view port, accordingly with `removeOutsideVisibleBounds` option._ + + + +### Installing the sub-plugin + +#### Local copy +1. Download the "`leaflet.markercluster.freezable.js`" file from the [`{{TAG_NAME}}` release](https://github.com/ghybs/Leaflet.MarkerCluster.Freezable/releases/tag/{{TAG_NAME}}). +2. Place the file alongside your page. +3. Add the `script` tag (see [Quick Guide > HTML](#quick-guide)) to your page after Leaflet and Leaflet.markercluster scripts. + +#### CDN +You can alternatively use the free [unpkg](https://unpkg.com) CDN service, but keep in mind that it "[_is a free, best-effort service and cannot provide any uptime or support guarantees_](https://unpkg.com/#/about)". + +```html + + +``` + +#### npm +1. Add this package to your project: + ```bash + $ npm install leaflet.markercluster.freezable --save + ``` + +2. If you are using a bundling tool, import in your JavaScript. +It only performs the side effect of adding new methods to `L.markerClusterGroup`, +so you do not need to store it into a local variable or import a namespace. + ```javascript + require('leaflet.markercluster.freezable'); + // Or with ES6: + import 'leaflet.markercluster.freezable'; + ``` + + + +### Creation +Simply use the the regular `L.markerClusterGroup` factory, as Freezable plugin +directly adds new methods to Leaflet.markercluster: + +```javascript +var mcg = L.markerClusterGroup(options); + +mcg.addTo(map); +``` + + + +## API Reference + +### Methods +| Method | Returns | Description | +| :------ | :------- | :---------- | +| **freezeAtZoom**( `` or `` or `` frozenZoom? ) | `this` | Freezes clusters at specified zoom, current zoom, or unfreeze. If passed a positive number (including 0), freezes at that zoom. If passed `"max"` (string), freezes at `maxZoom + 1`. If passed `"maxKeepSpiderfy"` (string), freezes at `maxZoom`. If passed nothing, `undefined`, `true` (boolean) or `NaN`, freezes at current zoom. If passed `false` (boolean) or any other non-number, unfreezes. | +| **unfreeze**() | `this` | Shortcut for `freezeAtZoom(false)`. | +| **disableClustering**() | `this` | Shortcut for `freezeAtZoom("max")`. | +| **disableClusteringKeepSpiderfy**() | `this` | Shortcut for `freezeAtZoom("maxKeepSpiderfy")`. | +| **enableClustering**() | `this` | Shortcut for `unfreeze()`. | + +MCG.Freezable does not provide any extra option or event. + + +### Regular MCG options, events and methods +All regular MCG [options](https://github.com/Leaflet/Leaflet.markercluster#all-options), +[events](https://github.com/Leaflet/Leaflet.markercluster#events) and +[methods](https://github.com/Leaflet/Leaflet.markercluster#methods) are +available within MCG Layer Support. Refer to Leaflet.markercluster documentation. + + + +## Limitations + +### Freezing at current zoom while not on map +If you request MCG to freeze at current zoom, but MCG is not on any map at that +moment, it will freeze at the zoom the map is at when added to it. + +## License +[![license](https://img.shields.io/github/license/ghybs/leaflet.markercluster.freezable.svg)](LICENSE) + +Leaflet.MarkerCluster.Freezable is distributed under the +[MIT License](http://choosealicense.com/licenses/mit/) (Expat type), like +Leaflet.markercluster.