Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
..
Failed to load latest commit information.
images
src
README.adoc
log.roo
pom.xml
quickstart-geo.roo

README.adoc

gvNIX quick start GEO application

gvNIX is a Spring Roo distribution that focuses both enterprise knowledge and enterprise standards to build Java applications.

If you don’t know What is gvNIX? you should start with quickstart-app tutorial.

You must download, unpack and install the development environment for gvNIX 1.5+, to be able to follow this guide.

The goal of this quick start geo app guide is to familiarize you with GEO apps generated using gvNIX. For this purpose, we will build an application based on quickstart-app tutorial.

You can see an example of a generated GEO web application using gvNIX here (user: admin | pass: admin)

map

gvNIX uses Leaflet project to generate map views.

Run from Git

If you want to preview this GEO sample application, follow this steps on the following order. If you prefer to develop by your own, go to gvNIX GEO Guide

  • Install PostgreSql and PostGIS

  • Create new Database with name postgis_example. Use gvnix as username and gvnix as password.

  • Add Postgis extensions on generated DB:

postgis db

  • Clone github repository

    $ git clone https://github.com/DISID/gvnix-samples.git
  • Acces to quickstart-geo-app

    $ cd quickstart-geo-app
  • Execute application using maven:

    $ mvn clean compile tomcat7:run
  • Open your browser on http://localhost:8080/petclinic/

  • Access using admin as username and admin as password.

Build your own geo app

You can execute quickstart-geo.roo file and creates a petclinic example application with GEO components.

If you don’t have experience using gvNIX, you can follow quickstart-app guide and then follow this to generate additional GEO components and functionalities.

This guide teaches you how to:

Configure Persistence

All DataBases are not valid to use Spatial Operations.

That’s why we need to configure our project with some valid Spatial DB. We can choose one of the following:

To follow this guide, you should configure a POSTGRES database on your system and add POSTGIS functionalities. To make that possible you can read postgis documentation.

When you have a valid POSTGIS Database configured on your system, you can execute the following command with your database configuration:

jpa setup --provider HIBERNATE --database POSTGRES --userName USERNAME --databaseName DATABASENAME --password PASSWORD --hostName HOSTNAME

Now, you have your project configured to use a valid Spatial Database.

Add Spatial Support

Your Database is configured to accept GEO types and GEO functionalities, but not your project.

To do that, you need to configure your project persistence with some valid Spatial Provider like Hibernate Spatial.

Execute the following command on your gvNIX shell to add spatial support:

jpa geo setup --provider HIBERNATE_SPATIAL
Note
This Spatial Provider is only available if your provider persistence is HIBERNATE and you select a valid DB

Add Geo Entity Fields

Now, you can add new fields to your generated Entites. (If you don’t generate entities before you should check quickstart-app guide)

You can add some different field types: POLYGON, POINT, LINESTRING, MULTILINESTRING, GEOMETRY, etc…​

You should execute the following to add new fields on Owner entity:

field geo --fieldName location --type POINT --class ~.domain.Owner
field geo --fieldName distance --type LINESTRING --class ~.domain.Owner
field geo --fieldName area --type POLYGON --class ~.domain.Owner
Note
Geo Field commands will not be available until you install Hibernate Spatial Provider.

Generate Geo Entity Finders

To get GEO fields values on a map view we need to generate some different methods with Spatial functionalities.

You can make it possible generating all finder methods for all entities with GEO fields. To do that, you need to execute the following command:

finder geo all

On the other hand, if you want to generate finder methods of an specific entity with geo fields, you need to execute the following command:

finder geo add --class ~.domain.Owner
Note
If you execute finder geo add command on a entity that not has geo fields, you are going to get an error message.

Generate Map Views

You can generate all maps you want on your application. To do that, you need to execute the following commands:

web mvc geo controller --class ~.web.MapViewerController --preferredMapping mapview --projection EPSG4326
web mvc geo controller --class ~.web.MapController --preferredMapping map

Previous commands generate different map views and different entries on top menu. The first map generated is configured with EPSG4326 projection. By default all generated maps are generated with EPSG3857 projection.

menu simple map

Note
If you want to configure map options like zoom, center point, base layer, etc.. you need to edit manually your views/{mappath}/show.jspx file

Use Map Control on CRU

Now, you are going to generate Map Controls on your CRU entity views (create.jspx, show.jspx, update.jspx) to create, display and update GEO fields values.

To make that possible, you should execute the following commands:

