Add documentation on default plugins

site/public/_header.ejs

@@ -1,4 +1,4 @@
-<title>Planetary.js</title>
+<title>Planetary.js: Awesome interactive globes for the web</title>
 <link href='http://fonts.googleapis.com/css?family=Source+Sans+Pro:400,700|Open+Sans:300italic,400,300,700' rel='stylesheet' type='text/css'>
 <link type="text/css" rel="stylesheet" href="/semantic/css/semantic.min.css">
 <link type="text/css" rel="stylesheet" href="/css/planetaryjs.css">

site/public/documentation/builtin.md

@@ -11,3 +11,5 @@ Planetary.js comes with several built-in plugins that provide a base set of func
 * [Pings](/documentation/builtin_pings.html) - draws animated, circular pings on the globe
 * [Zoom](/documentation/builtin_zoom.html) - enables mouse-based zooming of the globe via the mousewheel
 * [Drag](/documentation/builtin_drag.html) - enables mouse-based rotation of the globe via dragging
+
+Built-in plugins exposed as properties on `planetaryjs.plugins`.

site/public/documentation/builtin_borders.md

@@ -1,2 +1,29 @@
 Borders Plugin
 ==============
+
+The `borders` plugin renders the borders around (and between) countries. It uses TopoJSON data published to `planet.plugins.topojson.world` by the [TopoJSON plugin](/documentation/builtin_topojson.html).
+
+API
+---
+
+**`planetaryjs.plugins.borders([config])`**
+
+Valid keys for `config` are:
+
+* `stroke`: the `strokeStyle` to use for the context; defaults to `"gray"`
+* `lineWidth` the `lineWidth` to set on the context; defaults to no value, and the context's `lineWidth` is not modified
+* `type`: valid options are `"internal"`, `"external"`, or `"both"`. `"internal"` draws borders between countries but not coastlines; `"external"` does the opposite. `"both"`, unsurprisingly, draws both. Defaults to `"internal"`.
+
+<div class='ui raise segment'>
+<div class='ui red ribbon label'>JavaScript</div>
+
+```javascript
+planetaryjs.plugins.borders({
+  stroke: '#008000', lineWidth: 0.25, type: 'both'
+});
+```
+</div>
+
+See also:
+
+* [TopoJSON Plugin](/documentation/builtin_topojson.html)

site/public/documentation/builtin_earth.md

@@ -1,2 +1,36 @@
 Earth Plugin
 ============
+
+The `earth` plugin is simply a wrapper around the `topojson`, `oceans`, `land`, and `borders` plugins. It parses its configuration and passes pieces of it to the individual plugins.
+
+API
+---
+
+**`planetaryjs.plugins.earth([config])`**
+
+Valid keys for `config` are:
+
+* `topojson`: options to pass to the `topojson` plugin
+* `oceans`: options to pass to the `oceans` plugin
+* `land`: options to pass to the `land` plugin
+* `borders`: options to pass to the `borders` plugin
+
+<div class='ui raise segment'>
+<div class='ui red ribbon label'>JavaScript</div>
+
+```javascript
+planetaryjs.plugins.earth({
+  topojson: { file:   'world-110m.json' },
+  oceans:   { fill:   '#000080' },
+  land:     { fill:   '#339966' },
+  borders:  { stroke: '#008000' }
+});
+```
+</div>
+
+See also:
+
+* [TopoJSON Plugin](/documentation/builtin_topojson.html)
+* [Oceans Plugin](/documentation/builtin_oceans.html)
+* [Land Plugin](/documentation/builtin_land.html)
+* [Borders Plugin](/documentation/builtin_borders.html)

site/public/documentation/builtin_land.md

@@ -1,2 +1,29 @@
 Land Plugin
 ===========
+
+The `land` plugin renders Earth's landmasses. It uses TopoJSON data published to `planet.plugins.topojson.world` by the [TopoJSON plugin](/documentation/builtin_topojson.html).
+
+API
+---
+
+**`planetaryjs.plugins.land([config])`**
+
+Valid keys for `config` are:
+
+* `fill`: the `fillStyle` to use for the context; defaults to `"white"`
+* `stroke`: the `strokeStyle` to use for the context; defaults to no value, resulting in no stroke around the landmasses
+* `lineWidth` the `lineWidth` to set on the context; only effective if `stroke` is set. Defaults to no value, resulting in no change to the context's `lineWidth`
+
+<div class='ui raise segment'>
+<div class='ui red ribbon label'>JavaScript</div>
+
+```javascript
+planetaryjs.plugins.land({
+  fill: '#339966', stroke: '#000000'
+});
+```
+</div>
+
+See also:
+
+* [TopoJSON Plugin](/documentation/builtin_topojson.html)

