.. _modules:

################
Module reference
################

Individual Map Center pages often make use of additional functionality that
isn't included in the core :ref:`nhmc <nhmc>` package; without such additional
functionality, all that would appear is a blank map! The Map Center implements
these extras in the form of "modules", which are simply JavaScript functions
that are executed when the :ref:`coreInitialized <signals-coreInitialized>`
signal fires.

The general organization of a module consists of:

* Declaring which core :ref:`packages <packages>` are in use by calling the
  `namespace function`_.
* Defining an handler for the ``coreInitialized`` signal. This signal should
  only fire once, but existing modules tend to bind to it using
  ``$(document).one()`` for additional safety.
  
  The body of that handler generally includes:
  
  * Any module-specific data to display or global-ish (within the scope of the
    handler) objects for intermediate storage of the module's state.
  * Configuration options.
  * Utility functions to handle different calculation or rendering tasks that
    will be needed.
  * Binding of :ref:`UI <ui>` event handlers.
  * Initialization of the module.

.. _namespace function: http://blogger.ziesemer.com/2008/05/javascript-namespace-function.html

A simple stub module might look something like this:

.. code-block:: javascript
   
   namespace("nhmc");
   namespace("nhmc.charts");
   namespace("nhmc.cleanup");
   namespace("nhmc.config");
   namespace("nhmc.ctrl");
   namespace("nhmc.geo");
   namespace("nhmc.tooltips");
   $(document).one('coreInitialized', function() {
       // Module body goes here.
   });

Modules:

.. toctree::
   :maxdepth: 1
   
   electoral_college
   governors
   live
   other_votes
   static_maps