andy/planetary.js
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

(site) Add installation section; move AMD and CommonJS info there

Browse Source
This commit is contained in:
Brandon Tilley 2014-01-01 18:18:51 -08:00
parent 1764ee07f7
commit fe1de35576
5 changed files with 93 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
site/public/documentation/_layout.ejs
View File

@ -15,6 +15,10 @@
Introduction Introduction
<i class='icon home'></i> <i class='icon home'></i>
</a> </a>
<a class='purple item <%- current.source == 'installation' ? 'active' : '' %>' href='/documentation/installation.html'>
Installation
<i class='icon download'></i>
</a>
<a class='blue item <%- current.source == 'core' ? 'active' : '' %>' href='/documentation/core.html'> <a class='blue item <%- current.source == 'core' ? 'active' : '' %>' href='/documentation/core.html'>
Core API Core API
<i class='icon setting'></i> <i class='icon setting'></i>

22
site/public/documentation/core.md
View File

@ -1,28 +1,6 @@
Core API 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:
<div class='ui raised segment'>
<div class='ui blue ribbon label'>HTML</div>
```html
<html>
<head>
<script type='text/javascript' src='http://d3js.org/d3.v3.min.js'></script>
<script type='text/javascript' src='http://d3js.org/topojson.v1.min.js'></script>
<script type='text/javascript' src='path/to/planetaryjs.min.js'></script>
</head>
<body>
...
```
</div>
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 Core API
-------- --------

50
site/public/documentation/faq.md
View File

@ -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." **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. **A:** Ensure you're requiring the [D3](http://d3js.org/) and [TopoJSON](https://github.com/mbostock/topojson) libraries before Planetary.js.
<div class="ui horizontal icon divider">
<i class="globe icon"></i>
</div>
**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).
<div class='ui raised segment'>
<div class='ui blue ribbon label'>HTML</div>
```html
<body>
<canvas id='globe' width='500' height='500'></canavs>
<script src='//cdnjs.cloudflare.com/ajax/libs/require.js/2.1.9/require.min.js'
data-main='/app.js'></script>
</body>
```
<div class='ui red ribbon label'>JavaScript</div>
```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
});
```
</div>
## 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.

2
site/public/documentation/index.md
View File

@ -15,7 +15,7 @@ The documentation is split up into several sections:
Quick Start 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). 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).

88
site/public/documentation/installation.md Normal file
View File

@ -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:
<div class='ui raised segment'>
<div class='ui blue ribbon label'>HTML</div>
```html
<html>
<head>
<script type='text/javascript' src='http://d3js.org/d3.v3.min.js'></script>
<script type='text/javascript' src='http://d3js.org/topojson.v1.min.js'></script>
<script type='text/javascript' src='path/to/planetaryjs.min.js'></script>
</head>
<body>
...
```
</div>
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).
<div class='ui raised segment'>
<div class='ui blue ribbon label'>HTML</div>
```html
<body>
<canvas id='globe' width='500' height='500'></canavs>
<script src='//cdnjs.cloudflare.com/ajax/libs/require.js/2.1.9/require.min.js'
data-main='/app.js'></script>
</body>
```
<div class='ui red ribbon label'>JavaScript</div>
```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
});
```
</div>
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.
<div class='ui raised segment'>
<div class='ui red ribbon label'>JavaScript</div>
```javascript
var planetaryjs = require('planetary.js');
var planet = planetaryjs.planet();
var canvas = document.getElementById('canvas');
planet.draw(canvas);
```
<div class='ui purple ribbon label'>Shell</div>
```shell
$ npm install browserify brfs
$ ./node_modules/.bin/browserify --g brfs app.js > bundle.js
```
</div>
`bundle.js` is now ready to use!