site/public/documentation/builtin_oceans.md

@@ -1,2 +1,23 @@
 Oceans Plugin
 =============
+
+The `oceans` plugin simply renders the main shape of the globe, filling it in with a solid color.
+
+API
+---
+
+**`planetaryjs.plugins.oceans([config])`**
+
+Valid keys for `config` are:
+
+* `fill`: the `fillStyle` to use for the globe; defaults to `"black"`
+
+<div class='ui raise segment'>
+<div class='ui red ribbon label'>JavaScript</div>
+
+```javascript
+planetaryjs.plugins.oceans({
+  fill: '#000080'
+});
+```
+</div>

site/public/documentation/builtin_pings.md

@@ -1,2 +1,44 @@
 Pings Plugin
 ============
+
+The `pings` plugin allows you to display animated "pings" at any location on the planet. It publishes a method to create pings at `planet.plugins.pings.add`.
+
+API
+---
+
+**`planetaryjs.plugins.pings([config])`**
+
+Valid keys for `config` are:
+
+* `color`: the default color for pings; defaults to `"white"`
+* `ttl`: the default TTL for pings in milliseconds (how long they take to fade out); defaults to 2000
+* `angle`: the maximum angle for the ping (it will grow to this size over the course of its TTL); defaults to `5`
+
+<div class='ui raise segment'>
+<div class='ui red ribbon label'>JavaScript</div>
+
+```javascript
+planetaryjs.plugins.pings({
+  color: 'yellow', ttl: 5000, angle: 10
+});
+```
+</div>
+
+**`planet.plugins.pings.add(lat, lng, [config])`**
+
+Add a new ping to the globe at the latitudinal and longitudinal coordinates specified by `lat` and `lng`. `config` may take all the same keys as the configuration option for the plugin itself; any values will overwrite values from that object, if any were set.
+
+<div class='ui raise segment'>
+<div class='ui red ribbon label'>JavaScript</div>
+
+```javascript
+var colors = ['red', 'yellow', 'white', 'orange', 'green', 'cyan', 'pink'];
+setInterval(function() {
+  var lat = Math.random() * 170 - 85;
+  var lng = Math.random() * 360 - 180;
+  var color = colors[Math.floor(Math.random() * colors.length)];
+  var angle = Math.random() * 10;
+  planet.plugins.pings.add(lat, lng, { color: color, ttl: 2000, angle: angle });
+}, 250);
+```
+</div>

site/public/documentation/builtin_topojson.md

@@ -1,2 +1,44 @@
 TopoJSON Plugin
 ===============
