.. _ui:

##############
User interface
##############

The Map Center includes a variety of user interface items that aim to keep the
user experience relatively consistent across pages and across modules. Some of
these are missing in :ref:`embedded maps <embed>`, but other pages should
include these as needed.

We use `jQuery UI`_'s Overcast_ theme as a base for items that make use of
jQuery UI; right now, that just includes :ref:`dialog boxes <ui-dialog_boxes>`.

.. _jQuery UI: http://jqueryui.com/
.. _Overcast: http://bit.ly/LipBe6


.. _ui-broadcast_maps:

**************
Broadcast maps
**************

We keep broadcast-ready versions of all of our maps that omit several of the
page features that normally surround Map Center pages, such as site navigation
and featured politics stories. The main markup parts of these maps (everything
inside ``#view_info`` and ``#content_area``) should almost always be the same,
though. Usually there are some additional styles applied to change text sizes
and/or reposition elements to make them more readable on air.


.. _ui-dialog_boxes:

************
Dialog boxes
************

These are standard jQuery UI `dialog boxes`_. When creating these, be sure to
add them to :ref:`nhmc.cleanup.futureGarbage` and
:ref:`nhmc.cleanup.activeDialogs` so the appropriate cleanup routines know
about them for later.

.. _dialog boxes: http://jqueryui.com/demos/dialog/


.. _ui-map_page_selection:

******************
Map page selection
******************

Toward the top of each Map Center page is a ``#nav_outermost`` element that contains all of the containers needed for the user to select the page they want to view. This is handled outside of the Map Center core by the standalone JavaScript file ``lib/map_center/navigation.js``, which takes care of all of the event bindings and populates the navigation's ``#nav_container`` with an option for every page listed in that JS file's ``navObjects`` array. Each object in ``navObjects`` should contain four properties:

* ``featured`` is a Boolean value that, if ``true``, will color the navigation
  option differently as a way to make it stand out. This should only be
  ``true`` for one item at a time.
* ``title`` is a string with the text of the navigation option.
* ``href`` is a string with the filename of the page to which the navigation
  option should link. (This will automatically have ``-broadcast`` inserted
  before the file extension when the navigation detects that the user is
  viewing a :ref:`broadcast map <ui-broadcast_maps>`.)
* ``id`` is a string that should be short and is added to the navigation
  option's ID in order to give each one a unique identifier for CSS purposes.
  Each option will have the ID ``nav_option_ID``, where ``ID`` is the value of
  this property.

This navigation uses the Roto_ library, which works great but raises errors
from time to time; we keep it collapsed by default, but it doesn't expect to
ever be hidden. Errors raised by this library can be safely ignored.

.. _Roto: https://github.com/rdallasgray/roto


.. _ui-sidebars:

********
Sidebars
********

All pages (so far) have extra information (most commonly map legends) in the ``#sidebar`` element. This element contains three important child elements:

* ``#sidebar_title`` is a header with the title to be displayed in the sidebar.
* ``#legend`` is the main content container for the sidebar.
* ``#map_view`` is a hidden ``<input>`` that keeps track of the current
  :ref:`map view <nhmc.geo>` that is being displayed. This could be anywhere in
  theory, but this seemed like a reasonable place to put it.


.. _ui-tabs:

****
Tabs
****

Tabs live in the ``#view_tabs`` element and are each ``<div>`` elements with
the class ``view_tab``. The tab marked as active on the page also should have
the class ``view_tab_active``; this will be moved as necessary by the event
bindings in :ref:`nhmc.mapCenterInit`.

Each tab at least should contain an ``<a>`` element with the class
``view_tab_option`` containing the tab's text. It is up to the
:ref:`module <modules>` developer to add module-specific handlers for these
options, including parsing their text or ``href`` attributes as needed.

Tabs with the classes ``view_tab_more`` and ``view_tab_options_more``, if
provided, can include child dropdown menus, which are implemented as ``<ul>``
elements (called ``#view_tab_more_menu`` and ``#view_tab_options_more_menu``,
respectively) that contain more of these ``a.view_tab_option`` elements; when
these are clicked, their text and ``href`` attributes replace those of the
tab's top-level ``.view_tab_option`` element (i.e., above the ``<ul>``). For an
example of both of these tabs, see ``ethnicity.html``; for an example of tabs
without dropdown menus, see ``calc.html``.


.. _ui-tooltips:

********
Tooltips
********

These informational boxes appear next to the user's cursor (if on a desktop
device) or touch location (if on a mobile device) in certain
:ref:`modules <modules>` to show details about the area touched or hovered
over.

.. seealso::
   See the :ref:`tooltip package documentation <nhmc.tooltips>` for details.


.. _ui-flyouts:

Flyouts
=======

Flyouts are a special case of :ref:`tooltip <ui-tooltips>` intended
specifically for :ref:`broadcast maps <ui-broadcast_maps>`. They are positioned
on the left side of the screen and tend to be vertically centered. These allow
for the tooltip information to be presented without actually covering up the
part of the map with which the people on air are interacting.

When flyouts are rendered, they should add a stroke to the area being touched
or hovered over; when they are destroyed, they should remove that stroke.