Mapbender Quickstart: First steps with Mapbender

Mapbender is a web based geoportal framework to publish, register, view, navigate, monitor and grant secure access to spatial data infrastructure services. Management interfaces empower administrators who need to maintain and categorize map and feature services and grant access to individuals, groups and other services. Mapbender is written from the ground up using modern web technologies. The foundation is laid by Symfony. On the client-side expect to find OpenLayers.

With this code base, we will continue the Mapbender idea of being a Geoportal framework. Key features of Mapbender are:

• Applications can be setup, configured and styled right from within the browser.

• Services (e.g. WMS) can be managed inside a service repository and linked to applications.

• Rights management are easy to maintain, for individual users and groups, whether you store them inside the database or in an LDAP.

• Search modules can be configured.

• Applications for digitalization can be setup.

• Mobile template can be used to provide applications for smartphones and tablets.

You will need nothing but a web browser for this quickstart.

This quickstart offers sections to:

• 1. Start Mapbender

• 2. Create an application

• 3. Add elements to your application

• 4. Configure Sources

• 5. User and group management

• 6. Rights management

• 7. Start an Application at a defined position

This is how a Mapbender application can look like:

Install Mapbender

This quickstart explains the basics of Mapbender and serves as a quick introduction after your first successful Installation.

1. Start Mapbender

1. Choose Mapbender from the start menu (if a shortcut was already created) or visit http://localhost/mapbender (this address can be slightly different depending on how the Apache Alias was created in the file /etc/apache2/sites-available/mapbender.conf. Find more information under Installation).

2. The application should then appear in your browser window.

If you have any difficulties running Mapbender, please check whether your Apache web server and your PostgreSQL database are running without errors.

Start Mapbender in a productive environment

Mapbender offers two environments: dev (this is the default) and prod.

The development environment shows full error messages including stack traces in the browser and enables the Symfony debug console and profiler. Also, caching is disabled. The productive environment enables caching and only shows generic error messages. More specific error messages are written into logfiles.

The environment can be set via the APP_ENV variable. Make sure to change this to prod when deploying your application for the public. The value can be changed in several ways:

• by overriding the value in an .env.local file,

• by setting an environment variable in your Apache2 vHost configuration: SetEnv APP_ENV prod,

• by explicitly setting it when starting the local webserver:

APP_ENV=prod symfony server:start --no-tls

Mapbender Backend

1. After a successful Mapbender startup, the application overview page in the Backend will appear. The applications are listed with a screenshot, title, URL title and description.

2. You can open an application by clicking on its title, its screenshot or via .

3. A login is required to gain access into Mapbender’s Backend. In order to do so, click on Login at the top-right of the login page. You can login with the user that was generated during installation. This could be root with the password root. This is the default user and password that you get after installation of Mapbender. Please change the root password if you want to run a productive environment.

Warning

Do not delete the root user.

After a successful login you will be directed to the Backend.

Application overview

The Applications page displays a list of all available applications. The root user has access to the following functions:

• Title, URL title and description

• Preview screenshot for the application

• Filter textfield for application search

• Button to create new applications

• Button to show an application

• Button to duplicate an application

• Button to export an application

• Button to edit an application

• Button to make an application available for the public

• Button to delete an application

2. Create an application

There are three different options to create an application:

An application can be created out of an already existing one. This can be done via a click on in the application overview. The application will receive the same title and URL title with the appendix _imp, or _db (for yaml applications). All previously defined elements and configurations will be transferred as well.

Another possibility is the import of an application. Further information can be found under YAML Configuration (Configuration and Application files).

Furthermore, new applications can be created from scratch. The required steps are explained in the following:

1. Select the option New Application in the application overview.

2. After that, select a template in order to define the layout of your application. The options are: Fullscreen, Fullscreen alternative, Mapbender Mobile template. It is also possible to define your own template and assign it to a new application.

Tip

Please note that the style-, icon- and layout-configurations can be set up online via the CSS editor tab and/or via configuration files locally. Read more about template generation under How to create your own Template?.

1. Define a title, URL title and a description (optional). Title and URL title can be identical. However, the URL title has to follow the usual URL syntax: Typically, lowercase letters, numbers, as well as hyphens and underscores are allowed.

2. A thumbnail can be uploaded as well. It will appear next to the application title on the application overview page. For this, select Select File below the thumbnail section.

3. Set the checkmark at Persistent map state to make certain map parameters and configurations persistent. Further information can be found in Share elements.

4. Set the checkmark at Show Splashscreen to generate a loading screen on application startup that indicates the loading time.

5. Click Save to save and create your application. It is now possible to add elements (e.g. map, navigation bar, legend) and services to your applicaiton.

3. Add elements to your application

Mapbender applications consist of a Top toolbar, Sidepane, Map area and Footer. A variety of different elements can be added into these areas.

1. Choose Applications → → Layouts.

2. Click on to get an overview over the elements Mapbender provides.

Note

