Better dependencies / installation instructions (#329)

Indigo744 · web-flow · commit 28d08fe42a78 · 2017-10-17T19:38:07.000+02:00
* Update bower.json (add ignore file list)
* Update package.json (set peerdependencies and file list)
* Allow multiple jquery/raphael dependencies
* Update README file for installation
* Use minified version for CDNJs
diff --git a/README.md b/README.md
@@ -33,23 +33,88 @@ Mapael supports all modern browsers and Internet Explorer 9+. For older versions
 *   **Resizable** Maps are easily resizable.
 *   **Zoom** Zoom and panning abilities (also on mobile devices).
 
+## Installation
+
+### Directly in your page
+
+**Note on dependencies**: [jQuery](https://jquery.com/) and [Raphael](https://raphaeljs.com) 
+(and [Mousewheel](https://github.com/jquery/jquery-mousewheel), if needed) 
+must be loaded **before** Mapael in order to work properly.
+
+**Note on maps**: map files must be loaded **after** Mapael in order to work properly.
+
+#### Using CDN
+
+Include in your project page one of these tags:
+```html
+<script src="//cdnjs.cloudflare.com/ajax/libs/jquery-mapael/2.1.0/js/jquery.mapael.min.js"></script>
+<script src="//cdn.jsdelivr.net/npm/jquery-mapael@2.1.0/js/jquery.mapael.min.js"></script>
+```
+
+#### Using self-hosted
+
+Download the [latest version](https://github.com/neveldo/jQuery-Mapael/releases/tag/2.1.0) 
+and extract `jquery.mapael.min.js` in your project.
+
+Then, add the script to your page (update the path as needed):
+```html
+<script src="path/to/jquery.mapael.min.js"></script>
+```
+
+### Using a package manager
+
+#### NPM / Yarn
+
+In your project root, run either commandline:
+```text
+npm i --save jquery-mapael
+yarn add jquery-mapael
+```
+
+However, if you don't need the optional Mousewheel feature (for Zoom feature), 
+then you can use the `--no-optional` flag to skip optional dependencies. 
+
+Use either:
+```text
+npm i --no-optional jquery-mapael
+yarn add --no-optional jquery-mapael
+```
+
+Then in your application:
+```js
+require('jquery-mapael');
+```
+Or, in ES6:
+```js
+import 'jquery-mapael';
+```
+
+#### Bower
+
+In your project root, run:
+```text
+bower install jquery-mapael --save
+```
+
 ## Basic code example
 
 Here is the simplest example that shows how to display an empty map of the world :
 
 **HTML :**
-
+```html
     <div class="container">
         <div class="map">Alternative content</div>
     </div>
+```
 
 **JS :**
-
+```js
     $(".container").mapael({
         map : {
             name : "world_countries"
         }
     });
+```
 
 ## Examples
 
diff --git a/bower.json b/bower.json
@@ -1,19 +1,29 @@
 {
-  "name": "jquery-mapael",
-  "version": "2.1.0",
-  "main": "./js/jquery.mapael.js",
-  "description": "jQuery Mapael is a jQuery plugin based on raphael.js that allows you to display dynamic vector maps.",
-  "license": "MIT",
-  "ignore": [],
-  "dependencies": {
-    "raphael": "^2.2",
-    "jquery": "^3.0",
-    "jquery-mousewheel": "^3.1"
-  },
-  "devDependencies": {
-    "grunt": "^1.0",
-    "grunt-contrib-jshint": "^1.0",
-    "grunt-contrib-qunit": "^1.2",
-    "grunt-contrib-uglify": "^2.0"
-  }
+    "name": "jquery-mapael",
+    "version": "2.1.0",
+    "main": "./js/jquery.mapael.js",
+    "description": "jQuery Mapael is a jQuery plugin based on raphael.js that allows you to display dynamic vector maps.",
+    "license": "MIT",
+    "ignore": [
+        ".*",
+        "*.json",
+        "*.md",
+        "*.txt",
+        "Gruntfile.js",
+        "test",
+        "examples",
+        "!LICENSE",
+        "!CHANGELOG.md"
+    ],
+    "dependencies": {
+        "raphael": "^2.2",
+        "jquery": "^3.0",
+        "jquery-mousewheel": "^3.1"
+    },
+    "devDependencies": {
+        "grunt": "^1.0",
+        "grunt-contrib-jshint": "^1.0",
+        "grunt-contrib-qunit": "^1.2",
+        "grunt-contrib-uglify": "^2.0"
+    }
 }
diff --git a/package.json b/package.json
@@ -1,40 +1,48 @@
 {
-  "name": "jquery-mapael",
-  "version": "2.1.0",
-  "description": "jQuery Mapael is a jQuery plugin based on raphael.js that allows you to display dynamic vector maps.",
-  "homepage": "https://www.vincentbroute.fr/mapael/",
-  "main": "./js/jquery.mapael.js",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/neveldo/jQuery-Mapael.git"
-  },
-  "author": "Vincent Brouté <contact@vincentbroute.fr> (https://www.vincentbroute.fr/)",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/neveldo/jQuery-Mapael/issues"
-  },
-  "keywords": [
-    "jquery",
-    "map",
-    "vector",
-    "svg",
-    "dataviz",
-    "dynamic",
-    "jquery-plugin",
-    "browser"
-  ],
-  "dependencies": {
-    "jquery": "^3.0",
-    "raphael": "^2.2",
-    "jquery-mousewheel": "^3.1"
-  },
-  "devDependencies": {
-    "grunt": "^1.0",
-    "grunt-contrib-jshint": "^1.1",
-    "grunt-contrib-qunit": "^1.2",
-    "grunt-contrib-uglify": "^2.0"
-  },
-  "scripts": {
-    "test": "grunt test"
-  }
+    "name": "jquery-mapael",
+    "version": "2.1.0",
+    "description": "jQuery Mapael is a jQuery plugin based on raphael.js that allows you to display dynamic vector maps.",
+    "homepage": "https://www.vincentbroute.fr/mapael/",
+    "main": "./js/jquery.mapael.js",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/neveldo/jQuery-Mapael.git"
+    },
+    "author": "Vincent Brouté <contact@vincentbroute.fr> (https://www.vincentbroute.fr/)",
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/neveldo/jQuery-Mapael/issues"
+    },
+    "keywords": [
+        "jquery",
+        "map",
+        "vector",
+        "svg",
+        "dataviz",
+        "dynamic",
+        "jquery-plugin",
+        "browser"
+    ],
+    "dependencies": {
+        "jquery": "^3.0 || ^2.0 || ^1.0",
+        "raphael": "^2.2.0 || ^2.1.0"
+    },
+    "peerDependencies": {
+        "jquery": "^3.0 || ^2.0 || ^1.0"
+    },
+    "optionalDependencies": {
+        "jquery-mousewheel": "^3.1"
+    },
+    "devDependencies": {
+        "grunt": "^1.0",
+        "grunt-contrib-jshint": "^1.1",
+        "grunt-contrib-qunit": "^1.2",
+        "grunt-contrib-uglify": "^2.0"
+    },
+    "files": [
+        "js/"
+    ],
+    "scripts": {
+        "test": "grunt test"
+    }
 }
