Structure of the client: directories and files

The structure of the geonode_mapstore_client module is an important part of this documentation because most of the customization done inside geonode-project are overrides based on the location of the files. These are the main groups of the module:

  • client directory contains all source code needed for the MapStore application

  • static/mapstore directory contains all the compiled static files used by GeoNode through the django_geonode_mapstore_client module

  • templates directory contains all the html django templates used by the client interface

geonode_mapstore_client/
|-- ...
|-- client/
|    |-- ...
|    |-- js/
|    |-- MapStore2/
|    |-- static/
|    |    +-- mapstore/
|    |         |-- ...
|    |         +-- translations/
|    |-- themes/
|    |    +-- geonode/
|    |-- ...
|    |-- .env.sample
|    |-- package.json
|    +-- version.txt
|-- static/
|    |-- ...
|    +-- mapstore/
|    |    |-- ...
|    |    |-- configs/
|    |         +-- localConfig.json
|    |    |-- dist/
|    |         +-- ... 
|    |    |-- extensions/
|    |         +-- index.json
|    |    |-- gn-translations/
|    |    |-- img/
|    |    |-- ms-translations/
|    |    |-- symbols/
|    |    +-- version.txt
|-- templates/
|    +-- geonode-mapstore-client/
|-- ...

Javascript files

The geonode_mapstore_client/client/js/ folder contains all the javascript and jsx files needed to build the application. This folder is targeted by babel loader so it’s possible to use javascript es6 features inside .js and .jsx files. These files are compiled with the npm run compile script, and the bundle is copied in the static/mapstore/dist directory to be available from GeoNode templates.

The name of the folders follows the directories and files naming convention defined by MapStore.

The directories are organized by their function:

  • actions

  • api

  • components

  • epics

  • hooks

  • observables

  • plugins

  • reducers

  • routes

  • utils

  • …

while the files should be related to a specific plugin name unless they are generic ones.

eg. The Save plugin will have a name like plugins/Save.jsx, utils/SaveUtils.jsx, actions/save.js, reducers/save.js, epics/save.js and so on.

Below is the structure of the geonode_mapstore_client/client/js/ folder:

geonode_mapstore_client/
|-- ...
|-- client/
|    |-- ...
|    +-- js/
|         |-- ...
|         |-- actions/
|         |-- api/
|         |-- apps/
|         |    |-- gn-catalogue.js
|         |    |-- gn-dashboard.js
|         |    |-- gn-document.js
|         |    |-- gn-geostory.js
|         |    |-- gn-home.jsx
|         |    +-- gn-map.js
|         |-- components/
|         |-- epics/
|         |-- hooks/
|         |-- map/
|         |-- observables/
|         |-- plugins/
|         |-- reducers/
|         |-- routes/
|         |-- selector/
|         +-- utils/
|
... -> compiled in
|
|-- static/
|    |-- ...
|    +-- mapstore/
|    |    +-- dist/

The files included inside geonode_mapstore_client/client/js/apps/ represent the entry points of the applications provided by the core implementation of the client. Each file included in js/apps/ is automatically detected and compiled by the build process as an application entry point. Eg. geonode_mapstore_client/client/js/apps/gn-geostory.js will become a gn-geostory.js file in the dist folder.

  • gn-catalogue.js main application under the catalogue page which includes list of resources and application viewers

  • gn-dashboard.js dashboard viewer application for embedded pages

  • gn-document.js document viewer application for embedded pages

  • gn-geostory.js geostory viewer application for embedded pages

  • gn-home.jsx homepage catalog rendered under the main hero title

  • gn-map.js map/dataset viewer application for embedded pages

Theme file

The geonode_mapstore_client/client/themes/ folder contains all the .less files needed to compile the MapStore theme with additional customization. Each theme should be placed inside a folder named as the final expected css file and provide a file theme.less as entry point:

eg. geonode_mapstore_client/client/themes/my-theme/theme.less will become a my-theme.css file in the dist folder.

geonode-mapstore-client provides one main theme called geonode.css

