Static Files Customizations Overview¶

This session aims to explore and overview the static files that allows customization of MapStore.

Note: we strongly advise to create a downstream project of MapStore to keep track of commit history and for a better maintainability even if the changes described in this session will allow a complete customization (MapStore Project topic covered in MS3)

Setup¶

download latest MapStore release from https://github.com/geosolutions-it/MapStore2/releases (files: mapstore2-{version}-bin.zip and mapstore-printing.zip)
extract all the content of mapstore2-{version}-bin.zip and run mapstore2-startup.bat or mapstore2-startup.sh based on the OS in use
MapStore will start a url http://localhost:8082/mapstore
stop the container using mapstore2-shutdown.bat or mapstore2-shutdown.sh based on the OS in use
unzip the content of mapstore-printing.zip and copy as described below
- content of mapstore-printing/WEB-INF/classes to mapstore2-{version}-bin/mapstore2/webapps/mapstore/WEB-INF/classes
- content of mapstore-printing/WEB-INF/lib to mapstore2-{version}-bin/mapstore2/webapps/mapstore/WEB-INF/lib
run again the container with mapstore2-startup.bat or mapstore2-startup.sh based on the OS in use

Now MapStore is running with the print plugin installed

HTML files¶

MapStore is a single page application that uses following html files:

index.hml: page used for the main viewer
embedded.html: display a map viewer used for embedded page
dashboard-embedded-template.html: display a dashboard viewer used for embedded page
geostory-embedded.html: display a geostory viewer used for embedded page
unsupportedBrowser.html: application redirects to this page if the browser is not supported

We will temporary edit the index.html to include a custom css file

Include a custom.css file¶

create a new folder called assets inside mapstore2-{version}-bin/mapstore2/webapps/mapstore/ directory
create a new file called custom.css inside mapstore2-{version}-bin/mapstore2/webapps/mapstore/assets/css/custom.css with the following content

/*
test to verify the correct import of custom.css
main navbar should become dark
*/
#mapstore-navbar-container {
    background-color: #333333;
}

open the mapstore2-{version}-bin/mapstore2/webapps/mapstore/index.html file and add the following stylesheet

<head>
    ...
+    <link rel="stylesheet" href="assets/css/custom.css" />
</head>

reload the MapStore page and verify if the navbar changed color. If so the custom.css is ready to be used for theme customization

Make a new theme with css variables¶

MapStore theme is using CSS variables so it is possible to override them by creating a new selector that declare new colors per variable. Steps to overrides theme colors:

replace the content of custom.css file with:

:root {
    --ms-main-bg: #333333;
    --ms-main-color: #f2f2f2;
}

reload the mapstore application. Now the background will use the new dark color with a contrast white text.

This customization is not complete yet because there are still some missing some variables: primary, success, main variant, link color, … .

Here a tool that helps to generates a css snippet with all the theme variables based on a set of input colors. After applied your favorite colors copy the generated style in the custom.css file.

Jumbotron image¶

Jumbotron image in the homepage is currently provided as a css background image so it’s possible override it using the same selector with a different image. We suggest to use an image that fit the width and height of the jumbotron to minimize the size of the file (eg: 1920px x 300px)

create an img folder inside the assets one
add the selected image as jumbotron in the assets/img folder or copy the following one

background image for the MapStore jumbotron

original image source https://unsplash.com/photos/ZvLvu1gUcYA

add the following rule to the custom.css file

.ms2 #container .page-maps .ms-home-description {
    background-image: url('../img/jumbotron.jpg');
    background-size: cover;
    background-position: center;
}
/* (optional) additional changes to the jumbotron text and overlay */
.ms2 #container .page-maps .ms-home-description .container {
    background-color: transparent;
    font-weight: bold;
    color: #ffffff;
}

Remove plugins via localConfig.json¶

The localConfig.json is the main configuration used by MapStore to manage different options including the structure of plugins in the different pages. We need to remove some default plugins from the homepage, here the steps:

open the localConfig.json file inside the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/ folder
remove “Fork” and “MailingLists” from the plugins.maps list of plugins

Now the “Fork me on GitHub” link and the mailing list section in the homepage are not visible anymore

Logo¶

The logo can be updated by changing a configuration in localConfig.json.

copy this file and copy it inside the mapstore2-{version}-bin/mapstore2/webapps/mapstore/assets/img folder

edit all the instance of “Attribution” plugin inside the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/localConfig.json file with the new configuration for the header logo

{
    "name": "Attribution",
    "cfg": {
        "label": "My Tooltip Description",
        "href": "#",
        "src": "assets/img/logo.svg"
    }
},

edit all the instance of “Footer” plugin inside the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/localConfig.json file with the new configuration for the footer logo

{
    "name": "Footer",
    "cfg": {
        "logo": {
            "src": "assets/img/logo.svg",
            "width": "auto",
            "height": "auto",
            "href": "#",
            "title": "Logo title",
            "alt": "Logo alt"
        }
    }
},

