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/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

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
logo image for the training
  • replace the north arrow by replacing the mapstore2-{version}-bin/mapstore2/webapps/mapstore/printing/Arrow_North_CFCF.svg with the following image
logo image for the training

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.

"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:

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.