web mvc geo field --controller ~.web.OwnerController --field location
web mvc geo field --controller ~.web.OwnerController --field distance
web mvc geo field --controller ~.web.OwnerController --field area

Now you can manage easly GEO fields values.

Note
If you don’t apply this Map Components on CRU views, you need to use WKT on input fields to save valid values
Note
After you execute these commands, you will get a message informing that you need to specify a base layer for those fields.

Add Base Layer to CRU Entity Views

At this point you have the Map Controls to manage GEO fields. Now, you should include a base layer on your CRU entity views which displays a map to place geo data.

Exists more than one type of base layers. At the moment, gvNIX provides you this three types:

To add a base layer to each geo field of your CRU entity views you need to execute the following commands:

web mvc geo base layer field --controller ~.web.OwnerController --field location --url "http://maptile.maps.svc.ovi.com/maptiler/maptile/newest/satellite.day/{z}/{x}/{y}/256/png8" --type tile
web mvc geo base layer field --controller ~.web.OwnerController --field area --url "http://maptile.maps.svc.ovi.com/maptiler/maptile/newest/satellite.day/{z}/{x}/{y}/256/png8" --type tile
web mvc geo base layer field --controller ~.web.OwnerController --field distance --url "http://maptile.maps.svc.ovi.com/maptiler/maptile/newest/satellite.day/{z}/{x}/{y}/256/png8" --type tile
Note
The --type option can be tile, wms or wmts depending on the provider service.

With the previous commands, you have included a tile layer on your CRU entity views like the following.

CRU map

Add Base Layers to Map Views

gvNIX provides you the possibility to display extra base layers on your map views.

Exists more than one type of base layers. At the moment, gvNIX provides you this three types:

If you want to add Tile Layer on your map views, you need to execute the following command. On this example, you are going to add a Satellit base layer from OVI:

web mvc geo tilelayer --name satellit --url "http://maptile.maps.svc.ovi.com/maptiler/maptile/newest/satellite.day/{z}/{x}/{y}/256/png8" --index 1 --opacity 0.5

If you want to add WMS Layer on your map views, you need to execute the following command. On this example, you are going to add a geological map of Valencia (Spain) from IGME

web mvc geo wmslayer --name "geological map of valencia" --url "http://mapas.igme.es/gis/services/Cartografia_Geologica/IGME_GeologicoCValenciana_400/MapServer/WMSServer" --format "image/png" --transparent true --version "1.1.1" --crs EPSG4326 --layers "0,1,2,3"
Note
When you add new WMS layer, you need to get it using the same projection than your current map views. If you don’t do like this, you can see your wms layer on invalid map position.
Note
If you add --map command option, you are going to add the new base layer only on the selected map instead of every map

If you want to add WMTS Layer on your map views, you need to fill the parameters of this following command.

web mvc geo wmslayer --name "" --url "" --layer ""

Add entities to Map Views

gvNIX provides you the possibility to display entity data on your map views.

On the third point of this guide we added 3 new geo fields on Owner entity.

If you want to display all GEO entities on every maps, you need to execute the following commands:

web mvc geo entity all

However, if you want to add only one geo entity to every map, you need to execute the following command:

web mvc geo entity add --controller ~.web.OwnerController
Note
If you want to display only one geo entity or all entities in an specific map, you can use --map param selecting the map where you want to display them

Previous commands add to your Map views Owner entity. You can display or hide its fields using checkbox as see on the next images:

map entities map entity 0 map entities 1

Add Tools to Map Views

By default, as you can see on the previous images, when you generate new map view appears a toolbar on bottom right position. This toolbar contains a basic Hand Tool that indicates that you can move the map view.

At the moment, you can add two tool types using gvNIX commands:

  • Measure Tool: Get distances between some points.

  • Custom Tool: Customize it to generate new custom tools with custom functionalities on your map view.

If you want to add new measure tool on your map views you need to execute the next simple command:

web mvc geo tool measure --name measure

If you want to add new custom tool on your map views you need to execute the following command:

web mvc geo tool custom --name latlng --icon fa-location-arrow --activateFunction activateLatLngTool --deactivateFunction deactivateLatLngTool --iconLibrary fa

At now, we added new custom tool on toolbar but without any functionality. This tool will get the Latitude and Longitude from selected Point.

To add custom functionality you need to implement activateFunction and deactivateFunction like the following:

