.. _widget-api-label:

=====
 API
=====

The main purpose of this widget is to act as an **API** for GeoPrisma. It can
be used as a single **point of entry** for external JavaScript libraries to
**interact** with GeoPrisma and its widgets.  It is done so using **methods**,
which are described in details below.

.. note:: 
 * it doesn't need to be defined in the config file
 * **must be included** in your xslt template file
 * doesn't need to be drawn
 * has no options


API Methods
------------

Each method receives a list of arguments and delegate them to an event they
trigger.  Widgets that need to interact with an event need to listen to it and
then react accordingly.

Here's the list of the currently supported methods, each defining their
required *arguments*, an *example* of use and the *widgets* using them.

applyFilters
~~~~~~~~~~~~~

This method fires the 'applyfilters' event.

*Arguments :*

:(Array): An array of hash objects containing the following keys and values :

          * **resource** (String) : the name of the resource to apply the filter
          * **filter** (OpenLayers.Filter) : the filter to apply to the
            resource.

*Example :*

.. code-block:: xml

  GeoPrisma.applyFilters([{
      resource: "R_Park",
      filter: new OpenLayers.Filter.Comparison({
          type: OpenLayers.Filter.Comparison.LIKE,
          property: "REG_CODE",
          value: "24"
      })
  }]);

*Widgets :*

* :ref:`widget-applyfilter-label`


applyFilter
~~~~~~~~~~~~

This method fires the 'applyfilters' event.

*Arguments :*

:(Object): A hash object containing the following keys and values :

          * **resource** (String) : the name of the resource to apply the filter
          * **filter** (OpenLayers.Filter) : the filter to apply to the
            resource.

*Example :*

.. code-block:: xml

  GeoPrisma.applyFilter({
      resource: "R_Park",
      filter: new OpenLayers.Filter.Comparison({
          type: OpenLayers.Filter.Comparison.LIKE,
          property: "REG_CODE",
          value: "24"
      })
  });

*Widgets :*

* :ref:`widget-applyfilter-label`

.. note:: This method fires the same event as the *applyFilters* one.  Its used
          to apply a single filter to a single resource using the object as the
          argument instead of an array.


Util Methods
-------------

The following methods are available for use internally in GeoPrisma API and is
destined for development use.

getLayers
~~~~~~~~~~

*Returns :*

(Array) of OpenLayers.Layer objects that match the specified search options.

*Arguments :*

:(Object): A hash option that can have any or all of the following search
           criteria :

           * **resourceName** (String) : the resource name the layer must have.
           * **serviceType** (String) : the service type the layer must have.
             Possible values are any of the service **type** in lowercase.

             .. note:: The possible values for this option can be found
                       in this page : :ref:`concepts-service-label`. Look for
                       the **type** property.

*Example :*

.. code-block:: xml

  var matchLayers = GeoPrisma.getLayers({
      resourceName: "R_Park",
      serviceType: "wms"
  });


zoomToFeatureExtent
~~~~~~~~~~~~~~~~~~~~

See in code for more documentation.


Service Type
--------------
N/A


Widget Action
--------------
read