Mapbender provides different regions in your application. Not all elements can be added to all regions.

1. Choose an element from the list. Make sure to add the element to a region that makes sense.

2. Configure the element.

Note

When you select an element, for example Map, you see that the element has a set of attributes. Each element offers individual attributes for configuration.

1. You can change the position of an element via drag & drop within and between regions.

2. Have a look at your application. To open your application, click on .

Now you should have an idea about how easy it is to change a Mapbender application.

In the following, you find a complete list of all elements and their functionalities. For a more detailed description, please have a look at the corresponding chapters in the Table of Contents.

• About Dialog: Show information about Mapbender in an about dialog.

• Activity Indicator: Shows HTTP activity.

• Application Switcher: Switch to another application while maintaining the current map position.

• Button: Integrate another element as a button.

• Base source switcher: Change the map’s background sources.

• Coordinates Utility: Transform coordinates to different SRS and navigate to them on the map.

• Coordinates Display: Show the map coordinates of your mouse position.

• Copyright: Shows terms of use.

• Data Manager: Create and save information in a database.*

• Digitizer: Create and manage spatial data.*

• Dimensions handler: Manage sources with a time dimension.

• Image Export: Export the current map view (format options: .png or .jpeg)

• Legend: Displays legend of active themes on the map.

• Link: Links to an external URL.

• Layertree: Lists all included layer sets and layers with selection and sorting options.

• Map: Creates the map element in which layersets and layers are integrated into.

• Overview: Provides an overview map.

• POI: Create a POI for sharing.

• PrintClient: Renders a Print dialog.

• Line/Area Ruler: Enables to measure a line/area and display its length/area in a dialog.

• Scale Display: Displays the current map scale.

• Scale Bar: Displays a small line indicator representing the current map scale.

• Scale Selector: Displays and changes a map scale.

• Search Router: Enables a configurable search via SQL.

• Simple Search: Enables a configurable search on JSON sources (e.g. Solr).

• Simple Search: Enables a search.

• Sketches: Enables a drawing tool with different shapes.

• SRS Selector: Changes the map’s spatial reference system.

• Share URL: Share the current map view via URL.

• View Manager: Save map states for later restoration.

• WMS Loader: Load a WMS via a getCapabilities-Request.

Hint

Items marked with an asterisk (*) require additional dependencies.

4. Configure Sources

Mapbender can handle sources of the type OGC WMS or OGC WMTS / TMS. Via a click on Sources, you can navigate to an overview of all uploaded sources. There is a second list called Shared instances which only provides sources of the type shared. Further information about bound and shared instances can be found under Layerset.

Sources provides the following functions:

• add data source

• show data source

• update data source

• delete data source

• filter via text to search for sources

Load sources

Mapbender allows the integration of OGC Web Map Services (WMS) and Web Map Tile Services (WMTS). Versions 1.0.0 and 1.3.0. are supported. A source provides a XML when its getCapabilities document is requested. This information is then read by Mapbender: The client receives all necessary information about a source via this XML.

Tip

You should check your capabilities document in your browser before uploading the service.

1. To upload a source, click on Add source.

2. Define the Type of the source: OGC WMS or OGC WMTS / TMS.

3. In the field Service URL, provide the link to the getCapabilities URL.

4. Define username and password (in case your source requires it).

5. Click on Load to upload the service into the repository.

6. After a successful upload, Mapbender will provide an overview of the WMS information.

Add sources to an application

After uploading a service, it can be integrated into one or several application(s).

1. Navigate to Applications. Click on of the desired application and navigate to Layersets.

2. In Layersets you can integrate uploaded sources into your application. Click on next to the filter function to create a layerset. All layers have to be assigned to at least one layerset. Provide a name for it (e.g. main for the main map and overview for the overview map).

3. Now you can add layers to the layerset. Click on next to the desired layerset.

4. The order of the layers can be changed via drag & drop.

Source configuration

Sources can be individually configured. This can be useful if you, for instance, don’t want to display all layers, change the order or titles of the layers, prevent a layer’s feature info output or adjust the scale in which the layers are visible.

1. Click on Applications → → Layersets → Edit instance to configure an instance.

2. You can now change the instance configuration.

3. The order of the layers can also be changed via drag & drop.

Source configuration:

• Title: Name of the application.

• Opacity: Opacity in percentage (0: transparent, 100: opaque).

• Format: Format of the getMap-Requests.

• Infoformat: Format of the getFeatureInfo-Requests (text/html is recommended).

• Exceptionformat: Format for error messages.

• Tile buffer: This parameter is valid for tiles services and specifies if additional tiles should be requested. If the user pans the map, these tiles are already downloaded and visible. The higher the value the more tiles are requested (default: 0).

• BBOX Factor: This parameter is valid for non-tiled WMS services. You can specify the size of the returned map-image. A value greater than 1 will request a bigger map-image (default: 1.25).

• BaseSource: If active, the service is handled as a BaseSource. Should be activated for full-screen background maps, such as street maps and satellite images, and where a simultaneous display is not needed.