function activateLatLngTool(map, instance, element){
    var oMap = map.fnGetMapObject();
	oMap.on("click", function(e){
   	   alert(e.latlng);
  	});
}
function deactivateLatLngTool(map, instance, element){
	var oMap = map.fnGetMapObject();
	oMap.off("click");
}
Note
If you add --map command option, you are going to add the new tool only on the selected map instead of every map

Also, you can find more tools in the WEB-INF/tags/geo/tools folder. To include any of these tools you need to add its tag with the required parameters to the geo:toolbar tag in your views/{mappath}/show.jspx file. Below you can find some examples:

  • Add Print Tool.

    <geo:toolbar id="ps_com_springsource_petclinic_web_Map_toolbar" z="MBw20Dq9PKNdvfzOXRO7MnYvi10=">
        ...
        <tool:print id="ps_com_springsource_petclinic_web_Map_print"/>
        ...
    </geo:toolbar>
  • Add Zoom Select All Tool. It zooms and places your map to display all entity geo data efficiently.

    <geo:toolbar id="ps_com_springsource_petclinic_web_Map_toolbar" z="MBw20Dq9PKNdvfzOXRO7MnYvi10=">
        ...
        <tool:zoom-select-all id="ps_com_springsource_petclinic_web_Map_zoomall" />
        ...
    </geo:toolbar>
  • Add Action Tool. It allows you to define an action.

    <geo:toolbar id="ps_com_springsource_petclinic_web_Map_toolbar" z="MBw20Dq9PKNdvfzOXRO7MnYvi10=">
        ...
        <tool:action actionFunction="showHelpMessage" icon="fa-info-circle" iconLibrary="fa" id="ps_com_springsource_petclinic_web_Map_showhelp"/>
        ...
    </geo:toolbar>

    Also, you need to define the showHelpMessage function.

    function showHelpMessage(map, instance, element){
        alert("Show any help information");
    }

When you finish these steps you are going to have the following toolbar:

toolbar

Add Overview to Map Views

If you want to include an overview on any of your map views, you need to execute the following command. The class parameter indicates which map the overview will be added to

web mvc geo component overview --class ~.web.MapController

By default, this component shows all the layers added on that map view.

overview

Note
You can select which layers are displayed by editing layers overview code in your views/{mappath}/show.jspx file.

Add Geo Components to Map Views

There are several geo functionalities that can be added to any map view:

Note
These components are not added using commands, but you need to include them by editing your views/{mappath}/show.jspx file.

Add Real Coordinates

To show the real coordinates of the mouse pointer position on a map view you need to include the next code in your views/{mappath}/show.jspx file:

  1. If your show file does not contain a geo:component tag you need to add it. Include the following code inside the geo:map tag:

    <geo:components id="ps_com_springsource_petclinic_web_Map_components">
    </geo:components>

    Then, you need to add its dependency:

    <div
     ...
     xmlns:components="urn:jsptagdir:/WEB-INF/tags/geo/components"
     ...
    version="2.0">
  2. Inside the geo:component tag you need to include the coordinates tag, as is shown below:

    <geo:components id="ps_com_springsource_petclinic_web_Map_components">
       <components:coordinates id="ps_com_springsource_petclinic_web_Map_coordinates" centerInputCoordinates="true"/>
    </geo:components>

This component also allows to mark a position by specifing coordinates location.

coordinates

Note
If you enable the centerInputCoordinates option, when you specify a location you will be placed there automatically.

Add Map Scale

To show a map scale on a map view you need to include the next code in your views/{mappath}/show.jspx file:

  1. If your show view file does not contain a geo:component tag you need to add it. Include the following code inside the geo:map tag:

    <geo:components id="ps_com_springsource_petclinic_web_Map_components">
    </geo:components>

    Then, you need to add its dependency:

    <div
     ...
     xmlns:components="urn:jsptagdir:/WEB-INF/tags/geo/components"
     ...
    version="2.0">
  2. Inside the geo:component tag you need to add the scale tag, as is shown below:

    <geo:components id="ps_com_springsource_petclinic_web_Map_components">
      <components:scale id="ps_com_springsource_petclinic_web_Map_coordinates"/>
    </geo:components>

Add Street Map Searcher

To include a street map searcher which locates places based on text introduced, you need to include the next code inside geo:toolbar tag in your views/{mappath}/show.jspx file:

<geo:toolbar id="ps_com_springsource_petclinic_web_Map_toolbar" z="user-managed">
    ...
    <tool:geosearch id="ps_com_springsource_petclinic_web_Map_geosearch"/>
</geo:toolbar>

When you search a location a marker is placed on the result.

gosearch

Add Opacity Layer Control