Homepage title¶

The title of the Homepage is defined as name variable inside the HomeDescription plugin. Each plugin allows to override the with a cfg object. We need to change the maps plugin list as follow to display the new title

edit “HomeDescription” plugin inside the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/localConfig.json file with the new jumbotron title

"maps": [
    {
        "name": "HomeDescription",
        "cfg": {
            "name": "My New Title"
        }
    },

Locales¶

edit “locales” section inside the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/localConfig.json file with the new list of supported locales

"locales": {
    "supportedLocales": {
        "it": {
            "code": "it-IT",
            "description": "Italiano"
        },
        "en": {
            "code": "en-US",
            "description": "English"
        }
    }
}

Translations¶

create a new folder called translations inside the assets folder (mapstore2-{version}-bin/mapstore2/webapps/mapstore/assets/translations)
create a new file for the english translations overrides with the following content (mapstore2-{version}-bin/mapstore2/webapps/mapstore/assets/translations/data.en-US.json)

{
    "locale": "en-US",
    "messages": {
        "home": {
            "shortDescription": "My custom MapStore GeoPortal",
            "footerDescription": "MapStore Training"
        }
    }
}

create a new file for the italian translations overrides with the following content (mapstore2-{version}-bin/mapstore2/webapps/mapstore/assets/translations/data.it-IT.json)

{
    "locale": "it-IT",
    "messages": {
        "home": {
            "shortDescription": "Il mio GeoPortale MapStore personalizzato",
            "footerDescription": "MapStore Training"
        }
    }
}

add “translationsPath” property inside the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/localConfig.json file including new translations path

"translationsPath": [ "translations", "assets/translations" ],

Context themes¶

create a new theme called new-theme.css inside mapstore2-{version}-bin/mapstore2/webapps/mapstore/assets/css using the theme tool
add “themes” configuration to “ContextCreator” plugin inside the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/localConfig.json file

{
    "name": "ContextCreator",
    "cfg": {
        ...
        "themes": [
            {
                "id": "new-theme",
                "type": "link",
                "href": "assets/css/new-theme.css",
                "defaultVariables": {
                    "ms-main-color": "#000000",
                    "ms-main-bg": "#FFFFFF",
                    "ms-primary-contrast": "#FFFFFF",
                    "ms-primary": "#078aa3",
                    "ms-success-contrast": "#FFFFFF",
                    "ms-success": "#398439"
                }
            }
        ],
        "basicVariables": {
            "ms-main-color": "#000000",
            "ms-main-bg": "#FFFFFF",
            "ms-primary-contrast": "#FFFFFF",
            "ms-primary": "#078aa3",
            "ms-success-contrast": "#FFFFFF",
            "ms-success": "#398439"
        }
    }
},

Printing configuration¶

replace the layout header by replacing the mapstore2-{version}-bin/mapstore2/webapps/mapstore/printing/print_header.png with the following image

replace the north arrow by replacing the mapstore2-{version}-bin/mapstore2/webapps/mapstore/printing/Arrow_North_CFCF.svg with the following image

other additional configuration on the layouts are available at https://mapfish.github.io/mapfish-print-doc/attributes.html

New map configuration¶

replace initial “center” position for new map in the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/new.json file

"center": {
    "x": 11.2558136,
    "y": 43.7695604,
    "crs": "EPSG:4326"
},

replace initial “zoom” level for new map in the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/new.json file

"zoom": 7,

replace initial base map “layers” for new map in the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/new.json file

"layers": [
    {
        "type": "osm",
        "title": "Open Street Map",
        "name": "mapnik",
        "source": "osm",
        "group": "background",
        "visibility": true
    },
    {
        "source": "ol",
        "group": "background",
        "title": "Empty Background",
        "fixed": true,
        "type": "empty",
        "visibility": false,
        "args": [
            "Empty Background",
            {
            "visibility": false
            }
        ]
    }
]

add a specific set of scales for new map in the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/new.json file

"mapOptions": {
    "view": {
        "scales": [175000, 125000, 100000, 75000, 50000, 25000, 10000, 5000, 2500]
    }
},

add a extent constraint for all the map in the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/localConfig.json file

"mapConstraints": {
    "crs": "EPSG:4326",
    "restrictedExtent": [ 6.62, 37.86, 18.58, 47.1 ]
},

New GeoStory configuration

replace default geostory initial theme with a custom by editing mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/newgeostory.json file

"settings": {
    "theme": {
        "general": {
            "color": "#ffffff",
            "backgroundColor": "#333333",
            "borderColor": "#777777"
        },
        "overlay": {
            "backgroundColor": "rgba(0, 0, 0, 0.75)",
            "borderColor": "#777777",
            "boxShadow": "0 14px 28px rgba(0,0,0,0.25), 0 10px 10px rgba(0,0,0,0.22)",
            "color": "#ffffff"
        }
    }
},

Catalog Configuration¶

replace the default Catalog services by editing the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/localConfig.json file for global and DashboardEditor configurations

"selectedService": "local_wms",
"services": {
    "local_wms": {
        "url": "http://localhost:8080/geoserver/wms",
        "type": "wms",
        "title": "Local GeoServer WMS",
        "autoload": true
    }
},

if needed add the new catalog url to the useCORS list to ensure the client send direct request the service. This configuration is inside the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/localConfig.json file

"proxyUrl": {
    "url": "proxy/?url=",
    "useCORS": [
        ...other urls,
        "http://localhost:8080/geoserver/wms"
    ]
},

Map projections¶

MapStore allows to add new projection that can be used in the OpenLayers map viewer. The def property of the projection should be described as a proj4js definition

add this configuration inside the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/localConfig.json file to include the EPSG:3003 and EPSG:3004 projection

"projectionDefs": [
    {
        "code": "EPSG:3003",
        "def": "+proj=tmerc +lat_0=0 +lon_0=9 +k=0.9996 +x_0=1500000 +y_0=0 +ellps=intl +towgs84=-104.1,-49.1,-9.9,0.971,-2.917,0.714,-11.68 +units=m +no_defs",
        "extent": [1241482.0019, 973563.1609, 1830078.9331, 5215189.0853],
        "worldExtent": [6.6500, 8.8000, 12.0000, 47.0500]
    },
    {
        "code": "EPSG:3004",
        "def": "+proj=tmerc +lat_0=0 +lon_0=15 +k=0.9996 +x_0=2520000 +y_0=0 +ellps=intl +towgs84=-104.1,-49.1,-9.9,0.971,-2.917,0.714,-11.68 +units=m +no_defs",
        "extent": [1782205.39, 4223533.54, 2791665.11, 5222517.32],
        "worldExtent": [6.62, 37.86, 18.58, 47.1]
    }
],

add new crs to the list of the available ones to the CRSSelector plugin inside the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/localConfig.json

"additionalCRS": {
    "EPSG:3003": {
        "label": "EPSG:3003"
    },
    "EPSG:3004": {
        "label": "EPSG:3004"
    }
}

Note: projection definition could be retrieved at https://epsg.io/

3D Terrain¶

MapStore allows to configure a custom terrain provider that could be provided as wms layer from GeoServer in the application/bil16.

setup a layer in GeoServer that support application/bil16 format by using the DSS/BIL plugin (see https://mapstore.readthedocs.io/en/latest/developer-guide/maps-configuration/#special-case-the-elevation-layer)
add following configuration to the Map plugin using the url and name for the terrain layer previously configured in GeoServer by editing the mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/localConfig.json file

"additionalLayers": [
    {
        "url": "http://localhost:8080/geoserver/wms",
        "type": "wms",
        "format": "application/bil16",
        "name": "etopo:ETOPO1",
        "littleendian": false,
        "visibility": true,
        "useForElevation": true
    }
],

Annotation Symbols¶

clean up of the svg icon remove style inside the file svg

copy the logo.svg file inside the mapstore2-{version}-bin/mapstore2/webapps/mapstore/product/assets/symbols folder
edit the mapstore2-{version}-bin/mapstore2/webapps/mapstore/product/assets/symbols/symbols.json file to include only the following icons

[
    {"name": "triangle", "label": "Triangle"},
    {"name": "logo", "label": "Logo"}
]

Note: ensure the the new svg symbol does not contain inline style to allow the annotation editor to apply custom colors

Conclusion¶

We covered the most common customization and configuration available via static files in MapStore. The following documentation provides additional configuration that could be applied to the app or to single plugins:

Developer guide https://mapstore2.readthedocs.io/en/user_docs/developer-guide/
Plugin available configuration https://mapstore.geosolutionsgroup.com/mapstore/docs/api/plugins

We advise to copy all the changed file in a MapStore project or in a separate repository to avoid an override in the next mapstore.war update.

MapStore Training documentation

Table of Contents

Previous topic

Next topic

This Page

Static Files Customizations Overview¶

Setup¶

HTML files¶

Include a custom.css file¶

Make a new theme with css variables¶

Jumbotron image¶

Remove plugins via localConfig.json¶

Logo¶

Homepage title¶

Locales¶

Translations¶

Context themes¶

Printing configuration¶

New map configuration¶

Catalog Configuration¶

Map projections¶

3D Terrain¶

Annotation Symbols¶

Conclusion¶

MapStore Training documentation

Static Files Customizations Overview¶

Setup¶

HTML files¶

Include a custom.css file¶

Make a new theme with css variables¶

Jumbotron image¶

Remove plugins via localConfig.json¶

Logo¶

Homepage title¶

Locales¶

Translations¶

Context themes¶

Printing configuration¶

New map configuration¶

Catalog Configuration¶

Map projections¶

3D Terrain¶

Annotation Symbols¶

Conclusion¶

Navigation