.. _modules-static_maps:

###################################
General-purpose static data mapping
###################################

This module drives all data-driven choropleth maps not covered under any of the
other Map Center :ref:`modules <modules>`. It is designed to display
category-based and continuous value-based data for any of the available
:ref:`map types <nhmc.geo>`, and it includes a variety of useful
:ref:`hooks and overrides <modules-static_maps-configuration_options>` in order
to be more useful for creating variations on these types of maps relatively
quickly.

This module lives in ``lib/map_center/modules/static_maps.js``, and the current
data sets used with it live in ``lib/map_center/modules/static_maps_data/`` by
convention.


.. _modules-static_maps-operation:

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

A page making use of this module must include one additional JavaScript file
containing the data to display. As described above, this file should live in
``lib/map_center/modules/static_maps_data/``. That file should define one
global variable, ``nhmcStatic``, with a format described
:ref:`below <modules-static_maps-data_structure>`.

Depending on whether the page is intended to show one or multiple data sets,
the user may have one or two :ref:`tabs <ui-tabs>` available; the one that is
always available allows the user to select a specific
:ref:`map view <nhmc.geo>`, and the one that is available in the case of
multiple data sets allows the user to select a specific data set to view.

In either case, the states or counties on the map are colored according to the
data provided. The :ref:`sidebar <ui-sidebars>` in this module shows the
meaning of each color used on the map, and the :ref:`tooltips <nhmc.tooltips>`
for each state or county shows the specific data value that caused that state
or county to receive the color it has.


.. _modules-static_maps-configuration_options:

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

There are three major configuration options that exist outside the
:ref:`data file itself <modules-static_maps-data_structure>`, all changeable
via global variables:

* ``nhmcStaticBreakFormatter`` is a function used for rendering the
  :ref:`sidebar <ui-sidebars>` entries for each color shown on the map when the
  data set shown uses
  :ref:`continuous values <modules-static_maps-data_structure-continuous>`. It
  accepts six arguments:
  
  * ``thisBreak`` is the break value for this particular sidebar entry.
  * ``prevBreak`` is either ``null`` or the break value for the sidebar entry
    before this one.
  * ``isLastBreak`` lets the formatter function know this is the last break
    value to be included in the sidebar.
  * ``breakPrefix`` is a string meant to be displayed before a break value.
    This often is used for currency signs.
  * ``breakSuffix`` is a string meant to be displayed after a break value. This
    often is used for units (points, percent, etc.).
  * ``breakDecimals`` is an integer requesting that a break value be rounded to
    a specific number of decimal places; for example, small dollar amounts
    might have ``breakDecimals`` set to ``2`` to properly show a number of
    cents.
  
  By default, this function renders the sidebar as a list of ranges from one
  break to the next. This function will execute every time the map view is
  changed.

* ``nhmcStaticFlyouts`` is an object that determines whether
  :ref:`tooltips <nhmc.tooltips>` should be rendered as
  :ref:`flyouts <ui-flyouts>`. No specific properties need to be defined in
  this object for flyouts to be enabled; the object just needs to exist. By
  convention, though, to enable flyouts, the following value is used:
  
  .. code-block:: javascript
     
     var nhmcStaticFlyouts = {
         enabled: true
     };
  
  Other properties that get merged with those provided in this object are:
  
  * ``corner`` was intended to be a string value setting a position for the
    flyout (or ``null`` if flyouts should not be used), but now positioning is
    entirely handled in CSS, so this option should be considered deprecated.
  * ``strokeHighlight`` is a hexadecimal color code for the color used to
    outline the state or county targeted by the tooltip.
  * ``width`` is a number stating the number of pixels wide to render the
    flyout. (This was here in order to support certain animations.) Positioning
    and formatting are entirely handled in CSS now, so this option should be
    considered deprecated.

* ``nhmcStaticTooltipFormatter`` is a function used for rendering the content
  of the :ref:`tooltips <nhmc.tooltips>` corresponding to each state or county
  on the map. It accepts five arguments:
  
  * ``thisFIPS`` is a :ref:`county FIPS code <nhmc.config-fips>` if the tooltip
    should show data for a county or an empty string if it should show data for
    a state.
  * ``thisState`` is a full state name for the area for which the tooltip
    should show data. This is included whether the area is a county or a state
    (since counties *do* exist within states); therefore,
    ``nhmcStaticTooltipFormatter`` should check the values of the ``thisFIPS``
    and ``thisCounty`` arguments to determine the type of area being touched or
    hovered over.
  * ``thisCounty`` is a full county name if the tooltip should show data for a
    county or an empty string if it should show data for a state.
  * ``countyOnly`` is a Boolean value that, if true, requests that the tooltip
    show just the name of the county being touched or hovered over as opposed
    to the name of the county *and* the name of that county's state (e.g.,
    ``Arlington County`` or ``Arlington County, Virginia`` if ``countyOnly`` is
    ``true`` or ``false`` respectively).
  * ``currentData`` is the full data set being displayed (as described in
    :ref:`modules-static_maps-data_structure` below).
  
  This function will execute every time a tooltip is created, but not while
  that tooltip simply updates its position within the same state or county.

One additional configuration option exists:

