.. _nhmc.geo: ######## nhmc.geo ######## This package contains the source data and the actual graphics objects for map views, including their constituent state or county path objects and any applicable :ref:`city labels `. The contents of this package are primarily used by :ref:`nhmc.ctrl.zoomToState`, which switches between map views. State and county path objects contain ``nhmcData`` attributes with identifying information that might be useful for event handlers interacting with those paths; more details about those objects' properties are provided below. There are three general types of map view currently in use: * The :ref:`nationwide county map ` is a map containing every county and `county-equivalent`_ in the 50 United States and the District of Columbia. "County-equivalent" areas include boroughs in Alaska; parishes in Louisiana; independent cities in Maryland, Missouri, Nevada and Virginia; the District of Columbia; and `census areas`_ in Alaska. .. _county-equivalent: http://en.wikipedia.org/wiki/County-equivalent .. _census areas: http://en.wikipedia.org/wiki/Unorganized_Borough,_Alaska * The :ref:`nationwide state map ` is a map containing all 50 states and the District of Columbia. * The :ref:`statewide county maps ` are maps of each of the 50 states and the District of Columbia. Each state map (and the DC map) contains all of the county-equivalents in that state and can contain :ref:`city labels ` for important metropolitan areas in that state. .. todo:: The entire map view system should be refactored to work in a common way to avoid some of the complications resulting from having three different kinds of map. Part of a prototype implementation of this exists but still needs to be incorporated into the current version of the Map Center. .. _nhmc.geo-nationwide_county: ********************* Nationwide county map ********************* The nationwide county map consists of one basic type of object: county paths. This map is identified by the view name (also referred to in some contexts as the "state" name) ``us_counties``. Each county and county-equivalent in this map is identified by its five-digit FIPS code as found in :ref:`nhmc.config.FIPSToCounty `. For example, the raw path string corresponding to Arlington County, Va., which has a FIPS code of ``51013``, is located at ``nhmc.geo.allCounties["51013"]``. .. important:: If you intend to use this map view in a Map Center page, you must include ``lib/maps/all_counties.js`` in the document ````. In theory, any other JavaScript file with the appropriate structure could be used, though, which could be useful for making modifications to this view for the purposes of a specific :ref:`module `. For example, a different version of this map view is included in the map of `2008 general election results`_ to reflect the fact that Alaska results were reported by state House district instead of by county; that version of ``all_counties.js`` is available at ``lib/map_center/modules/static_maps_data/08general-all_counties.js``. .. _2008 general election results: http://www.pbs.org/newshour/vote2012/map/08general.html .. _nhmc.geo.allCounties: nhmc.geo.allCounties ==================== *Object (values are strings)* This object has county FIPS codes as keys and raw SVG_ path strings as values. These strings theoretically could be included as the ``d`` attribute of an SVG ``path`` element and properly represent the counties' desired shape. (In fact, these path strings were taken directly from such attributes; all current Map Center views existed first as standard SVG images.) .. _SVG: http://en.wikipedia.org/wiki/Scalable_Vector_Graphics .. _nhmc.geo.countyGeo: nhmc.geo.countyGeo ================== *Object (values are instances of dojox.gfx.path.Path)* This object has keys of county FIPS codes and values of `Dojo path objects`_ corresponding to the actual image components representing the counties. It is generated directly from the path strings found in :ref:`nhmc.geo.allCounties`. .. _Dojo path objects: http://dojotoolkit.org/api/1.6/dojox/gfx/path/Path Each county path object also includes an ``nhmcData`` object to help event handlers identify the county when needed. ``nhmc.geo.countyGeo[foo].nhmcData`` contains one property, ``county_fips``, with a value of the county's FIPS code as found in :ref:`nhmc.config.FIPSToCounty `. .. _nhmc.geo-nationwide_state: ******************** Nationwide state map ******************** The nationwide state map consists of two basic types of object: state paths and labels for some smaller states. This map is initially rendered directly by :ref:`nhmc.mapCenterInit` and is identified by the view name (also referred to in some contexts as the "state" name) ``us_all``. The objects making up the nationwide state map live in ``nhmc.geo.usGeo`` under the key corresponding to the state's full name as found in :ref:`nhmc.config.stateToUSPS `, represented as ``foo`` in the headings below. For example, the raw SVG_ path string for North Carolina is located at ``nhmc.geo.usGeo["North Carolina"].state``. .. _SVG: http://en.wikipedia.org/wiki/Scalable_Vector_Graphics .. important:: If you intend to use this map view in a Map Center page, you should include ``lib/maps/states_only.js`` in the document ````. In theory, any other JavaScript file with the appropriate structure could be used, though, which could be useful for making modifications to this view for the purposes of a specific :ref:`module `. .. _nhmc.geo.usGeo-state: nhmc.geo.usGeo[foo].state ========================= *String* This property is the raw SVG_ path string for the state ``foo``; that is, this string theoretically could be included as the ``d`` attribute of an SVG ``path`` element and properly represent the state's desired shape. (In fact, these path strings were taken directly from such attributes; all current Map Center views existed first as standard SVG images.) .. _SVG: http://en.wikipedia.org/wiki/Scalable_Vector_Graphics .. _nhmc.geo.usGeo-statePath: nhmc.geo.usGeo[foo].statePath ============================= *Object (instance of dojox.gfx.path.Path)* This property is a `Dojo path object`_ corresponding to the actual image component representing the state ``foo``. It is generated directly from the path string found in :ref:`nhmc.geo.usGeo[foo].state `. .. _Dojo path object: http://dojotoolkit.org/api/1.6/dojox/gfx/path/Path This object also includes an ``nhmcData`` object to help event handlers identify the state when needed. ``nhmc.geo.usGeo[foo].statePath.nhmcData`` contains one property, ``state``, with a value of the state's full name as found in :ref:`nhmc.config.stateToUSPS `. .. _nhmc.geo.usGeo-label: nhmc.geo.usGeo[foo].label ========================= *Object (instance of dojox.gfx.shape.Text)* This property is only used for a handful of East Coast states and is a `Dojo text object`_ corresponding to a label for that state. .. _Dojo text object: http://dojotoolkit.org/api/1.6/dojox/gfx/shape/Text .. _nhmc.geo-statewide_county: ********************* Statewide county maps ********************* Statewide county maps are an interesting case because there are so many of them; all maps other than the two mentioned above are considered statewide county maps. Each statewide county map consists of two basic types of object: county paths and city labels. Each map is identified by a view name (also referred to in some contexts as the "state" name) corresponding to the all-lowercase version of its state abbreviation as found in :ref:`nhmc.config.USPSToState `. The objects making up each statewide county map live in ``nhmc.geo.usGeo`` under the key corresponding to the state's full name as found in :ref:`nhmc.config.stateToUSPS `, represented as ``foo`` in the headings below. For example, the Dojo group object corresponding to the city label for Jefferson City, Mo., is located at ``nhmc.geo.usGeo["Missouri"].cityPaths["Jefferson City"]``. In order to keep users from having to download all map views' path data at once whenever loading a Map Center page, :ref:`nhmc.ctrl.zoomToState` makes AJAX (technically JSONP) requests to obtain the data for a specific statewide county map the first time it is needed for a given pageview. The JSONP file for each map view is located at ``http://s3.amazonaws.com/newshourroot/nhmc_geo_json/VIEW_NAME.json``, where ``VIEW_NAME`` is the view name mentioned earlier in this section. Cities ====== .. _nhmc.geo.usGeo-cities: nhmc.geo.usGeo[foo].cities -------------------------- *Object (values are arrays)* This object has city names as keys and city location arrays as values. The format of those arrays is described more in detail in the documentation for :ref:`nhmc.ctrl.addCity`. .. _nhmc.geo.usGeo-cityPaths: nhmc.geo.usGeo[foo].cityPaths ----------------------------- *Object (values are instances of dojox.gfx.shape.Container)* This object has city names as keys and `Dojo group objects`_ as values. Each of those groups contains the components of the labels for the cities defined in :ref:`nhmc.geo.usGeo[foo].cities `, which provides the source data used to generate this object. .. _Dojo group objects: http://dojotoolkit.org/api/1.6/dojox/gfx/shape/Container Counties ======== .. _nhmc.geo.usGeo-counties: nhmc.geo.usGeo[foo].counties ---------------------------- *Object (values are strings)* This object has full county names (as found in :ref:`nhmc.config.CountyToFIPS[foo] ` as keys and raw SVG_ path strings as values. These strings theoretically could be included as the ``d`` attribute of an SVG ``path`` element and properly represent the counties' desired shape. (In fact, these path strings were taken directly from such attributes; all current Map Center views existed first as standard SVG images.) .. _SVG: http://en.wikipedia.org/wiki/Scalable_Vector_Graphics For example, the path string corresponding to Dane County, Wis., is located at ``nhmc.geo.usGeo["Wisconsin"].counties["Dane County"]``. .. _nhmc.geo.usGeo-countyPaths: nhmc.geo.usGeo[foo].countyPaths ------------------------------- *Object (values are instances of dojox.gfx.path.Path)* This object has keys of full county names and values of `Dojo path objects`_ corresponding to the actual image components representing the counties. It is generated directly from the path strings found in :ref:`nhmc.geo.usGeo[foo].counties `. .. _Dojo path objects: http://dojotoolkit.org/api/1.6/dojox/gfx/path/Path Each county path object also includes an ``nhmcData`` object to help event handlers identify the county when needed. ``nhmc.geo.usGeo[foo].counties[bar].nhmcData`` contains one property, ``county``, with a value of the county's full name as found in :ref:`nhmc.config.CountyToFIPS[foo] `.