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:
clientdirectory contains all source code needed for the MapStore applicationstatic/mapstoredirectory contains all the compiled static files used by GeoNode through the django_geonode_mapstore_client moduletemplatesdirectory 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.jsmain application under the catalogue page which includes list of resources and application viewersgn-components.jsused in the homepage to visualize the resources grid only. It could be used to create pages with custom resources girdgn-dashboard.jsdashboard viewer application for embedded pagesgn-document.jsdocument viewer application for embedded pagesgn-geostory.jsgeostory viewer application for embedded pagesgn-map.jsmap/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.jsontranslations files for the geonode client are included in the
geonode_mapstore_client/static/mapstore/gn-translations/folderindex.json in the
geonode_mapstore_client/static/mapstore/extensions/folder is a placeholder to allow overrides for extensions plugin inside a geonode-projectgeonode_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.htmlis included in all the pages that contain a geonode-mapstore-client application and it allows the overriding and/or extension of the localConfig configurationcustom_theme.htmlis included in all the pages and allows the overriding and/or extension of the styles of the geonode-mapstore-client themesnippets/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 templatespage.htmlan empty page with the header and footer that can be extended with custom content