To include a slider which manages the opacity of map layers, you need to include the next code in your views/{mappath}/show.jspx file:

  1. Inside geo:toc tag you need to add a geo:toc-toolbar tag.

  2. Include the opacity tag inside the previous geo:toc-toolbar tag, as is shown below:

    <geo:toc id="ps_com_springsource_petclinic_web_Map_toc" z="YpKTYjQzut/zC96UI52ho3hliRk=">
      <geo:toc-toolbar id="ps_com_springsource_petclinic_web_Map_toc_toolbar" z="user-managed">
        <tool:opacity id="opacity_slider" z="user-managed"/>
      </geo:toc-toolbar>

opacity

Add Tools to Layers

gvNIX allows you to add new tools not only to your map view but also to your layers. If you want to include a tool on a entity field layer you need to add a tool tag inside your entity field layer tag in your views/{mappath}/show.jspx file.

For example, to add a zoom select tool (which places your map to display all geo field data attached to the selected layer efficiently) to a layer, you have to include this tool as is shown below:

<layer:entity-field field="location" id="l_com_springsource_petclinic_domain_Owner_location" ... >
   <layer-toc:tools >
      <layer-tool:zoom-select id="owner-location-zoom-select" />
   </layer-toc:tools>
</layer:entity-field>

layer tools

Advanced Functionalities

At this moment you have a complete gvNIX GEO application. But…​ Which posibilities I have with this GEO application?

Here there’s some functionalities that you can implement/modify on your generated map view.

Filtering Map Data using Datatables

By default, all entities that you add to Map View are filterable. You can identify a filterable entity by the filter icon that appears on layers panel (TOC)

filter icon

With this functionality, you can filter your entity map data using his Datatable. Here’s an example:

At first, you are displaying all your Owner records on map.

filter 0

If you filter Datatable, you are going to show only filtered records and filter icon change as selected.

filter 1

If you filter Datatable with other value, you are going to show different filtered records and filter icon change as selected.

filter 2

Note
You can change filter type of an entity modifying filterType attribute on src/main/webapp/WEB-INF/views/{mappath}/show.jspx. If you set to auto, when you filter datatable, Map data is going to reload automatically. If you set to manual, you need to refresh Map View page to display filtered data. If you set to none filter button disappear and get all entity records without filter.

Select Map Data using Datatables

With this functionality you can select some records (is possible to select more than one) from Datatables and "mark as selected" on your map views as you can see on the following image:

selection map

By default this functionality is not enabled. To activate it you need to enable the entity layer selection option in your src/main/webapp/WEB-INF/views/{mappath}/show.jspx file:

 <layer:entity selection="true" id="l_com_springsource_petclinic_domain_Owner" path="/owners" ...>

This functionality is compatible with Filter Map Data, you can filter your map data using Datatables and then select some record.

Note
You can modify selection style editing entity-field selection attributes on src/main/webapp/WEB-INF/views/{mappath}/show.jspx

Configure Map Data Filter

By default, if you press an entity filter icon its entity datatables is loaded on a dialog. You can change how entity datatables are displayed to one of these options:

  • Window: the entity datatables is displayed on a new page.

  • Dialog: the entity datatables is load on a dialog.

  • Custom: you can custumize how entity datatables is shown.

Note

If you want to change how entity filter is shown, you need to set showFilterOn to dialog in your src/main/webapp/WEB-INF/views/{mappath}/show.jspx file:

 <layer:entity showFilterOn="dialog" id="l_com_springsource_petclinic_domain_Owner" path="/owners" ...>

Group Map Markers

If you have some close markers when you change zoom, gvNIX can group them to improve map navigation as you can see on the following image:

grouped markers

If you click on grouped marker map will zoom on markers area to view all markers without group.

By default this functionality is not enabled. To activate it you need to enable the clusterize option of your layer fields in your src/main/webapp/WEB-INF/views/{mappath}/show.jspx file:

<layer:entity-field clusterize="true" field="location" id="l_com_springsource_petclinic_domain_Owner_location" .../>

Add Marker Label

If you want to show information in your entity markers, you can use an entity propiety as a marker label.

To show a propiety value in an entity marker you need to set this propierty in your src/main/webapp/WEB-INF/views/{mappath}/show.jspx file:

<layer:entity-field labelingProperty="lastName" field="location" id="l_com_springsource_petclinic_domain_Owner_location" .../>

gvNIX is based on Spring Roo project.

To implement GEO functionalities gvNIX uses Leaflet project and different Leaflet Plugins like: