diff --git a/site/public/_header.ejs b/site/public/_header.ejs index e174d91..cd051d0 100644 --- a/site/public/_header.ejs +++ b/site/public/_header.ejs @@ -1,4 +1,4 @@ -Planetary.js +Planetary.js: Awesome interactive globes for the web diff --git a/site/public/documentation/builtin.md b/site/public/documentation/builtin.md index d774d35..0590485 100644 --- a/site/public/documentation/builtin.md +++ b/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`. diff --git a/site/public/documentation/builtin_borders.md b/site/public/documentation/builtin_borders.md index 004fea1..ae7bf88 100644 --- a/site/public/documentation/builtin_borders.md +++ b/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"`. + +
+
JavaScript
+ +```javascript +planetaryjs.plugins.borders({ + stroke: '#008000', lineWidth: 0.25, type: 'both' +}); +``` +
+ +See also: + +* [TopoJSON Plugin](/documentation/builtin_topojson.html) diff --git a/site/public/documentation/builtin_earth.md b/site/public/documentation/builtin_earth.md index 9bfdf5a..4074706 100644 --- a/site/public/documentation/builtin_earth.md +++ b/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 + +
+
JavaScript
+ +```javascript +planetaryjs.plugins.earth({ + topojson: { file: 'world-110m.json' }, + oceans: { fill: '#000080' }, + land: { fill: '#339966' }, + borders: { stroke: '#008000' } +}); +``` +
+ +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) diff --git a/site/public/documentation/builtin_land.md b/site/public/documentation/builtin_land.md index 3665829..b77ca0e 100644 --- a/site/public/documentation/builtin_land.md +++ b/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` + +
+
JavaScript
+ +```javascript +planetaryjs.plugins.land({ + fill: '#339966', stroke: '#000000' +}); +``` +
+ +See also: + +* [TopoJSON Plugin](/documentation/builtin_topojson.html) diff --git a/site/public/documentation/builtin_oceans.md b/site/public/documentation/builtin_oceans.md index e136052..7be79f4 100644 --- a/site/public/documentation/builtin_oceans.md +++ b/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"` + +
+
JavaScript
+ +```javascript +planetaryjs.plugins.oceans({ + fill: '#000080' +}); +``` +
diff --git a/site/public/documentation/builtin_pings.md b/site/public/documentation/builtin_pings.md index 436a98b..361153d 100644 --- a/site/public/documentation/builtin_pings.md +++ b/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` + +
+
JavaScript
+ +```javascript +planetaryjs.plugins.pings({ + color: 'yellow', ttl: 5000, angle: 10 +}); +``` +
+ +**`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. + +
+
JavaScript
+ +```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); +``` +
diff --git a/site/public/documentation/builtin_topojson.md b/site/public/documentation/builtin_topojson.md index b043714..8727573 100644 --- a/site/public/documentation/builtin_topojson.md +++ b/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. + +
+
JavaScript
+ +```javascript +planetaryjs.plugins.topojson({ + file: '/data/world-110m.json' +}); +``` +
+ +
+
JavaScript
+ +```javascript +d3.json('/data/world-110m.json', function(err, data) { + planetaryjs.plugins.topojson({ + world: data + }); + // Create planets inside this callback +}); +``` +
+ +* [Land Plugin](/documentation/builtin_land.html) +* [Borders Plugin](/documentation/builtin_borders.html) diff --git a/site/public/js/lib/planetaryjs.min.js b/site/public/js/lib/planetaryjs.min.js index 28b9557..d8a8e9e 100644 --- a/site/public/js/lib/planetaryjs.min.js +++ b/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=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=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