Apr 7, 2025 4:51:52 PM Philippe Bareille

wiki : Technical documentation > Cartography on Lutece

Cartography on Lutèce

The Carto plugin and its modules address two recurring cartographic practices on the web:

• Consultation of localized data on a tiled map background, most often global
• Contribution of spatial data by site users.

Different dynamic or interactive maps can be presented on the same site:

• Location maps that allow visualizing the resources the application focuses on (appointment locations, event locations, intervention sites, anomaly locations, etc.)
• Interactive maps that combine the visualization of already recorded resources and other location elements, as well as drawing and editing functionalities to add resources to the database or produce documents derived from the map.

The display of spatial data on a map background can be done on the following front office page: Portal.jsp?page=coordinate&view=manageCoordonnees

The Carto plugin and its modules can be combined with the Forms plugin. Thus, entering spatial information can be an element of response to a form, such as in the case of a call for citizen participation. The map becomes a support for the user who completes their proposal by entering data on a map. The information entered on the map can be points, lines, or areas. This aspect is configurable in the Back Office according to the choices of site administrators based on thematic needs.

The Leaflet library is used as the display engine.

Indexing in Solr allows managing the display in the Front Office of all or part of the contributed data.

Modules

The Carto plugin utilizes:

• The cartography-solr module, to store and access geographic data for display in the FO
• The genericattributes-cartography module and the forms-cartography module to add Carto plugin functionalities to a Forms form

Building a Map in the Back Office

Two Back Office menus are used for cartography configuration: Cartography Reference and Cartography Configuration.

Cartography References

Three references constitute the fundamentals of maps that can be built: data layer types, geometry types, and map backgrounds.

Data Layer Types

The data layer type reference lists the interactivity features with the map.

A layer type:

• Consultation is not modifiable via the map in the Front Office. It is a data layer that provides context in an interactive map or serves to locate information on a site
• Editable by users and viewable by all users is the data layer for which it is possible to create a new geographic object by the user
• Inclusion defines a perimeter within which it is possible to create data on the editable data layer. Outside this perimeter, it is not possible to edit the data layer
• Exclusion defines a perimeter within which it is not possible to create data on the editable data layer. Outside this perimeter, it is possible to edit the data layer

To define an exclusion or inclusion zone, either the data is already indexed in the connected Solr, or it involves importing a geojson file delimiting the zone.

{ "type":
 "Feature",
 "id": 0, 
"properties": { }, 
"geometry": { "type": "Polygon", "coordinates": [ [ [ 2.351876929823846, 48.836814955383176 ], [ 2.355540683790891, 48.831349624682986 ], [ 2.349474078196109, 48.829532935753519 ], [ 2.33607996466724, 48.833213228500881 ], [ 2.339719928024108, 48.838850599512739 ], [ 2.347451876331182, 48.837206431832747 ], [ 2.351876929823846, 48.836814955383176 ] ] ]
 }
 }

Geometry Types

The reference including geometry types adheres to the standardized separation of geographic information systems. Currently, the three fundamental elements in GIS are integrated: points, lines, and polygons. Data is created in the WGS84 geographic coordinate system.

Map Backgrounds

By default, the classic OSM (OpenStreetMap) background is offered with the plugin. It is a free map background provided especially for associative projects serving OSM. It is not recommended to use these tiles in production to avoid consuming many resources on the OSM association's map servers. The map background reference allows adding other raster tile servers. It is also possible to add tiles with limited access via a token by adding this token in the URL declared in this menu.

Example of map backgrounds for testing: https://leaflet-extras.github.io/leaflet-providers/preview/

Cartography Configuration - Create a Map

Map Model Management

The map model is the element that will be called for displaying the map, either directly in an Xpage or in a form. It carries the basic characteristics for defining a map in Leaflet. A map model has the following attributes:

• A title
• A description
• A map background, selected from the map backgrounds listed in the reference
• A default zoom level, defining the scale at which the map will be displayed when the page loads
• A minimum zoom level, allowing to force the map reading at a minimum scale
• A maximum zoom level, allowing to restrict the zoom
• A center, an address that will center the map on the first page load

Data Layer Management

A data layer corresponds to the reference of a set of data from a Solr database. A data layer has the following attributes:

• A title
• A Solr tag: If data is already stored in the connected Solr database, it can be called by declaring the tag. Otherwise, when creating data from the application, it will carry the defined tag.
• A geometry type, chosen from the types registered in the reference
• The thumbnail: The content of the thumbnail that will appear when clicking on the cartographic object is configurable. If the map is associated with a form via the generic attributes module, it is possible to use other form fields to populate the thumbnail.

Linking Data and Map - Define Cartographic Representation

The link allows adding a data source to a map model, defining the graphic charter of the data layer, and defining the interactivity that will be possible on this data layer in the context of the associated map model.

A link between a map model and a data layer of type Point has the following attributes:

• Map model
• Data layer
• Pictogram
• Pictogram size
• Minimum zoom
• Data layer type

A link between a map model and a data layer of type Polygon has the following attributes:

• Map model
• Data layer
• Color
• Thickness
• Minimum zoom
• Data layer type
• Exclusion or inclusion JSON

A link between a map model and a data layer of type Line has the following attributes:

• Map model
• Data layer
• Color
• Thickness
• Minimum zoom

Using a Map Model and Creating Data within Forms

