(site) Add installation section; move AMD and CommonJS info there
This commit is contained in:
Brandon Tilley
parent
1764ee07f7
commit
fe1de35576
@ -15,6 +15,10 @@
|
||||
Introduction
|
||||
<i class='icon home'></i>
|
||||
</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'>
|
||||
Core API
|
||||
<i class='icon setting'></i>
|
||||
|
||||
@ -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:
|
||||
|
||||
<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
|
||||
--------
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
<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.
|
||||
|
||||
@ -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).
|
||||
|
||||
|
||||
88
site/public/documentation/installation.md
Normal file
88
site/public/documentation/installation.md
Normal 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!
|
||||
Loading…
Reference in New Issue
Block a user