.. _services_understanding: Understanding GeoMOOSE Services =============================== Introduction ------------ GeoMOOSE expects services to return a special HTML format that allows it to display information and manipulate the user interface. Learning how to craft custom services enables developers and administrators to extend GeoMOOSE past the capabilities provided in the demos. Our First Service ----------------- To create our first service we are going to focus on a very basic GeoMOOSE PHP-Service. Save these contents to `php/myservice.php`: :: This is my first service. The following is a commented version of the code explaining all of the components. :: This is my first service Defining the Service in the Mapbook ------------------------------------- Integrating a service with GeoMOOSE requires two parts. First, defining how to communicate with the service. This is done with a `` tag. Second, we need to define a tool in the toolbar that calls the the service we have defined. To use our example, we need to find an open place in the Mapbook to add the text. For our purposes, find the `` tag, and insert the following text afterwards. :: php/myservice.php The contextual meaning of the different attributes and children are listed here. :: php/myservice.php The `` entry above defines how the application should communicate with the service. Now, we need to add the service to the user interface. To do this we need to add a `` entry to the ``. There are a number of types of ``s found in the ``. They are: * `internal` - These are built-in javascript type tools that trigger different behaviors in the UI. * `javascript` - These can be used to add arbitrary javascript code to the "onclick" event to a tool. * `service` - These call services defined by `` tags and is the type we will use in our example. * `layer` - These call layer editing tools. The easiest spot to add this entry is before the `` line. :: The other attributes for a tool are. * `name` - This is the name of the tool. It can be used to hook to different styling elements. * `title` - This is the label for the tool. By default the label is only shown when hovering over the tool. * `selectable` - Tools that are `selectable` cannot be used when other tools are being used. If tool has `selectable` set to false then it will not prevent other tools from operating at the same time. * `service` - This is the service to call when this tool is clicked. This is only valid for `tool`s with `type="service"`. Testing out the new Service --------------------------- To test the new service, clear the browser cache and reload GeoMOOSE. A small binoculars should appear at the end of the list of tools. Clicking on the binoculars will make the text "This is my first service." appear in the Results tab. Adding User Input ----------------- From time to time, it is necessary to allow users to enter parameters to the service. GeoMOOSE supports a number of different inputs types that can be found in :doc:`this reference `. First, we will modify the service to output some requests. :: This is my first service, , and you drew the shape . Second, we will add an input "step" to the service. GeoMOOSE allows services to have a number of input steps. Each input step is like a slide in a presentation, or pages of a book, where the user is prompted to enter information. A special type of step is the `type="spatial"`, these will prompt the user to draw a shape on the map. This lets services have both multiple pages of inputs and multiple spatial inputs. In this example, we will add both a spatial and an input step. :: php/myservice.php Annoying the User ----------------- Up to this point we have explored the `` section of a GeoMOOSE service results. The ` This is my first service, , and you drew the shape . Doing something Useful ---------------------- While it can be fun to simply annoy users, it is probably more practical to do something useful with the information we are given. This example parses the WKT of the user's input and zooms to that location on the map. :: This is my first service, , and you drew the shape . Stylizing Your Toolbar Icon --------------------------- Showing the Label ^^^^^^^^^^^^^^^^^ Changing the label is very simple. Set the `show-label` attribute to `true`. :: Changing the Icon ^^^^^^^^^^^^^^^^^ GeoMOOSE contains icons for the various default icons but changing the default icon for a custom service does require two steps. First, we need to add a snippet of CSS either as a `