• Proxy: If active, the service will be requested by Mapbender and not directly. Should always be enabled for password-protected services, as otherwise the password will be readable by every user.

• Transparency: Default is active, the source is without a transparent background if it is deactivated (getMap-Request with Transparent=FALSE).

• Tiled: You can request a WMS in tiles, default is not tiled (may be a good choice if your map is very big and the WMS service does not support the width/height).

• Layer ordering: Handles the order of the layers in the service. Can be set to standard (reversed) and QGIS (same order).

Dimensions:

This function is relevant for sources with a time dimension. Further information can be found under Dimensions handler.

Vendor Specific Parameter:

You can define Vendor Specific Parameters in a layerset instance to add them to a WMS request. This principle follows Multi-Dimensions in the WMS specification.

You can use Vendor Specific Parameters in Mapbender to add the user and group information of the logged-in user to a WMS request. You can also add hard coded values.

List of the possible parameters:

• User: $email$, $groups$, $id$, $username$

• Groups: $id$, $title$, $description$

The following example shows the definition of the parameter groups, which transfers the group value of the logged-in user.

• Vstype: Mapbender specific variables. Group (groups), User (users), Simple

• Name: Parameter name of the WMS request

• Default: Default value

• Hidden: If this value is set, requests are send via a server so that the parameters are not directly visible. Only works if Proxy is enabled for the service, too.

Currently, the element can be used to transfer user- and group information, e.g. for a user the $id$ and for groups the value $group$.

Layer configuration:

• title: Layer title as shown in the layer tree. Default value is the getCapabilities requested title.

• min./max. scale: scale scope (e.g., 1:100-1:1000).

• active on/off: activates/deactivates a layer completely.

• select allow: layer is active when the application starts.

• select on: selectable in geodata explorer.

• info allow: layer info is active when the application starts.

• info on: layer provides feature info requests, info default activates the feature info functionality.

• toggle allowed: allows opening in the layer tree.

• toggle on: open folder on start of the application.

• more information (…): opens a dialog with detailed layer information.

  • ID: ID of the layer. Can be useful to control URL parameters.

  • Name: layer name of the service information (for getMap-Requests).

  • Style: if a WMS provides more than one style you can choose a different style than the default style.

5. User and group management

Access to Mapbender requires authentication. Only public applications can be used by everyone. A user can get permissions to access one or a set of applications and services.

Create a user

1. To create a user, go to Security → Users → Add new user.

2. Choose a name for your user.

3. Provide an email address for the user.

4. Choose a password for your user and repeat it in the Confirm password field.

5. Save your new user. It is still possible to alter user information later on.

You can provide more information about the user in the tab Profile. In the Groups and Security tabs it is possible to assign the user additional parameters, e.g. the membership to a group.

Create a group

1. Create a group by Security → Groups → Add new Group.

2. Define a name and a description for your group.

3. In the tab Users, assign users to your group.

4. Save your new group.

6. Rights management

Mapbender provides an easy-to-use rights management that is implemented into the backend.

• View: Select a user that is allowed to view an object (e.g., an application or a service).

• Create: Select a user that is allowed to create an object.

• Edit: Select a user that is allowed to make changes to an object.

• Delete: Select a user that is allowed to delete an object.

Hint

Assign rights to a user via Security → Global Permissions.

Assign an Application to a User/Group

1. Edit your application via Application → .

2. Choose Security.

3. Make your application accessable to the public by Security → Public Access. Alternatively, one can use Toggle public access.

4. Alternatively to public access, you can set permissions for specific users/groups:

Test your configuration. Logout from Mapbender by clicking Logout in the upper right corner. Login again as the new user.

Assign elements to a User/Group

Per default, all elements of an application are accessible to users and groups if they have access to that particular application. This can be modified for each element.

1. Edit your application by clicking Edit.

2. In your application settings, choose Layouts.

3. For every element, it is possible to Restrict element access.

4. Choose the Restrict element access from the element that should be only available for special users/groups.

5. Assign one or more users or groups to the element. Then, you can set a View permission for the specific users or groups.

6. Test your configuration.

7. Start an Application at a defined position

You can open an application at a defined location. This can be done by a POI. You also can add texts in the request.

You can pass one or more POIs in the URL. Each POI has the following parameters:

• point: coordinate pair with values separated by comma (mandatory)

• label: Label to display (optional)

• scale: Scale to show POI in (optional, makes only sense with one POI)

If you pass more than one POI, the map will zoom to 150 % of the POIs bounding.

To pass a single POI, use the following URL format:

• ?poi[point]=363374,5621936&poi[label]=Hello World&poi[scale]=5000

What’s next?

This is only the first step on the road to using Mapbender. There is a lot more to discover:

• Head over to the official Mapbender website,

• Find quick answers to the biggest Mapbender-related questions in the FAQ - Frequently Asked Questions,

• Become a member of the Mapbender community.