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/
|    |-- 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-components.js
|         |    |-- gn-dashboard.js
|         |    |-- gn-document.js
|         |    |-- gn-geostory.js
|         |    +-- 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-components.js used in the homepage to visualize the resources grid only. It could be used to create pages with custom resources gird

  • 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-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/static/mapstore/gn-translations/ folder

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

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

geonode_mapstore_client/
|-- ...
|-- static/
|    |-- ...
|    +-- mapstore/
|    |    |-- configs/
|    |    |    |-- ...
|    |    |    +-- localConfig.json
|    |    |-- extensions/
|    |    |    |-- ...
|    |    |    +-- index.json
|    |    |-- gn-translations/ (custom translations for the geonode client)
|    |    |    |-- ...
|    |    |    |-- data.de-DE.json
|    |    |    |-- data.en-US.json
|    |    |    |-- data.es-ES.json
|    |    |    |-- data.fr-FR.json
|    |    |    +-- data.it-IT.json
|    |    |-- img/
|    |    |-- ms-translations/ (from the MapStore2 submodule, this should not be edited)
|    |    +-- symbols/
|-- ...

Important!: The ms-translations is a copy of the MapStore core translations and they will be replaced every new build of the client. Fixes or additions to those files should be contributed directly to the MapStore2 repository and then inherits by the GeoNode MapStore client via submodule update.

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-components.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: Add a new plugin extension