geonode_mapstore_client/
|-- ...
|-- client/
|    |-- ...
|    +-- themes/
|         |-- ...
|         +-- geonode/
|              |-- less/
|              +-- theme.less
|
... -> compiled in
|
|-- static/
|    |-- ...
|    +-- mapstore/
|    |    +-- dist/
|    |         +-- geonode.css
|-- ...

The language used for the styles is lesscss and it’s compatible with the MapStore theme.

Configurations files

The MapStore application needs configurations to load the correct plugins or enable/disable/change functionalities.

We need to provide following configuration files:

  • apps and plugins configurations is centralized in localConfig.json

  • translations files for the geonode client are included in the geonode_mapstore_client/client/static/translations/ folder

  • index.json in the geonode_mapstore_client/client/static/extensions/ folder is a placeholder to allow overrides for extensions plugin inside a geonode-project

  • geonode_mapstore_client/client/static/symbols/ folder provides all the icons needed for the annotation plugin

geonode_mapstore_client/
|-- ...
|-- client/
|    |-- ...
|    |-- static/
|    |    +-- mapstore/
|    |         |-- configs/
|    |         |    |-- ...
|    |         |    |-- localConfig.json
|    |         |-- extensions/
|    |         |-- img/
|    |         |-- symbols/
|    |         +-- translations/
|    |              |-- ...
|    |              |-- data.de-DE.json
|    |              |-- data.en-US.json
|    |              |-- data.es-ES.json
|    |              |-- data.fr-FR.json
|    |              +-- data.it-IT.json
|    |-- ...
|
... -> compiled in
|
|-- static/
|    |-- ...
|    +-- mapstore/
|    |    |-- gn-translations/ (from client folder translations)
|    |    |-- configs/
|    |    |    +-- localConfig.json
|    |    +-- ms-translations/ (from the MapStore2 submodule)
|-- ...

Important!: The geonode_mapstore_client/static/mapstore/ is the directory with all the final files generated after running the npm run compile script inside the geonode_mapstore_client/client/ folder. Every new file needed in the geonode_mapstore_client/static/mapstore/ must be placed inside the geonode_mapstore_client/client/static/mapstore/ directory then the npm run compile will move all the needed files into the final destination including the statics.

HTML templates files

The HTML templates are the pages performing the MapStore client integration.

Each template has its own configuration based on the resource type: dataset, map, document or app; and for a specific purpose: view, edit or embed.

geonode_mapstore_client/
|-- ...
|-- templates/
|    |-- documents/
|    |    |-- ...
|    |    +-- document_embed.html (it uses gn-document.js app)
|    |-- geonode-mapstore-client/
|    |    |-- ...
|    |    |-- legacy/ (deprecated template snippets)
|    |    |-- snippets/
|    |    |    |-- ...
|    |    |    |-- brand_navbar.html
|    |    |    |-- custom_theme.html
|    |    |    |-- footer.html
|    |    |    |-- header.html
|    |    |    |-- hero.html
|    |    |    |-- language_selector.html
|    |    |    |-- loader.html
|    |    |    |-- loader_style.html
|    |    |    |-- menu_item.html
|    |    |    |-- menu_item_compact.html
|    |    |    |-- search_bar.html
|    |    |    +-- topbar.html
|    |    |-- _geonode_config.html
|    |    |-- catalogue.html (it uses gn-catalogue.js app)
|    |    |-- dashboard_embed.html (it uses gn-dashboard.js app)
|    |    |-- dataset_embed.html (it uses gn-map.js app)
|    |    |-- geostory_embed.html (it uses gn-geostory.js app)
|    |    +-- map_embed.html (it uses gn-map.js app)
|    |-- base.html
|    |-- index.html (it uses gn-home.js app)
|    +-- page.html
|-- ...

Some notes on templates structure and files

  • _geonode_config.html is included in all the pages that contain a geonode-mapstore-client application and it allows the overriding and/or extension of the localConfig configuration

  • custom_theme.html is included in all the pages and allows the overriding and/or extension of the styles of the geonode-mapstore-client theme

  • snippets/ folder contains all the common parts of the pages such as header, footer, … . This structure simplifies the overriding of a snippet with a geonode-project taking advantage of the django templates

  • page.html an empty page with the header and footer that can be extended with custom content

Next Section: Setup of a GeoNode project to test the available customizations