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 .. code-block:: css /* 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 .. code-block:: diff ... + - 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: .. code-block:: css :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 <../_static/theme-tool.html>`_ 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 .. figure:: ./img/jumbotron.jpg :alt: background image for the MapStore jumbotron original image source https://unsplash.com/photos/ZvLvu1gUcYA - add the following rule to the custom.css file .. code-block:: css .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 .. figure:: ./img/logo.svg :width: 64 :alt: logo image for the training - 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 .. code-block:: json { "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 .. code-block:: json { "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 .. code-block:: json "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 .. code-block:: json "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``) .. code-block:: 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``) .. code-block:: 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 .. code-block:: json "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 <../_static/theme-tool.html>`_ - add "themes" configuration to "ContextCreator" plugin inside the ``mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/localConfig.json`` file .. code-block:: json { "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 .. figure:: ./img/print_header.png :alt: 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 .. figure:: ./img/Arrow_North_CFCF.svg :width: 64 :alt: 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 .. code-block:: json "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 .. code-block:: json "zoom": 7, - replace initial base map "layers" for new map in the ``mapstore2-{version}-bin/mapstore2/webapps/mapstore/configs/new.json`` file .. code-block:: json "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 .. code-block:: json "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 .. code-block:: json "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 .. code-block:: json "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 .. code-block:: json "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 .. code-block:: json "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 .. code-block:: json "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`` .. code-block:: 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 .. code-block:: json "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 .. code-block:: json [ {"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.