Functions
=========

.. index:: display() ; SDCat.App function
.. js:function:: SDCat.App.display()
   :noindex:
   
   Populates and displays the app. In most cases, this is the only function you will ever need to run.

.. index:: displaySidemenu()
.. js:function:: SDCat.App.displaySidemenu()
   :noindex:

   Adds the sidemenu to the app. This function will create the div and then add the required controls
   to the sidemenu, based on the options that were set when the App object was initialised.

.. index:: createSectionHeader()
.. _createSectionHeader:
.. js:function:: SDCat.App.createSectionHeader(header, help)
   :noindex:

   Creates, populates and adds a header to a control in the app's sidemenu.

   .. attribute:: header
      :noindex:

      (*String*) - The text to appear in the section header.

   .. attribute:: help
      :noindex:

      (*String* or *Array*) - The text to appear when the cursor is over the help icon.

.. index:: addButtonsToSidemenu()
.. js:function:: SDCat.App.addButtonsToSidemenu()
   :noindex:

   Loops through the :ref:`SDCat.App.sidemenuButtons <sidemenuButtons>` and adds them to the sidemenu.

.. index:: createSelectBox()
.. _createSelectBox:
.. js:function:: SDCat.App.createSelectBox(options)
   :noindex:

   Creates a select box comprised of the options in a given :ref:`SDCat.App.items <items>` list.

   .. attribute:: options
      :noindex:

      (*Object*) - Contains the select box specific options. The attributes of this object are as follows:

      .. attribute:: header
         :noindex:

         (*String*) - The text of this select box's section header. This will be passed to :ref:`SDCat.App.createSectionHeader() <createSectionHeader>`.
     
      .. attribute:: type
         :noindex:

         (*String*) - The type of :ref:`items <items>` which will populate this select box.

.. index:: setDefaultOptions()
.. js:function:: SDCat.App.setDefaultOptions(box)
   :noindex:

   Preselects default options in a select box, based on the contents of the item's :ref:`default <items.default>` attribute.

   .. attribute:: box
      :noindex:

      (*String*) - The type of :ref:`items <items>`. This will be the same as ``options.type`` in :ref:`SDCat.App.createSelectBox() <createSelectBox>`.

.. index:: refreshSelectBox()
.. js:function:: SDCat.App.refreshSelectBox(box)
   :noindex:

   Refreshes the content of a select box, based on the contents of the item's :ref:`default <items.default>` attribute.

   .. attribute:: box
      :noindex:

      (*String*) - The type of :ref:`items <items>`. This will be the same as ``options.type`` in :ref:`SDCat.App.createSelectBox() <createSelectBox>`.

.. index:: createButtonSet()
.. js:function:: SDCat.App.createButtonSet(options)
   :noindex:

   Creates a JQuery buttonset comprised of the options in a given :ref:`SDCat.App.items <items>` list.

   .. attribute:: options
      :noindex:

      (*Object*) - Contains the buttonset specific options. The attributes of this object are as follows:

      .. attribute:: header
         :noindex:

         (*String*) - The text of this buttonset's section header. This will be passed to :ref:`SDCat.App.createSectionHeader() <createSectionHeader>`.
     
      .. attribute:: type
         :noindex:

         (*String*) - The type of :ref:`items <items>` which will populate this buttonset.

      .. attribute:: onChange
         :noindex:

         (*Function*) - The function to run when the buttonset's value has been changed.

.. index:: createButton()
.. js:function:: SDCat.App.createButton(options)
   :noindex:

   Creates a JQuery button.

   .. attribute:: options
      :noindex:

      (*Object*) - Contains the button specific options. The attributes of this object are as follows:

      .. attribute:: title
         :noindex:

         (*String*) - The text that will appear on the button.

.. index:: createDropDownBox()
.. js:function:: SDCat.App.createDropDownBox(options)
   :noindex:

   Creates a JQuery drop down box comprised of the options in a given :ref:`SDCat.App.items <items>` list.

   .. attribute:: options
      :noindex:

      (*Object*) - Contains the drop down box specific options. The attributes of this object are as follows:

      .. attribute:: id
         :noindex:
     
         (*String*) - The ID of this drop down box.

      .. attribute:: type
         :noindex:

         (*String*) - The type of :ref:`items <items>` which will populate this drop down box.
 
      .. attribute:: headerText
         :noindex:

         (*String*) - A description of this drop down box. This will appear on page load as the default text that appears in the drop down box.

      .. attribute:: onChange
         :noindex:

         (*Function*) - The function to run when the buttonset's value has been changed.

.. index:: selectItemsByAttribute()
.. js:function:: SDCat.App.selectItemsByAttribute(itemType, attribute, attributeValue)
   :noindex:

   Returns an array item names from a :ref:`SDCat.App.items <items>` list where an attribute matches a value.

   .. attribute:: itemType
      :noindex:

      (*String*) - The type of :ref:`items <items>` to search through.

   .. attribute:: attribute
      :noindex:
 
      (*String*) - The attribute of the :ref:`item <items>` to search against.

   .. attribute:: attributeValue
      :noindex:

      (*String*) - The value of the attribute to search for.

   Example::

      // Find all BAS radars
      var filteredItems = app.selectItemsByAttribute("radars", "institute", "British Antarctic Survey");

   This will return an array containing the  radars where the institute attribute matches **British Antarctic Survey** 
   (i.e. **fir** and **hal**).

.. index:: selectAll()
.. js:function:: SDCat.App.selectAll()
   :noindex:

   Selects all items in the app. Note that the only items selected are those where the ``clearable`` flag is set to ``true``.

.. index:: clearSelection()
.. js:function:: SDCat.App.clearSelection()
   :noindex:

   Clears all selected items and resets the selection boxes. Note that the only items selected are those where the ``clearable`` 
   flag is set to ``false``.

.. index:: addHelp()
.. js:function:: SDCat.App.addHelp(element, helpText)
   :noindex:

   Adds a help tooltip to an element in the page.

   .. attribute:: element
      :noindex:

      (*JQuery element*) - When the cursor hovers over this element, the help tooltip will be displayed.

   .. attribute:: helpText
      :noindex:

      (*String* or *Array*) - Collection of bullet points that will appear in the tooltip which make up the help text. If a *String* is 
      supplied, it will be converted to an *Array*. This is usually the ``help`` attribute of the app components.

.. index:: generatePlot()
.. js:function:: SDCat.App.generatePlot()
   :noindex:

   Generates the coverage plot by creating a **SDCat.CoveragePlot** object and displaying it on the page.

.. index:: resetView()
.. js:function:: SDCat.App.resetView()
   :noindex:

   Resets the view of the plot to the original timespan after zooming in.