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 applicationstatic/mapstore
directory contains all the compiled static files used by GeoNode through the django_geonode_mapstore_client moduletemplates
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 viewersgn-components.js
used in the homepage to visualize the resources grid only. It could be used to create pages with custom resources girdgn-dashboard.js
dashboard viewer application for embedded pagesgn-document.js
document viewer application for embedded pagesgn-geostory.js
geostory viewer application for embedded pagesgn-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/
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.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 configurationcustom_theme.html
is 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.html
an empty page with the header and footer that can be extended with custom content