.. _modules-other_votes: ############################ Non-primary election results ############################ This module allows users to view the results of elections other than Republican presidential primaries. This module lives in ``lib/map_center/modules/other_votes.js``. .. _modules-other_votes-operation: ********* Operation ********* Two :ref:`tabs ` are available to the user; one allows the user to select a state for which to view results, and the other allows the user to select a specific race in that state. The :ref:`sidebar ` in this module shows the statewide vote breakdown in the race, and the :ref:`tooltips ` for each county shows the countywide vote breakdown in the race. If `config.autoRefresh`_ is ``true``, the map will request and display updated results every `config.autoRefreshDelay`_ milliseconds. This does not require a full page refresh. Results in this module are provided by the Associated Press' `AP Election Services`_. .. _AP Election Services: http://www.ap.org/products-services/new-media .. _modules-other_votes-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 ``nhmc_live_config``, which will be merged into ``config`` using `jQuery.extend`_. .. _jQuery.extend: http://api.jquery.com/jQuery.extend/ .. _config.autoRefresh: * ``autoRefresh`` is a Boolean value stating whether the map should periodically request and display updated results. This is useful on election night to keep users from having to manually refresh the page to view updated results. .. _config.autoRefreshDelay: * ``autoRefreshDelay`` is a number stating the number of milliseconds to wait between requests for updated results. This is ignored if `config.autoRefresh`_ is ``false``. .. _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.blankMap: * ``blankMap`` is a Boolean value stating whether to force the map to have all counties uncolored. This was used in one broadcast segment that used :ref:`another module `, and this functionality still exists in this one since it was based on that other module. .. _config.candidateColors: * ``candidateColors`` is an object with candidate names as keys and hexadecimal color codes as values for colors to represent them on the map. .. _config.candidateImages: * ``candidateImages`` is an object with candidate names as keys and headshot image URLs as values. .. _config.condenseCandidates: * ``condenseCandidates`` is a Boolean value stating whether to restrict the list of candidates to those named in ``showCandidates`` and group all others under an "Other" entry. .. _config.defaultRaceNames: * ``defaultRaceNames`` is an empty object that is completely unused. It has no mention anywhere in the module source except in the initial definition of the ``config`` object. .. todo:: Remove this. .. _config.flyoutsEnabled: * ``flyoutsEnabled`` is a Boolean value stating whether tooltips should be rendered as :ref:`flyouts `, which is only done for broadcast. .. _config.friendlyRaceNames: * ``friendlyRaceNames`` is an object with race names as listed in the :ref:`state results file ` as keys and race names as the :ref:`module ` developer would prefer them to be displayed as values. These should be short in order to fit within the space available in the :ref:`race selection tab `. .. _config.randomColors: * ``randomColors`` is an array of hexadecimal color codes from which candidates' colors will be selected for counties they're winning and their sidebar legend entries. A candidate's color is determined first by the candidate-specific color listed in `config.candidateColors`_ if one exists or by the first unused color in ``config.randomColors`` otherwise. .. _config.showCandidates: * ``showCandidates`` is an array of candidate names to show when `config.condenseCandidates`_ is true. .. _config.showRaces: * ``showRaces`` is an array of names of races that are allowed to be displayed. If this is empty (as it is by default), all available races may be displayed. The names in this array should be the race names as provided in the :ref:`state results file `, *not* the alternative race names potentially defined in `config.friendlyRaceNames`_. .. _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-other_votes-data_structure: ************** Data structure ************** The results data for each state lives in a static JSONP_ file at ``http://www.pbs.org/newshour/vote2012/map/live_data/VIEW_NAME_general.json``, where ``VIEW_NAME`` is the state's abbreviation as found in :ref:`nhmc.config.stateToUSPS `, lowercased. The file's callback name is the same abbreviation, but the name there is uppercased; this was done to avoid conflicts with the lowercase abbreviation ``in`` for the state of Indiana, which happens to be a `reserved word`_ in JavaScript. .. _JSONP: http://en.wikipedia.org/wiki/JSONP .. _reserved word: https://developer.mozilla.org/en/JavaScript/Reference/Reserved_Words Each state's results object contains the following properties: * ``candidates`` is an object with candidate IDs as keys and candidate names as values. This allows the data in ``areas``, ``breakdown``, ``colors``, ``images`` and ``winners`` 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; AP Election Services arbitrarily assigns them to candidates and may use different IDs from state to state for the same candidate. * ``lastUpdated`` is an array containing five elements describing the date and time (in the `Eastern time zone`_, including `Daylight Saving Time`_ if in effect) when this results file was last updated. .. _Eastern time zone: http://en.wikipedia.org/wiki/Eastern_Time_Zone .. _Daylight Saving Time: http://en.wikipedia.org/wiki/Daylight_saving_time_in_the_United_States * ``raceNames`` is an object with race IDs as keys and race names as values. This allows the data in ``racees`` to use the more compact race IDs instead of race names to save space. .. note:: All configuration options use races' names, not their IDs. IDs should not be used with any other modules; AP Election Services arbitrarily assigns them to races and may use different IDs from state to state for races for the same (i.e., federal) position. * ``races`` is an object with race IDs as keys and race results objects as values. Each race results object has the following properties: * ``areas`` is an object with area IDs as keys and objects with area results as values. .. note:: For the purposes of this module, an "area ID" is generally a :ref:`county FIPS code `; for non-county areas (such as states), the full name of the area is used instead. Each area's results object contains the following properties: * ``data`` is an array that 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 area's array is sorted by the number of votes received in descending order; that is, the candidate with the most votes in that area is listed first. * ``precincts`` is an array containing two elements: * The first is the number of precincts reporting in the area. * The second is the total number of precincts in the area. These may be used to calculate the percent of precincts reporting. .. warning:: Rounding errors become significant once more than 99 percent of precincts are reporting; module developers should ensure they do not erroneously report 100 percent of precincts reporting before that is actually the case. (This is primarily an issue when rounding to the nearest integer.) * ``breakdown`` is an array identical in format to the county ``data`` objects in ``areas`` but with results for the entire state. * ``precincts`` is an array containing two elements: * The first is the number of precincts reporting statewide. * The second is the total number of precincts statewide. These may be used to calculate the percent of precincts reporting. .. warning:: Rounding errors become significant once more than 99 percent of precincts are reporting; module developers should ensure they do not erroneously report 100 percent of precincts reporting before that is actually the case. (This is primarily an issue when rounding to the nearest integer.) * ``winners`` is an object with area IDs as keys. For each area ID, the value is either the candidate ID for the winner projected by AP or ``null`` if no such projection has yet occurred. * ``test`` is a Boolean value stating whether AP Election Services marked any of the data used to generate this results file as being test data not intended for publication. .. todo:: Add some support for specifying the location of race-specific results files to allow for viewing archived results from past races in states that have held other races since then. .. _modules-other_votes-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.