.. _principles:

#######################
Principles of operation
#######################

The Map Center is designed to be a system for rapid (up to near-real-time)
generation of browser-based vector choropleth maps related to the 2012 state
and federal election cycle.

*************
Compatibility
*************

The Map Center officially supports (i.e., is specifically tested on) the latest
versions of Firefox, Chrome and Mobile Safari as well as Internet Explorer 8
and later. More generally, it should be compatible with any relatively modern
browser that supports SVG_, including Android 3.0; Android 2.x devices are
considered partially compatible due to a canvas_ fallback that does not support
events on shapes on the canvas.

.. _SVG: http://en.wikipedia.org/wiki/Scalable_Vector_Graphics
.. _canvas: http://en.wikipedia.org/wiki/Canvas_element

There is a particular emphasis on planning for touch events and supporting
Mobile Safari on the iPad in particular since an iPad 2 (using
`HDMI mirroring`_ and eventually feeding into the WETA_ control room) is used
to manipulate the Map Center on the air.

.. _HDMI mirroring: http://store.apple.com/us/product/MD098ZM/A
.. _WETA: http://www.weta.org/


**********
Components
**********

We use jQuery_ for most of our client-side heavy lifting, including handling
AJAX (technically JSONP_) requests, :ref:`UI <ui>` events and animations.
`jQuery UI`_ is used for specific widgets -- primarily dialog boxes.
Highcharts_ handles our occasional charting needs (currently just in the
:ref:`Electoral College module <modules-electoral_college>`), and Dojo_ gets
brought in for its `vector graphics library`_. We use Modernizr_ to determine
whether users are on touch-capable devices.

.. _jQuery: http://jquery.com/
.. _JSONP: http://en.wikipedia.org/wiki/JSONP
.. _jQuery UI: http://jqueryui.com/
.. _Highcharts: http://www.highcharts.com/
.. _Dojo: http://dojotoolkit.org/
.. _vector graphics library: http://dojotoolkit.org/reference-guide/1.6/dojox/gfx.html
.. _Modernizr: http://modernizr.com/

The core Map Center code handles the rest of the basics--drawing, coloring and
clearing map areas (e.g., counties and states), adding city labels where
necessary, positioning tooltips on map areas, binding common
:ref:`UI behaviors <ui>` and passing execution off to a specific Map Center
:ref:`module <modules>`.


**************
Execution flow
**************

`When the DOM is ready`_, we load Dojo's `graphics library`_ and prepare a
`surface`_ object on the ``#map`` element. This surface object is exposed as
:ref:`nhmc.surface` and is the area on which all map vector graphics will be
drawn.

.. _When the DOM is ready: http://api.jquery.com/ready/
.. _graphics library: http://dojotoolkit.org/reference-guide/1.6/dojox/gfx.html
.. _surface: http://dojotoolkit.org/reference-guide/1.6/dojox/gfx.html#surface

Once that surface is ready, we initialize the rest of the Map Center core in
:ref:`nhmc.mapCenterInit`. That function is described more fully in
:ref:`its own documentation <nhmc.mapCenterInit>`, but overall, it does the
following:

* Renders the initial nationwide state map if provided.
* Binds specific map-drawing event handlers.
* Shows the default map view on the page, as defined in the ``#map_view``
  hidden ``<input>`` element (generally included at the bottom of the sidebar).
* Binds a few outdated UI behaviors (used in initial testing but referring to
  elements which are currently omitted).
* Binds general UI behaviors for the :ref:`tabs <ui-tabs>` that are included in
  most modules.

When the initial render of the map is finished, the
:ref:`drawingComplete <signals-drawingComplete>` signal fires (which happens
any time a map view is finished rendering), which in turn fires (this one time
only) the :ref:`coreInitialized <signals-coreInitialized>` signal to pass
execution off to whatever :ref:`module <modules>` is responsible for the page.
(All modules ultimately consist of an event handler that is bound to
:ref:`coreInitialized <signals-coreInitialized>`.)