+
+The `topojson` plugin parses [TopoJSON data](https://github.com/mbostock/topojson) and publishes it on `planet.plugins.topojson.world` for other plugins to use (particularly for rendering geographical data using D3).
+
+The plugin can load data from a file using Ajax, or can be provided an object that has come from some other source.
+
+API
+---
+
+**`planetaryjs.plugins.topojson([config])`**
+
+Valid keys for `config` are:
+
+* `world`: a JavaScript object representing TopoJSON data (not JSON data); defaults to no value, which will cause the plugin to load data from the `file` configuration option
+* `file`: the path to a TopoJSON data file to be loaded via Ajax; defaults to `"world-110m.json"`, which can be downloaded with the Planetary.js library from the [download page](https://github.com/BinaryMuse/planetary.js/releases).
+
+If you plan on creating more than one planet from the same TopoJSON data, you can load the data once before loading the plugin and pass the parsed data to the plugin via the `world` property rather than letting the plugin load the data via Ajax each time a new planet is created.
+
+<div class='ui raise segment'>
+<div class='ui red ribbon label'>JavaScript</div>
+
+```javascript
+planetaryjs.plugins.topojson({
+  file: '/data/world-110m.json'
+});
+```
+</div>
+
+<div class='ui raise segment'>
+<div class='ui red ribbon label'>JavaScript</div>
+
+```javascript
+d3.json('/data/world-110m.json', function(err, data) {
+  planetaryjs.plugins.topojson({
+    world: data
+  });
+  // Create planets inside this callback
+});
+```
+</div>
+
+* [Land Plugin](/documentation/builtin_land.html)
+* [Borders Plugin](/documentation/builtin_borders.html)

site/public/js/lib/planetaryjs.min.js

@@ -1,2 +1,2 @@
 /*! Planetary.js 0.1.1 | (c) 2013 Brandon Tilley | Released under MIT License */
-!function(n,t){"function"==typeof define&&define.amd?define(["d3","topojson"],t):"object"==typeof exports?module.exports=t(require("d3"),require("topojson")):n.planetaryjs=t(n.d3,n.topojson,n)}(this,function(n,t,o){"use strict";var i=null;o&&(i=o.planetaryjs);var e=[],r=function(t,o,i){n.timer(function(){t.context.clearRect(0,0,o.width,o.height);for(var n=0;n<i.onDraw.length;n++)i.onDraw[n]()})},l=function(n,t){for(var o=0;o<e.length;o++)t.unshift(e[o]);0==t.length&&(a.plugins.earth&&n.loadPlugin(a.plugins.earth()),a.plugins.pings&&n.loadPlugin(a.plugins.pings()));for(var o=0;o<t.length;o++)t[o](n)},u=function(n,t,o){if(o.onInit.length){var i=0,e=function(n){var t=o.onInit[i];t.length?t(function(){i++,n()}):(t(),i++,setTimeout(n,0))},l=function(){i>=o.onInit.length?r(n,t,o):e(l)};e(l)}else r(n,t,o)},s=function(n,t,o,i){l(n,o),n.canvas=t,n.context=t.getContext("2d"),u(n,t,i)},a={plugins:{},noConflict:function(){return o.planetaryjs=i,a},loadPlugin:function(n){e.push(n)},planet:function(){var t=[],o={onInit:[],onDraw:[]},i={plugins:{},draw:function(n){s(i,n,t,o)},onInit:function(n){o.onInit.push(n)},onDraw:function(n){o.onDraw.push(n)},loadPlugin:function(n){t.push(n)},withSavedContext:function(n){if(!this.context)throw new Error("No canvas to fetch context for");this.context.save(),n(this.context),this.context.restore()}};return i.projection=n.geo.orthographic().clipAngle(90).precision(0),i.path=n.geo.path().projection(i.projection),i}};return a.plugins.topojson=function(t){return function(o){o.plugins.topojson={},o.onInit(function(i){if(t.world)o.plugins.topojson.world=t.world,setTimeout(i,0);else{var e=t.file||"world-110m.json";n.json(e,function(n,t){if(n)throw new Error("Could not load JSON "+e);o.plugins.topojson.world=t,i()})}})}},a.plugins.oceans=function(n){return function(t){t.onDraw(function(){t.withSavedContext(function(o){o.beginPath(),t.path.context(o)({type:"Sphere"}),o.fillStyle=n.fill||"black",o.fill(),0!=n.stroke&&(o.strokeStyle=n.stroke,o.stroke())})})}},a.plugins.land=function(n){return function(o){var i=null;o.onInit(function(){var n=o.plugins.topojson.world;i=t.feature(n,n.objects.land)}),o.onDraw(function(){o.withSavedContext(function(t){t.beginPath(),o.path.context(t)(i),0!=n.fill&&(t.fillStyle=n.fill||"white",t.fill()),n.stroke&&(t.strokeStyle=n.stroke,t.stroke())})})}},a.plugins.borders=function(n){return function(o){var i=null;o.onInit(function(){var n=o.plugins.topojson.world,e=n.objects.countries;i=t.mesh(n,e,function(n,t){return n.id!==t.id})}),o.onDraw(function(){o.withSavedContext(function(t){t.beginPath(),o.path.context(t)(i),t.strokeStyle=n.stroke||"gray",t.stroke()})})}},a.plugins.earth=function(n){var n=n||{},t=n.topojson||{},o=n.oceans||{},i=n.land||{},e=n.borders||{};return function(n){a.plugins.topojson(t)(n),a.plugins.oceans(o)(n),a.plugins.land(i)(n),a.plugins.borders(e)(n)}},a.plugins.pings=function(){var t=[],o=function(n,o,i){var i=i||{};i.color=i.color||"white",i.ttl=i.ttl||2e3,i.angle=i.angle||5,t.push({lat:n,lng:o,time:new Date,options:i})},i=function(n,o,i){for(var r=[],l=0;l<t.length;l++){var u=t[l],s=i-u.time;s<u.options.ttl&&(r.push(u),e(n,o,i,s,u))}t=r},e=function(t,o,i,e,r){var l=1-e/r.options.ttl,u=n.rgb(r.options.color);u="rgba("+u.r+","+u.g+","+u.b+","+l+")",o.strokeStyle=u;var s=n.geo.circle().origin([r.lng,r.lat]).angle(e/r.options.ttl*r.options.angle)();o.beginPath(),t.path.context(o)(s),o.stroke()};return function(n){n.plugins.pings={add:o},n.onDraw(function(){var t=new Date;n.withSavedContext(function(o){i(n,o,t)})})}},a});
+!function(n,t){"function"==typeof define&&define.amd?define(["d3","topojson"],t):"object"==typeof exports?module.exports=t(require("d3"),require("topojson")):n.planetaryjs=t(n.d3,n.topojson,n)}(this,function(n,t,o){"use strict";var i=null;o&&(i=o.planetaryjs);var e=[],r=function(t,o,i){n.timer(function(){t.context.clearRect(0,0,o.width,o.height);for(var n=0;n<i.onDraw.length;n++)i.onDraw[n]()})},l=function(n,t){for(var o=0;o<e.length;o++)t.unshift(e[o]);0==t.length&&(s.plugins.earth&&n.loadPlugin(s.plugins.earth()),s.plugins.pings&&n.loadPlugin(s.plugins.pings()));for(var o=0;o<t.length;o++)t[o](n)},u=function(n,t,o){if(o.onInit.length){var i=0,e=function(n){var t=o.onInit[i];t.length?t(function(){i++,n()}):(t(),i++,setTimeout(n,0))},l=function(){i>=o.onInit.length?r(n,t,o):e(l)};e(l)}else r(n,t,o)},a=function(n,t,o,i){l(n,o),n.canvas=t,n.context=t.getContext("2d"),u(n,t,i)},s={plugins:{},noConflict:function(){return o.planetaryjs=i,s},loadPlugin:function(n){e.push(n)},planet:function(){var t=[],o={onInit:[],onDraw:[]},i={plugins:{},draw:function(n){a(i,n,t,o)},onInit:function(n){o.onInit.push(n)},onDraw:function(n){o.onDraw.push(n)},loadPlugin:function(n){t.push(n)},withSavedContext:function(n){if(!this.context)throw new Error("No canvas to fetch context for");this.context.save(),n(this.context),this.context.restore()}};return i.projection=n.geo.orthographic().clipAngle(90).precision(0),i.path=n.geo.path().projection(i.projection),i}};return s.plugins.topojson=function(t){return function(o){o.plugins.topojson={},o.onInit(function(i){if(t.world)o.plugins.topojson.world=t.world,setTimeout(i,0);else{var e=t.file||"world-110m.json";n.json(e,function(n,t){if(n)throw new Error("Could not load JSON "+e);o.plugins.topojson.world=t,i()})}})}},s.plugins.oceans=function(n){return function(t){t.onDraw(function(){t.withSavedContext(function(o){o.beginPath(),t.path.context(o)({type:"Sphere"}),o.fillStyle=n.fill||"black",o.fill()})})}},s.plugins.land=function(n){return function(o){var i=null;o.onInit(function(){var n=o.plugins.topojson.world;i=t.feature(n,n.objects.land)}),o.onDraw(function(){o.withSavedContext(function(t){t.beginPath(),o.path.context(t)(i),0!=n.fill&&(t.fillStyle=n.fill||"white",t.fill()),n.stroke&&(n.lineWidth&&(t.lineWidth=n.lineWidth),t.strokeStyle=n.stroke,t.stroke())})})}},s.plugins.borders=function(n){return function(o){var i=null,e={internal:function(n,t){return n.id!==t.id},external:function(n,t){return n.id===t.id},both:function(){return!0}};o.onInit(function(){var r=o.plugins.topojson.world,l=r.objects.countries,u=n.type||"internal";i=t.mesh(r,l,e[u])}),o.onDraw(function(){o.withSavedContext(function(t){t.beginPath(),o.path.context(t)(i),t.strokeStyle=n.stroke||"gray",n.lineWidth&&(t.lineWidth=n.lineWidth),t.stroke()})})}},s.plugins.earth=function(n){var n=n||{},t=n.topojson||{},o=n.oceans||{},i=n.land||{},e=n.borders||{};return function(n){s.plugins.topojson(t)(n),s.plugins.oceans(o)(n),s.plugins.land(i)(n),s.plugins.borders(e)(n)}},s.plugins.pings=function(t){var o=[],i=function(n,i,e){var e=e||{};e.color=e.color||t.color||"white",e.ttl=e.ttl||t.ttl||2e3,e.angle=e.angle||t.angle||5,o.push({lat:n,lng:i,time:new Date,options:e})},e=function(n,t,i){for(var e=[],l=0;l<o.length;l++){var u=o[l],a=i-u.time;a<u.options.ttl&&(e.push(u),r(n,t,i,a,u))}o=e},r=function(t,o,i,e,r){var l=1-e/r.options.ttl,u=n.rgb(r.options.color);u="rgba("+u.r+","+u.g+","+u.b+","+l+")",o.strokeStyle=u;var a=n.geo.circle().origin([r.lng,r.lat]).angle(e/r.options.ttl*r.options.angle)();o.beginPath(),t.path.context(o)(a),o.stroke()};return function(n){n.plugins.pings={add:i},n.onDraw(function(){var t=new Date;n.withSavedContext(function(o){e(n,o,t)})})}},s});