diff --git a/site/public/documentation/_layout.ejs b/site/public/documentation/_layout.ejs index 83a4c49..290d40f 100644 --- a/site/public/documentation/_layout.ejs +++ b/site/public/documentation/_layout.ejs @@ -15,6 +15,10 @@ Introduction + ' href='/documentation/installation.html'> + Installation + + ' href='/documentation/core.html'> Core API diff --git a/site/public/documentation/core.md b/site/public/documentation/core.md index 875999c..f4e4730 100644 --- a/site/public/documentation/core.md +++ b/site/public/documentation/core.md @@ -1,28 +1,6 @@ Core API ======== -Installation ------------- - -Once you've [downloaded Planetary.js](/download/), you can include it via a `script` tag on your page *after* the inclusion of D3 and TopoJSON. This example uses the CDN URLs for those libraries: - -
-
HTML
- -```html - - - - - - - -... -``` -
- -If you use the default `topojson` plugin (most people will), you'll also need to make sure `world-110m.json` (or some other TopoJSON data file) is available on your server. This file is also available from [the download page](/download/). See the [TopoJSON Plugin documentation](/documentation/builtin_topojson.html) for more information. - Core API -------- diff --git a/site/public/documentation/faq.md b/site/public/documentation/faq.md index 2fc520a..099578b 100644 --- a/site/public/documentation/faq.md +++ b/site/public/documentation/faq.md @@ -45,53 +45,3 @@ planet's `draw` method. **Q:** I'm getting "Cannot read property 'geo' of undefined" or "Cannot call method 'feature' of undefined." **A:** Ensure you're requiring the [D3](http://d3js.org/) and [TopoJSON](https://github.com/mbostock/topojson) libraries before Planetary.js. - -
- -
- -**Q:** Can I use Planetary.js with AMD or CommonJS? - -**A:** Yes and no. Planetary.js uses a universal module definition, and so is compatible with AMD and CommonJS. However, neither D3 nor TopoJSON support AMD, and TopoJSON's CommonJS package (as installed with [npm](https://npmjs.org/)) uses Node-specific functionality, so you can't, for instance, [browserify](http://browserify.org/) it directly. - -## AMD - -This example uses [RequireJS](http://requirejs.org/). Since neither D3 nor TopoJSON support AMD, we will use RequireJS's [shim configuration](http://requirejs.org/docs/api.html#config-shim). - -
-
HTML
- -```html - - - - -``` - -
JavaScript
- -```javascript -requirejs.config({ - // Tell RequireJS to use `window.d3` and `window.topojson` - // for those libraries, respectively - shim: { - d3: { exports: 'd3' }, - topojson: { exports: 'topojson' } - }, - paths: { - 'd3': 'path/to/d3.v3.min', - 'topojson': 'path/to/topojson.v1.min' - } -}); - -requirejs(['planetaryjs'], function(planetaryjs) { - // Use Planetary.js here -}); - -``` -
- -## CommonJS - -To use Planetary.js with a tool like Browserify, you will need to create a shim for TopoJSON (D3 includes a Browserify-compatible script). Take a look at [browserify-shim](https://github.com/thlorenz/browserify-shim) for more information. diff --git a/site/public/documentation/index.md b/site/public/documentation/index.md index f21aee7..71641b5 100644 --- a/site/public/documentation/index.md +++ b/site/public/documentation/index.md @@ -15,7 +15,7 @@ The documentation is split up into several sections: Quick Start ----------- -If you want to get up-and-running quickly, or like to experiment and figure things out, you can use this HTML and JavaScript to get a very simple globe up and running. +If you want to get up-and-running quickly, or like to experiment and figure things out, you can use this HTML and JavaScript to get a very simple globe up and running (once you've [installed Planetary.js](/documentation/installation.html)). Note that you'll need to run this page from a web server of some kind so that Planetary.js can load the TopoJSON data via Ajax (Ajax requests don't work when viewing a page directly from the filesystem). diff --git a/site/public/documentation/installation.md b/site/public/documentation/installation.md new file mode 100644 index 0000000..4b9f37f --- /dev/null +++ b/site/public/documentation/installation.md @@ -0,0 +1,88 @@ +Installation +============ + +Once you've [downloaded Planetary.js](/download/), you can include it via a `script` tag on your page *after* the inclusion of D3 and TopoJSON. This example uses the CDN URLs for those libraries: + +
+
HTML
+ +```html + + + + + + + +... +``` +
+ +If you use the default `topojson` plugin (most people will), you'll also need to make sure `world-110m.json` (or some other TopoJSON data file) is available on your server. This file is also available from [the download page](/download/). See the [TopoJSON Plugin documentation](/documentation/builtin_topojson.html) for more information. + +Planetary.js also supports installation via AMD and CommonJS loaders. + +AMD +--- + +This example uses [RequireJS](http://requirejs.org/). Since neither D3 nor TopoJSON support AMD, we will use RequireJS's [shim configuration](http://requirejs.org/docs/api.html#config-shim). + +
+
HTML
+ +```html + + + + +``` + +
JavaScript
+ +```javascript +requirejs.config({ + // Tell RequireJS to use `window.d3` and `window.topojson` + // for those libraries, respectively + shim: { + d3: { exports: 'd3' }, + topojson: { exports: 'topojson' } + }, + paths: { + 'd3': 'path/to/d3.v3.min', + 'topojson': 'path/to/topojson.v1.min' + } +}); + +requirejs(['planetaryjs'], function(planetaryjs) { + // Use Planetary.js here +}); + +``` +
+ +CommonJS +-------- + +First, install `browserify` and `brfs` from npm (as well as `planetary.js`, if you haven't already). Then, create your application (here referred to as `app.js`) and bundle it with browserify, running the dependencies through brfs. + +
+
JavaScript
+ +```javascript +var planetaryjs = require('planetary.js'); + +var planet = planetaryjs.planet(); +var canvas = document.getElementById('canvas'); +planet.draw(canvas); +``` + +
Shell
+ +```shell +$ npm install browserify brfs +$ ./node_modules/.bin/browserify --g brfs app.js > bundle.js +``` +
+ +`bundle.js` is now ready to use!