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.

Operation

Two 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 sidebar in this module shows the statewide vote breakdown in the race, and the 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.

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.

• 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.

• autoRefreshDelay is a number stating the number of milliseconds to wait between requests for updated results. This is ignored if config.autoRefresh is false.

• 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.

• 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 another module, and this functionality still exists in this one since it was based on that other module.

• candidateColors is an object with candidate names as keys and hexadecimal color codes as values for colors to represent them on the map.

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

• 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.

• 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.

• flyoutsEnabled is a Boolean value stating whether tooltips should be rendered as flyouts, which is only done for broadcast.

• friendlyRaceNames is an object with race names as listed in the state results file as keys and race names as the module developer would prefer them to be displayed as values. These should be short in order to fit within the space available in the race selection tab.

• 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.

• showCandidates is an array of candidate names to show when config.condenseCandidates is true.

• 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 state results file, not the alternative race names potentially defined in config.friendlyRaceNames.

• 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.

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

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 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.

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.

• 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 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.

Fragment identifier

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

• 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.