From df3c44c6c548ada455dcb3bb86f48fb537234685 Mon Sep 17 00:00:00 2001 From: Brandon Tilley Date: Sat, 21 Dec 2013 19:14:22 -0800 Subject: [PATCH] Update site --- css/planetaryjs.css | 2 +- documentation/builtin_topojson.html | 83 +++++++++++++ documentation/core.html | 121 +++++++++++++++++++ documentation/index.html | 91 +++++++++++++++ documentation/planet.html | 175 ++++++++++++++++++++++++++++ documentation/plugins.html | 121 +++++++++++++++++++ index.html | 68 ++++++----- 7 files changed, 628 insertions(+), 33 deletions(-) create mode 100644 documentation/builtin_topojson.html create mode 100644 documentation/core.html create mode 100644 documentation/index.html create mode 100644 documentation/planet.html create mode 100644 documentation/plugins.html diff --git a/css/planetaryjs.css b/css/planetaryjs.css index 59a94b1..d238785 100644 --- a/css/planetaryjs.css +++ b/css/planetaryjs.css @@ -1 +1 @@ -html,body{font-size:15px;font-family:"Open Sans","Helvetica Neue","Helvetica","Arial",sans-serif}body{margin:0;padding:0}h1,h2,h3,h4,h5,h6{font-family:"Source Sans Pro","Helvetica Neue","Helvetica","Arial",sans-serif}h1.subheader,h2.subheader,h3.subheader,h4.subheader,h5.subheader,h6.subheader{font-weight:300}h1.title-header,h2.title-header{margin-top:0px;margin-bottom:10px}.content.container{padding-top:50px}.centered{text-align:center}.feature-list{font-size:17px}.feature-list .icon{margin-right:5px !important}a.ui.icon.header{text-decoration:none;color:black}a.ui.icon.header:hover{color:blue}.divider .icon.huge{font-size:2em}.footer .text{text-align:center}canvas{width:350px;height:350px}@media screen and (max-width:768px){.hide-on-mobile{display:none !important}.ui.grid>.eight.wide.column{width:auto !important;min-width:100%}}@media screen and (min-width:769px){.hide-on-non-mobile{display:none !important}.main-menu .items{text-align:center;max-width:900px}}@media screen and (min-width:1050px){.main-menu{padding-left:8%}}.spacer{display:inline-block;width:50px}.ui.large.menu .item.minor{font-size:14px}.homepage-globe-canvas{text-align:right}@media screen and (max-width:998px){.homepage-globe-canvas{text-align:center}}.ui.dark.blue.label{background-color:#000080 !important}.ui.dark.blue.label:before{background-color:#000080 !important}.no-underline{text-decoration:none} \ No newline at end of file +html,body{font-size:15px;font-family:"Open Sans","Helvetica Neue","Helvetica","Arial",sans-serif}body{margin:0;padding:0}h1,h2,h3,h4,h5,h6{font-family:"Source Sans Pro","Helvetica Neue","Helvetica","Arial",sans-serif}h1.subheader,h2.subheader,h3.subheader,h4.subheader,h5.subheader,h6.subheader{font-weight:300}h1.title-header,h2.title-header{margin-top:0px;margin-bottom:10px}.content.container{padding-top:50px}.content.container .slim{max-width:1108px;padding:0 20px;margin:0 auto}.centered{text-align:center}.feature-list{font-size:17px}.feature-list .icon{margin-right:5px !important}a.ui.icon.header{text-decoration:none;color:black}a.ui.icon.header:hover{color:blue}.divider .icon.huge{font-size:2em}.footer .text{text-align:center}canvas{width:350px;height:350px}@media screen and (max-width:768px){.hide-on-mobile{display:none !important}.ui.grid>.wide.column{width:auto !important;min-width:100%}}.column h1:first-child{padding-top:0;margin-top:0}@media screen and (min-width:769px){.hide-on-non-mobile{display:none !important}.main-menu .items{text-align:center;max-width:900px}}@media screen and (min-width:1050px){.main-menu{padding-left:8%}}.spacer{display:inline-block;width:50px}.ui.large.menu .item.minor{font-size:14px}.homepage-globe-canvas{text-align:right}@media screen and (max-width:998px){.homepage-globe-canvas{text-align:center}}.ui.dark.blue.label{background-color:#000080 !important}.ui.dark.blue.label:before{background-color:#000080 !important}.no-underline{text-decoration:none}.ui.menu .item.with-subitems{padding-bottom:0.2em}.ui.menu .item.contains-subitems{padding-top:0;padding-bottom:0;margin-top:0}pre{font-size:14px;overflow-x:auto} \ No newline at end of file diff --git a/documentation/builtin_topojson.html b/documentation/builtin_topojson.html new file mode 100644 index 0000000..7830c65 --- /dev/null +++ b/documentation/builtin_topojson.html @@ -0,0 +1,83 @@ + + + + Planetary.js + + + + + + + + + + +
+
+ + Planetary.js + + + + Download + + + Examples + + + Documentation + + + Fork on GitHub + +
+
+ + +
+
+
+
+ + Introduction + + + + Core API + + + + Planet API + + + + Plugins + + + + Built-In Plugins + + +
+
+ Earth + TopoJSON + Oceans + Land + Borders + Pings + Zoom + Drag +
+
+
+
+ +
+

TopoJSON Plugin

+ +
+
+
+ + diff --git a/documentation/core.html b/documentation/core.html new file mode 100644 index 0000000..6e56686 --- /dev/null +++ b/documentation/core.html @@ -0,0 +1,121 @@ + + + + Planetary.js + + + + + + + + + + +
+
+ + Planetary.js + + + + Download + + + Examples + + + Documentation + + + Fork on GitHub + +
+
+ + +
+
+
+
+ + Introduction + + + + Core API + + + + Planet API + + + + Plugins + + + + Built-In Plugins + + +
+
+ Earth + TopoJSON + Oceans + Land + Borders + Pings + Zoom + Drag +
+
+
+
+ +
+

Core API

+

Installation

+

Once you've downloaded Planetary.js, 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>
+<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>
+...
+

+

Core API

+

planetaryjs.noConflict()

+

In non-AMD and non-CommonJS environments, Planetary.js takes over the global planetaryjs namespace (in the browser, this means window.planetaryjs). If, for some reason, something else useful was there before you loaded Planetary.js, you can ask for it to be returned to that spot by calling planetaryjs.noConflict(). The Planetary.js library will be returned from the function, so you can continue to use the library.

+
+
JavaScript
+ +
var planetary = planetaryjs.noConflict();
+

+

planetaryjs.loadPlugin(plugin)

+

Planetary.js uses a plugin architecture for all its functionality. Calling planetaryjs.loadPlugin will cause that plugin to be loaded in all planets created from this library. If you only want to use a plugin in some of your planets, use the planet.loadPlugin method (from the Planet API) instead.

+
+
JavaScript
+ +
planetaryjs.loadPlugin(somePlugin);
+planetaryjs.loadPlugin(somePluginGenerator());
+

+

For more information on the plugin system and API, please see the Plugins documentation.

+

planetaryjs.planet()

+

The planet API call returns a new planet instance, which represents a single globe. It will be created with all the plugins registered with planetaryjs.loadPlugin() active. It has various methods for manipulating the globe and drawing it to a canvas. The Planet API covers these methods in considerably more detail.

+
+
JavaScript
+ +
var planet = planetaryjs.planet();
+

+ +
+
+
+ + diff --git a/documentation/index.html b/documentation/index.html new file mode 100644 index 0000000..7793919 --- /dev/null +++ b/documentation/index.html @@ -0,0 +1,91 @@ + + + + Planetary.js + + + + + + + + + + +
+
+ + Planetary.js + + + + Download + + + Examples + + + Documentation + + + Fork on GitHub + +
+
+ + +
+
+
+
+ + Introduction + + + + Core API + + + + Planet API + + + + Plugins + + + + Built-In Plugins + + +
+
+ Earth + TopoJSON + Oceans + Land + Borders + Pings + Zoom + Drag +
+
+
+
+ +
+

Introduction

+

Planetary.js is a JavaScript library for building awesome interactive globes. It uses D3 and TopoJSON to parse and render geographic data. Planetary.js is a plugin-based system; even the default functionality is implemented as plugins! This makes Planetary.js extremely flexible.

+

The documentation is split up into several sections:

+
    +
  • Core API describes the top-level Planetary.js API, including installing and configuring the library and creating new instances of planets.
    • +
  • Planet API describes the API associated with a planet instance, including modifying its properties and accessing a special canvas context that allows you to draw on the globe.
    • +
  • Plugins describes the plugin architecture of Planetary.js and shows how you can easily build your own plugins to modify the behavior of Planetary.js
    • +
  • Built-In Plugins describes each of the built-in plugins in turn, including their public API and how to use them in a project.
    • +
+ +
+
+
+ + diff --git a/documentation/planet.html b/documentation/planet.html new file mode 100644 index 0000000..662e07c --- /dev/null +++ b/documentation/planet.html @@ -0,0 +1,175 @@ + + + + Planetary.js + + + + + + + + + + +
+
+ + Planetary.js + + + + Download + + + Examples + + + Documentation + + + Fork on GitHub + +
+
+ + +
+
+
+
+ + Introduction + + + + Core API + + + + Planet API + + + + Plugins + + + + Built-In Plugins + + +
+
+ Earth + TopoJSON + Oceans + Land + Borders + Pings + Zoom + Drag +
+
+
+
+ +
+

Planet API

+

A "planet" represents a single globe and its rendering instructions. It is created from the planetaryjs.planet() method; see the Core API documentation for more details.

+

planet.loadPlugin(plugin)

+

Planetary.js uses a plugin architecture for all its functionality. While you can load plugins at the global library level, Planetary.js also allows you to load plugins for specific planets. If a planet is drawn and no plugins have been loaded globally and no plugins have been loaded for the specific planet instance, it will use the default earth and pings plugins.

+
+
JavaScript
+ +
planet.loadPlugin(somePlugin);
+planet.loadPlugin(somePluginGenerator());
+

+

For more information on the plugin system and API, please see the Plugins documentation.

+

planet.projection

+

The core of a planet's data model is an d3.geo.projection (specifically, an orthographic projection), which is exposed by a planet by planet.projection. You can use this object to control various aspects of the planet. The D3 documentation covers the methods in considerable detail, so be sure to check it out; many of the examples on this site also use the projection object to operate.

+
+
JavaScript
+ +
planet.projection
+  .scale(width / 2)
+  .rotate([60, -10, 0]);
+

+

planet.path

+

planet.path is a d3.geo.path which uses the planet's internal projection to generate path data for geographical features. Its context method is commonly used by interal plugins to take a canvas context and return a path generator that can be used to draw on the globe.

+
+
JavaScript
+ +
canvasContext.beginPath();
+planet.path.context(canvasContext)(geoFeature);
+canvasContext.fill();
+

+

planet.plugins

+

Planetary.js provides an empty object that plugins may use to store public data and methods. If a plugin is well-behaved, it will keep all its properties on the object under a single key (usually one that share's the plugin's name).

+

planet.canvas and planet.context

+

Once you call draw on a planet instance, Planetary.js will set the canvas and context properties to the canvas and its context, respectively.

+

planet.onInit( function([done]){} )

+

Registers a function to be called when the planet is initialized (which happens after a call to draw and after any loaded plugins have been initialized). This is mostly used by plugins to initialize themselves when the planet "boots."

+

If the provided callback function takes any parameters, it will be a "done" function that must be called once the initialization function finishes any asynchronous work before the planet will continue to initialize.

+
+
JavaScript
+ +
planet.onInit(function() {
+  doSomeSetupStuff();
+});
+
+planet.onInit(function(done) {
+  doSomeAsynchronousSetupStuff(function() {
+    done();
+  });
+});
+

+

planet.onDraw( function(){} )

+

Registers a function to be called each time the globe redraws itself. This is mostly used by plugins to draw plugin-specific data or otherwise animate the globe.

+
+
JavaScript
+ +
planet.onDraw(function() {
+  var rotation = planet.projection.rotate();
+  rotation[0] += 1;
+  if (rotation[0] >= 180) rotation[0] -= 360;
+  planet.projection.rotate(rotation);
+});
+

+

planet.withSavedContext( function(context){} )

+

Calls the function with the current canvas context as a paremter, wrapping the function call in context.save() and context.restore(). Use this function any time you're going to modify the context to ensure it gets put back to the way it was.

+
+
JavaScript
+ +
planet.onDraw(function() {
+  planet.withSavedContext(function(context) {
+    context.beginPath();
+    planet.path.context(context)({type: 'Sphere'});
+    context.fillStyle = config.fill || 'black';
+    context.fill();
+  });
+});
+

+

planet.draw(canvas)

+

Begins drawing the globe onto the given canvas. canvas should be a raw DOM element (e.g. as returned by document.getElementById). Specifically, if it is wrapped by D3 or jQuery, you need to unwrap it with something like wrappedCanvas[0].

+

Calling draw will perform the following operations:

+
    +
  1. Initialize each loaded plugin by calling the plugin function.
    2. +
  2. Set planet.canvas and planet.context to the canvas and the canvas' context, respectively.
    3. +
  3. Run each registered onInit hook in the order it was registered (note that onInit calls made by plugins will not be made until step 1, after draw has been called).
    4. +
  4. Start the animation loop, each tick clearing the canvas and calling any registered onDraw hooks in order.
    5. +
+
+
HTML
+ +
<canvas id='myCanvas' width='123' height='456'></canvas>
+
JavaScript
+ +
var canvas = document.getElementById('myCanvas');
+planet.draw(canvas);
+

+ +
+
+
+ + diff --git a/documentation/plugins.html b/documentation/plugins.html new file mode 100644 index 0000000..6b4a6ab --- /dev/null +++ b/documentation/plugins.html @@ -0,0 +1,121 @@ + + + + Planetary.js + + + + + + + + + + +
+
+ + Planetary.js + + + + Download + + + Examples + + + Documentation + + + Fork on GitHub + +
+
+ + +
+
+
+
+ + Introduction + + + + Core API + + + + Planet API + + + + Plugins + + + + Built-In Plugins + + +
+
+ Earth + TopoJSON + Oceans + Land + Borders + Pings + Zoom + Drag +
+
+
+
+ +
+

Plugins

+

Planetary.js uses a plugin-based architecture, and all the built-in functionality is built using this architecture. This makes Planetary.js extremely flexible.

+

Loading Plugins

+

Plugins are loaded either globally by planetaryjs.loadPlugin or for a specific planet instance by planet.loadPlugin. If you call draw on a planet and it has no plugins loaded at all (from either source), Planetary.js will use the default plugin stack, which consists of the earth and pings plugins.

+

Anatomy of a Plugin

+

A plugin is simply a JavaScript function that takes a planet instance as a parameter and performs some predefined operation. The best plugins do one tiny thing. If you want a plugin to do a lot of things at once, you should build a plugin that wraps other, smaller plugins; in fact, this is exactly how the earth plugin is built. See the Earth documentation for more details.

+

Most of the time, a plugin will implement its behavior by registering callbacks into the planet's lifecycle hooks. For example, the following simple plugin increments the planet's projection's rotation by one degree every tick (this would make for a very fast spinning globe, but demonstrates the idea nicely enough):

+
+
JavaScript
+ +
var autorotate = function(planet) {
+  planet.onDraw(function() {
+    var rotation = planet.projection.rotate();
+    rotation[0] += 1;
+    if (rotation[0] >= 180) rotation[0] -= 360;
+    planet.projection.rotate(rotation);
+  });
+};
+
+planet.loadPlugin(autorotate);
+

+

Plugin Generators

+

Often, you'll want your plugin to be configurable with some user-defined values. You can create a function generator, which is a function that takes your configuration data and then returns the plugin function. You can then call this generator to generate the plugin function for use by loadPlugin.

+
+
JavaScript
+ +
var autorotate = function(degreesPerTick) {
+  return function(planet) {
+    planet.onDraw(function() {
+      var rotation = planet.projection.rotate();
+      rotation[0] += degreesPerTick;
+      if (rotation[0] >= 180) rotation[0] -= 360;
+      planet.projection.rotate(rotation);
+    });
+  };
+};
+
+planet.loadPlugin(autorotate(5));
+

+ +
+
+
+ + diff --git a/index.html b/index.html index 8938187..b51aa3b 100644 --- a/index.html +++ b/index.html @@ -2,35 +2,37 @@ Planetary.js - - - + + + + + + + - - -
-
- - Planetary.js - - - - Download - - - Examples - - - Documentation - - - Fork on GitHub - -
+
+ + Planetary.js + + + + Download + + + Examples + + + Documentation + + + Fork on GitHub +
+
+
@@ -68,7 +70,7 @@
- Or install with Bower:
bower install planetary.js
+ Or install with Bower:
bower install planetary.js
@@ -101,20 +103,20 @@
- + Examples

Check out working examples and see what Planetary.js can do

-

Explore the Examples

+

Explore the Examples

- + Documentation

Download and install Planetary.js and build something awesome

-

Peruse the Documentation

+

Peruse the Documentation

@@ -130,9 +132,11 @@
- - - + + + + +