.. _actions_and_services:
Actions and Services
====================
GeoMoose 3+ supports two different types of tools in the toolbar. In
general the two can be described as follows:
- ``service``\ s are tools which query a set of layers and process the
data.
- ``action``\ s do not use the data-query life-cycle and are mostly
arbitrary bits of JavaScript that can be executed.
Actions
-------
Actions do one thing, they execute the code in the ``run`` method when
clicked from the toolbar.
Example custom action
~~~~~~~~~~~~~~~~~~~~~
**alert.js**
::
function AlertAction(Application, config) {
this.run = function() {
alert(config.message);
}
}
The application's **index.html** would then need to include
**alert.js**:
::
And the new action would then need to be registered with the application
in the **app.js** file:
::
app.registerAction('say-hello', AlertAction, {message: 'Hello, World'});
Finally, the action needs to be linked to a tool in the toolbar. In
**mapbook.xml**, in the ```` section, the following would be
added:
::
When the application is reloaded, a new toolbar button will appear with
the text "Say Hello," clicking on it will cause the action to execute
the code in ``this.run`` -- alerting the contents of config.message
which was set to ``'Hello, World'``.
Services
--------
Services are more complex. A service is used to collect information from
the user and the map then use that information to generate a query.
After the query has executed, the results are then rendered into HTML.
Unlike an action, services require defining more members for them to
function properly:
- ``title`` - A title is required for rendering results in the Super
tab. This title is placed at the top of the tab and is useful for
recognizing what the service is attempting to render.
- ``tools`` - This is an object that defines which types of drawing
tools are available. Options available:
- ``Point: true`` - Allow the user to draw a single point for the
query.
- ``MultiPoint: true`` - Allow the user to draw multiple points for
the query.
- ``LineString: true`` - Allow the user to draw a line for the
query.
- ``Polygon: true`` - Allow the user to draw a polygon for the
query.
- ``Select: true`` - Let the user choose features from a different
layer.
- ``Modify: true`` - Allow the user to modify their previous
selections.
- ``buffer: true`` - Allow the user to buffer their drawn shapes.
- ``default: [Point|MultiPoint|Polygon|LineString]`` - Specify the
drawing tool that should be selected by default.
- ``fields`` - This is a list of objects that defines the user input
fields. See:doc:`input-types` for the types of input
which are available.
The ``title``, ``tools``, and ``fields`` definitions will be used to
render a set of user inputs when the service is clicked in the toolbar.
Services also have different methods which handle different phases of
the query cycle:
- ``query(selection, fields)`` - The ``selection`` parameter describes
the geographic selection made by the user. The ``field`` parameter is
a list of field names and values which were derived from the
``fields`` object. The ``query`` method's job is to modify and
normalize any inputs before submitting them to
``Application.dispatchQuery``. ``Application.dispatchQuery`` will
start the next step in the service's life-cycle, either running the
service's ``runQuery`` method or using the built-in querying
mechanisms for the specified layer(s).
- ``resultsAsHtml(queryId, query)`` - Returns HTML to render in the
Super tab.
Writing a custom query
~~~~~~~~~~~~~~~~~~~~~~
The default behavior for a service is to query the chosen layer(s) for
features. For example, if a layer is on a WFS-type map-source, GeoMoose
will dispatch a WFS GetFeatures query with the appropriate filters to
get the relevant features back to the user. However, there are time
where this functionality is not desired. The example included in
GeoMoose's example desktop application is geocoding. When running a
geocode query the user will not query the underlying layers but call a
different script which will return features. This requires defining a
different ``runQuery`` method. E.G.:
::
function MyCustomService(Application, config) {
runQuery(queryId, query) {
// Do some stuff...
}
}
See ``src/services/geocode-osm.js`` for more details.