A map, defined in the BO (back office) of an application using the Forms plugin and its modules, can be integrated into a form so that the form response is complemented by localized data. Thus, the user could enter a point, a line, or an area as part of their FO entry. This is also possible for BO users. All management rules related to the map also apply to form entry, such as exclusion zones. Technically, display and entry via the map within a Forms form are enabled by the generic attribute Cartography available with the genericattributes-cartography module and the forms cartography module.

In the continuation of this documentation, we will follow the example of a call for proposals for urban furniture in the public space of a neighborhood. Given the subject, the data created by the FO user will be of point type.

Map Model, Data Layers, and Link

The cartographic elements will be:

• When opening the form, the map is centered at the address corresponding to the center of the neighborhood
• When opening the form, the map is at zoom level 15, corresponding in our case to the neighborhood scale
• During navigation, it is not possible to zoom out below zoom level 10

• A thematic context layer has been added: the neighborhood boundaries
• This same zone also defines the area within which ideas can be submitted

• The contribution data layer allows points to be entered by address or by clicking on the map

A New Generic Attribute: Cartography

A new generic attribute (or question type) has been created to allow entering spatial data according to the parameters of a map model.

In a form step, it is possible to add a "Cartography" type question. This question allows linking the question to the map model. Since each map model can only carry one editable data layer, the Front Office user will be authorized to edit this data layer. If no data layer is editable, this map will serve more as an illustration in the form.

On the Front Office side, the map integrates into the form flow. In our case, since it is point data, the entry can be made either by clicking on the map or by entering a specific address.

Workflow and Indexing Form Responses

Data layers are indexed in Solr. If there are already indexed data corresponding to the defined tag for the layers, they will appear on the map; for new data, they need to be indexed. Two configurations are required to ensure data is sent to Solr and thus displayed on the Front Office map:

• Choosing fields to index for publication:
  • In the form configuration, under the Publication tab, it is possible to choose the form fields to be indexed. Fields other than spatial data can populate the label of the spatial data when clicking on the object.
• Workflow Configuration:
  • A workflow is essential to trigger the publication of data, making it visible in the Front Office. This involves adding a task in a manual or automatic action. The task is titled (Forms) Update publication status and allows either the publication or unpublication of a resource.

Response Visualization

As in a typical usage context of the Forms plugin, it is possible to view responses from the Back Office. If spatial data has been entered, a map centered on the object is displayed.

Organization of Map Models

The designed data layer calling system offers flexibility and allows reusing the same data to create multiple maps. Thus, a data layer can be editable within a map model. The map model serves this data editing, and the charter is designed to highlight the editable layer. Additionally, the data layer can become a context layer for another model, allowing either the editing of another map or a synthesis of multiple editable data layers in other contexts. In a citizen participation project, this flexibility allows offering both the simplest possible editable maps for precise entry and maps highlighting the richness of proposals and themes.

Storage of Spatial Data and Indexing

Carto Plugin Tables

• carto_basemap: map background display configurations
• carto_coordonnee: storage of coordinates of objects created via the XPage (excluding FormResponse).
• carto_data_layer: definition of each layer (Solr tag, geometry type, popup content)
• carto_data_layer_map_template: Link table between layers, graphic representation, and the map
• carto_data_layer_type: List of layer types
• carto_geometry_type: List of geometry types
• carto_map_template: Global map definition (center, zoom level)

Storage of Cartography Generic Attribute Data

When entering a Cartography generic attribute field, two fields in the Lutece database are populated: coordinates_geojson and DataLayer. The coordinates_geojson field contains the geometry in geojson format of the entered object. The DataLayer field contains the information of the targeted data layer.

Excerpt from the genatt_response table

# id_response, response_value, id_entry, iteration_number, id_field, id_file, status, sort_order
1, {"geometry":{"coordinates":[2.3851318355445987,48.85827758964043],"type":"Point"},"properties":{"address":""},"type":"Feature"}, 3, -1, 13, , 1, 0
2, Coffee, 3, -1, 14, , 1, 0

Indexing in Solr

Values recorded in the response_value field of the genatt_response table are indexed in Solr. In the example below, the value of the response_value field for individual #1 from the above example is found under the tag "entry_code_question_3_iter_0_geojson". The "DataLayer_text" tag contains the information of the data layer to which the geometry is associated.

{
        "uid":"Demo_1_FORMS_FORM_RESPONSE",
        "date":"2023-10-25T10:24:38Z",
        "type":"FORMS_FORM_RESPONSE_1",
        "title":"formResponse #1",
        "site":"Demo",
        "role":"formResponse",
        "url":"jsp/site/Portal.jsp?page=formsResponse&id_response=1",
        "content":"{\"geometry\":{\"coordinates\":[2.3851318355445987,48.85827758964043],\"type\":\"Point\"},\"properties\":{\"address\":\"\"},\"type\":\"Feature\"} Coffee ",
        "id_resource":"1",
        "id_form_response_long":1,
        "entry_code_question_3_iter_0_geojson":"{\"geometry\":{\"coordinates\":[2.3851318355445987,48.85827758964043],\"type\":\"Point\"},\"properties\":{\"address\":\"\",\"icon\":\"FORMS_FORM_RESPONSE-entry_code_question_3_iter_0\"},\"type\":\"Feature\"}",
        "response_creation_date_long":1698229478000,
        "id_workflow_state_long":2,
        "entry_code_question_3_iter_0_address_text":"",
        "title_workflow_state_string":"Publié",
        "entry_code_question_3_iter_0_geoloc":"48.858278,2.385132",
        "DataLayer_text":"Coffee",
        "form_title_string":"Proposition de localisation d'un café",
        "response_update_date_long":1698229559000,
        "id_form_long":1}