nhmc (root)

Most of the Map Center’s functionality is contained either in its modules or in 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

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.

Initialization

nhmc.mapCenterInit

Function

nhmc.mapCenterInit()

This function executes as soon as nhmc.surface is loaded. It prepares the application environment for whatever module is ultimately responsible for the page by performing the following duties:

General configuration overrides

Many general configuration variables (text sizes, default fill colors, etc.) are located in 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.

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 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 module selects that map view later on.

Setting initial scale factors

The Map Center supports scaling map views as necessary to fit the width of the #map element that contains the actual 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.

Bind to map initialization signal

The default map view is set with the value of the #map_view hidden <input> element, which is typically located at the end of the sidebar markup. We kick off the actual rendering process by calling nhmc.ctrl.zoomToState with the initial value of #map_view.

Before we do that, however, we listen for the first firing of the drawingComplete signal. When this signal fires for the first time, we ensure that the map is scaled properly and then fire the coreInitialized signal to pass execution off to the 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.

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.

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 <h1> in most maps (currently all unless they’re 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 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 non-primary election results to show a list of races to choose from, for example.

• 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 Electoral College calculator, where tabs also exist without dropdown menus.

Orphans (unused components which should be removed)

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.

Todo

Remove this.