.. _modules-governors:

#####################################
Incumbent governors' election results
#####################################

This module allows users to view the results of the elections that put each
state's incumbent governor in office.

This module lives in ``lib/map_center/modules/governors.js``.

.. note::
   This currently only includes data from Wisconsin due to deadline pressures
   involved with that state's `recall election`_. The other states will be
   added later.
   
   .. _recall election: http://en.wikipedia.org/wiki/Wisconsin_gubernatorial_recall_election,_2012

.. todo::
   Add support for viewing a
   :ref:`nationwide state map <nhmc.geo-nationwide_state>` with incumbent
   governors' party affiliations and support for clicking a state to view that
   state's election results.


.. _modules-governors-operation:

*********
Operation
*********

The one :ref:`tab <ui-tabs>` available in this module allows users to select a
state in order to view the county-level results of the most recent election
that elected that state's incumbent governor (i.e., not including recall
efforts that governor survived).

The :ref:`sidebar <ui-sidebars>` in this module shows the statewide vote
breakdown in the race, and the :ref:`tooltips <nhmc.tooltips>` for each county
shows the countywide vote breakdown in the race.


.. _modules-governors-configuration_options:

*********************
Configuration options
*********************

All configuration options live in the ``config`` object toward the top of the
module source and may be overridden by defining a global object named
``nhmcGovernorsConfig``, which will be merged into ``config`` using
`jQuery.extend`_.

.. _jQuery.extend: http://api.jquery.com/jQuery.extend/

.. _config.bigCandidates:

* ``bigCandidates`` is an integer defining the number of candidates in the
  sidebar that will have large legend entries including their photo and large
  vote percents as opposed to smaller, more compact legend entries.

.. _config.partyColors:

* ``partyColors`` is an object with party abbreviation letters (``D``, ``R`` or
  ``O``) as keys and hexadecimal color codes as values.

.. _config.candidateImages:

* ``candidateImages`` is an object with candidate names as keys and headshot
  image URLs as values.

.. _config.flyoutsEnabled:

* ``flyoutsEnabled`` is a Boolean value stating whether tooltips should be
  rendered as :ref:`flyouts <ui-flyouts>`, which is only done for broadcast.

.. _config.strokeHighlight:

* ``strokeHighlight`` is a hexadecimal color code used when
  `config.flyoutsEnabled`_ is true; when that option is enabled, this color is
  used to outline the county targeted by the tooltip.

.. _config.tooltipsEnabled:

* ``tooltipsEnabled`` is a Boolean value stating whether tooltips with
  countywide vote totals should be enabled at all.


.. _modules-governors-data_structure:

**************
Data structure
**************

The data driving this module is located in an object called ``resultsData``
toward the top of the module source. It has capitalized state abbreviations as
found in :ref:`nhmc.config.USPSToState <nhmc.config-usps>` as keys and objects
as values. In each state's object:

* ``areas`` is an object with :ref:`county FIPS codes <nhmc.config-fips>` as
  keys and arrays as values. Each array contains one two-element array per
  candidate: The first element is the candidate ID listed in ``candidates``,
  and the second element is the number of votes that candidate received. The
  county's array is sorted by the number of votes received in descending order;
  that is, the candidate with the most votes in that county is listed first.

* ``breakdown`` is an array identical in format to the county arrays in
  ``areas`` but with results for the entire state.

* ``candidates`` is an object with candidate IDs as keys and candidate names as
  values. This allows the data in ``areas``, ``breakdown`` and ``parties`` to
  use the more compact candidate IDs instead of candidate names to save space.
  
  .. note::
     All configuration options use candidates' names, not their IDs. IDs should
     not be used with any other modules; they are arbitrarily assigned to
     candidates.

* ``electionYear`` is a string with the year the election described took place.

* ``parties`` is an object with candidate IDs as keys and party abbreviation
  letters (corresponding to the keys in `config.partyColors`_) as values.


.. _modules-governors-fragment_identifier:

*******************
Fragment identifier
*******************

This module makes use of one key-value pair in the `fragment identifier`_ via
:ref:`nhmc.ctrl.hashParams`:

.. _fragment identifier: http://en.wikipedia.org/wiki/Fragment_identifier

* ``map_view``, if provided, should be set to the view name of the state to
  display first. The fragment identifier will update as the map view is
  changed.