.. _nhmc: ########### nhmc (root) ########### Most of the Map Center's functionality is contained either in its :ref:`modules ` or in :ref:`packages ` underneath the root ``nhmc`` package, but a handful of important objects are contained at this level for lack of a more approprate place to put them. **************** Graphics objects **************** .. _nhmc.surface: nhmc.surface ============ *Object (instance of dojox.gfx.Surface)* Dojo's graphics library requires the creation of a "surface" object, which provides a rectangular drawing area on which vector images may be created. The ``nhmc.surface`` object always corresponds to that surface for the Map Center, and it is kept to the size of the ``#map`` element on the page. The `Dojo documentation`_ contains more guidance on the functionality of this type of object. .. _Dojo documentation: http://dojotoolkit.org/reference-guide/1.6/dojox/gfx.html#surface ************** Initialization ************** .. _nhmc.mapCenterInit: nhmc.mapCenterInit ================== *Function* ``nhmc.mapCenterInit()`` This function executes as soon as :ref:`nhmc.surface` is loaded. It prepares the application environment for whatever :ref:`module ` is ultimately responsible for the page by performing the following duties: .. _nhmc.mapCenterInit-config_overrides: General configuration overrides ------------------------------- Many general configuration variables (text sizes, default fill colors, etc.) are located in :ref:`nhmc.config`, but sometimes it makes sense to override them. ``nhmc.mapCenterInit`` begins by searching for a global object named ``nhmc_config``; if this object exists, it is merged into ``nhmc.config`` and overwrites any identically named properties. The logic for this deep copy operation is handled by `jQuery.extend`_. .. _jQuery.extend: http://api.jquery.com/jQuery.extend/ .. _nhmc.mapCenterInit-initial_render: Pre-drawing nationwide state map -------------------------------- The nationwide state map (i.e., the U.S. map that just shows state boundaries) is a special case of :ref:`map view ` that, if used, must already be rendered. Because of this, ``nhmc.mapCenterInit`` locates the path data if available, draws the states and adds labels for the especially small ones and then immediately hides all of those objects. This leaves them ready to go in case the user or the :ref:`module ` selects that map view later on. .. _nhmc.mapCenterInit-initial_scale: Setting initial scale factors ----------------------------- The Map Center supports scaling :ref:`map views ` as necessary to fit the width of the ``#map`` element that contains the actual :ref:`map surface `. At this point in the application, no measurements have been taken of the size of ``#map``, so we assume all maps to be rendered at their original size and store the corresponding scale factor of 1 for each possible map name. .. _nhmc.mapCenterInit-signal_bindings: Bind to map initialization signal --------------------------------- The default map view is set with the value of the ``#map_view`` hidden ```` element, which is typically located at the end of the sidebar markup. We kick off the actual rendering process by calling :ref:`nhmc.ctrl.zoomToState` with the initial value of ``#map_view``. Before we do that, however, we listen for the first firing of the :ref:`drawingComplete ` signal. When this signal fires for the first time, we ensure that the map is scaled properly and then fire the :ref:`coreInitialized ` signal to pass execution off to the :ref:`module ` responsible for the rest of the page. .. todo:: There's also an event handler bound to ``#map_view``'s ``change`` event that is most likely implemented incorrectly. In practice, it almost certainly never gets used and probably can be removed, but this should be investigated first. .. _nhmc.mapCenterInit-vestigial_ui: Bind vestigial UI events ------------------------ Toward the beginning of the Map Center's development, we experimented with some UI interactions that would allow for switching between the map view and a large chart of some sort for another view of the information being displayed. (The chart's exact contents would have depended on those of the map, of course.) Because of this, ``nhmc.mapCenterInit`` still binds UI events that that were related to that interaction and a few other testing elements we were using at that time. .. todo:: Consider removing these. .. _nhmc.mapCenterInit-tab_behaviors: Bind general tab behaviors -------------------------- Finally, ``nhmc.mapCenterInit`` binds UI behaviors that actually *are* used--namely, those related to the tabs shown next to the page's ``

`` in most maps (currently all unless they're :ref:`embedded `). There are three main behaviors to know about: * When a tab is selected somehow, assign it the ``.view_tab_active`` class and remove that class from all other tabs. "Selecting" a tab in this context also includes clicking on an option in that tab's child dropdown menu, which is covered next. * When a tab contains a button to show or hide a child dropdown menu, ensure that clicking that button actually shows or hides that menu. This possibility is limited to a maximum of two tabs with specific naming conventions: * One tab called ``#view_tab_more``, with a toggle button called ``#view_tab_more_toggle`` and a child dropdown menu called ``#view_tab_more_menu``, which is most often used for selecting a specific map view. (It's also used in the :ref:`Electoral College calculator ` for selecting a previous election's results to display.) * One tab called ``#view_tab_options_more``, with a toggle button called ``#view_tab_options_more_toggle`` and a child dropdown menu called ``#view_tab_options_more_menu``, which is most often used for selecting a more specific data set (for example, a specific ethnic group in a map of ethnic breakdowns). Event handlers for the options within tabs' dropdown menus are delegated_, so it is possible to add and remove these options after the Map Center core has been initialized. This is done for :ref:`non-primary election results ` to show a list of races to choose from, for example. .. _delegated: http://api.jquery.com/delegate/ * For tabs that contain child dropdown menus, ensure that clicking on the name of the tab toggles the dropdown menu instead of selecting the tab. This was changed after usability testing within the NewsHour (both on mobile and on desktop devices) showed that this was the expected behavior. This is overridden, however, on the :ref:`Electoral College calculator `, where tabs also exist without dropdown menus. *************************************************** Orphans (unused components which should be removed) *************************************************** .. _nhmc.R: nhmc.R ====== *null* Originally used as a reference to the Raphael_ graphics library; unused since switching to Dojo_ in September 2011. Currently set to ``null``. .. _Raphael: http://raphaeljs.com/ .. _Dojo: http://dojotoolkit.org/ .. todo:: Remove this.