* ``nhmcStaticDataIndex`` is an integer with the same interpretation as the
  `data_index` parameter in the
  :ref:`fragment identifier <modules-static_maps-fragment_identifier>`. It will
  be ignored if the `data_index` fragment parameter is set.


.. _modules-static_maps-data_structure:

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

Two types of data sets can be displayed in a map using this module:

* *Category-based* data sets place states and counties in any of a number of
  categories and color areas that are in the same category with the same color.
* *Continuous value-based* data set assign a value to each state and/or county
  and color those areas based on which of a number of ranges of values happen
  to include the areas' values.

As described in :ref:`modules-static_maps-operation` above, any page using this
module must include a JavaScript file (or ``<script>`` block) that defines a
variable named ``nhmcStatic``. For a page that uses only one data set,
``nhmcStatic`` should be an object with the properties listed in either
:ref:`modules-static_maps-data_structure-categories` or
:ref:`modules-static_maps-data_structure-continuous` below; for a page that
uses multiple data sets, ``nhmcStatic`` should be an array of such objects.

.. note::
   In both of the description sections below, the term "area name" refers to
   :ref:`FIPS codes <nhmc.config-fips>` for counties and full state names for
   states.

.. _modules-static_maps-data_structure-categories:

Categories
==========

A data set object for category-based data must contain the following three
properties:

* ``categories`` is an array of strings containing the names of the categories
  to use in the data set, listed in the order they should be displayed in the
  sidebar.
* ``colors`` is an object with category names (as listed in ``categories``) as
  keys and hexadecimal color codes as values. These colors will be used to fill
  areas that fall in each category and will be shown next to each category's
  name in the sidebar.
* ``areaLists`` is an object with category names (as listed in ``categories``)
  as keys and arrays of area names as values. Each array should contain the
  names of all states and the FIPS codes of all counties that fall in that
  category. Any states or counties that are unlisted in all area lists will
  remain their default fill color as defined in
  :ref:`nhmc.config.defaultAttributes`.

.. seealso::
   For an example of a category-based data set, check out the Patchwork Nation
   categories map. The page source is located at ``patchwork_types.html``, and
   the data set source is located at
   ``lib/map_center/modules/static_maps_data/patchwork_types.js``.

.. _modules-static_maps-data_structure-continuous:

Continuous values
=================

A data set object for continuous value-based data must contain the following
three properties:

* ``breaks`` is an array of numbers that represent the greatest value in each
  group of areas that should be colored identically. The last value in
  ``breaks`` should be at least as great as the greatest value in the data set
  and may be greater. (The maximum possible value is a good default, such as
  100 for percentages.)
  
  For example, if you are mapping a data set with values ranging from 0 to 100 and want to split it up into five equally spaced groups of 20 each:
  
  .. code-block:: javascript
     
     "breaks": [20, 40, 60, 80, 100]
  
  This will define groups of:
  
  * 0 to 20 (rendered by default in the sidebar as ``≤20``)
  * 20 to 40
  * 40 to 60
  * 60 to 80
  * 80 to 100 (rendered by default in the sidebar as ``>80``)

* ``colors`` is an array of hexadecimal color codes in the same order as in
  ``breaks``. Continuing the previous example:
  
  .. code-block:: javascript
     
     "colors": ["#000000", "#ffffff", "#ff0000", "#00ff00", "#0000ff"]
  
  would assign the color ``#ff0000`` to the ``40 to 60`` group.

* ``areas`` is an object with area names as keys and data points (numbers that
  fall in the ranges defined in ``breaks``) as values. Continuing the previous
  example:
  
  .. code-block:: javascript
     
     "areas": {
         "Missouri": 75
     }
  
  would fill the state of Missouri with ``#00ff00`` (since it falls in the
  ``60 to 80`` range).

It also may contain any combination of the following five properties, including
none of them or all of them:

* ``decimalPlaces`` is a number of decimal places to which the breaks and data
  values should be rounded when they're displayed. This defaults to zero, which
  rounds everything to the nearest integer.
* ``prefix`` is a string (defaulting to the empty string) that is prepended to
  the breaks and data values when they're displayed. This is primarily used for
  currency indicators such as the ``$`` before dollar amounts.
* ``suffix`` is a string (defaulting to the empty string) that is appended to
  the breaks and data values when they're displayed. This is primarily used for
  units, including percents.
* ``seriesName`` is a string (defaulting to ``undefined``) which, if defined,
  is used to populate any element with the class ``static_map_name``.
* ``sidebarTitle`` is a string (defaulting to ``undefined``) which, if defined,
  is used to populate the element with the ID ``sidebar_title``.

.. seealso::
   For an example of a continuous value-based data set, check out the
   unemployment rate map. The page source is located at ``unemployment.html``,
   and the data set source is located at
   ``lib/map_center/modules/static_maps_data/unemployment.js``.


.. _modules-static_maps-fragment_identifier:

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

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

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

* ``data_index``, if provided, should be set to the index of the data set to
  display first. This only makes sense if
  :ref:`nhmcStatic <modules-static_maps-data_structure>` is defined as an
  array of objects.
* ``map_view``, if provided, should be set to the name of the map view to
  display first. The fragment identifier will update as the map view is
  changed.