G3W-CLIENT v3.11.0-alpha.1

G3W-SUITE scripts and configuration files needed to set up a suitable local development enviroment for the g3w-client cartographic viewer.

---

Project setup

Download and install Node.js and NPM and Docker Compose in your development enviroment.

Clone and place the g3w-suite-docker, g3w-admin and g3w-client repositories into three separated adjacent folders:

cd /path/to/your/development/workspace

git clone https://github.com/g3w-suite/g3w-suite-docker.git --single-branch --branch dev ./g3w-suite-docker
git clone https://github.com/g3w-suite/g3w-admin.git --single-branch --branch dev ./g3w-admin
git clone https://github.com/g3w-suite/g3w-client.git --single-branch --branch dev ./g3w-client

Download all javascript and docker dependencies from within your g3w-client local repository:

cd ./g3w-client

npm install         # javascript dependencies (client)

npm run docker pull # docker dependencies (admin)

Create these configuration files from the available templates:

• /g3w-client/config.js ← config.template.js
• /g3w-suite-docker/.env ← .env.example
• /g3w-suite-docker/config/g3w-suite/settings_docker.py ← settings_docker.py
• /g3w-suite-docker/shared-volume/ ← add this folder if it doesn't exist

And check that the following parameters are set as follows:

# /g3w-suite-docker/.env

WEBGIS_DOCKER_SHARED_VOLUME=./shared-volume # path to docker container shared volume
G3WSUITE_LOCAL_CODE_PATH=../g3w-admin       # path to local g3w-admin folder
G3WSUITE_DEBUG=True                         # default: False

Now your folder structure should matches this one:

.
├── g3w-admin/
│
├── g3w-client/
│   ├── node_modules/
│   ├── package.json
│   ├── package-lock.json
│   └── config.js
│
└── g3w-suite-docker/
    ├── config/
    │   └── g3w-suite/
    │       └── settings_docker.py
    ├── shared-volume/
    ├── scripts/
    │   └── docker-entrypoint-dev.sh
    ├── .env
    ├── docker-compose-dev.yml
    └── README_DEV.md
    

For more info about this project dependencies see:

• package.json
• docker-compose-dev.yml

---

How to develop

From within your g3w-client local repository:

cd ./g3w-client

You can start the built-in development servers by using the following:

npm run docker:up      # backend server   (g3w-admin)

npm run dev            # frontend server  (g3w-client)

If everything went fine, you can now visit you local development server URL to see changes, the following rules are applied:

# EXAMPLE 1:
# project_group = "countries";
# project_type  = "qdjango";
# project_id    = "1"

http://localhost:8000/en/map/countries/qdjango/1 # g3w-admin  (production)
http://localhost:3000/en/map/countries/qdjango/1 # g3w-client (development)

# EXAMPLE 2:
# project_group = "eleprofile";
# project_type  = "qdjango";
# project_id    = "2"

http://localhost:8000/en/map/eleprofile/qdjango/2 # g3w-admin  (production)
http://localhost:3000/en/map/eleprofile/qdjango/2 # g3w-client (development)

Plugins

If you want develop client plugins you need place them in the src/plugins folder:

.
└── src/
    └── plugins/
        ├── base
        ├── eleprofile
        ├── sidebar
        └── ...

Update your config.js file accordingly:

// overrides global `window.initConfig.group.plugins` property for custom plugin development

const G3W_PLUGINS = [
  'base',
  'eleprofile',
  'sidebar',
  ...
];

And then start again the development servers:

npm run docker:up      # backend server (g3w-admin)
npm run dev            # frontend server (g3w-client)

For further information about plugin development, see also: src/plugins/README.md

Publish

1. Releasing a new version of G3W-CLIENT

• Ensure all milestones issues and pull requests are resolved.
• Create or checkout to a new appropriate branch: (eg. v3.5.x when bumping code from 3.5.0 to 3.5.1)
• Compile and create new tag: npm version v3.5.1
• Draft a new GitHub Relase

1.1 git tag usage

Listing local tags:

git tag

Add a new tag:

git tag v3.5

Update an existing tag:

git tag -f v3.5

Delete an existing tag:

git tag -d v3.5

Publish a local tag:

git push origin v3.5

Publish all local tags:

git push --tags

---

Fore more info:

• https://www.atlassian.com/git/tutorials/inspecting-a-repository/git-tag

2. Updating G3W-ADMIN after the release

• Create a new branch from client release zip archive: https://github.com/g3w-suite/g3w-client/releases
• Create a new PR with title: ⬆️ Bump g3w-client from <old_version> to <new_version>
• Add the dependencies label
• Add a link to changelog page in PR description (eg: **g3w-client: [v3.8.10](https://github.com/g3w-suite/g3w-client/releases/tag/v3.8.10)**)

---

FAQ

1. How can I start or stop docker containers?

For those unfamiliar with docker development docker-compose is a tool for defining and running multi-container applications.

Below are described the most frequent commands, that are also available here in this repository as npm scripts, you can find similar information by running npm run from the command line.

Define and run the services that make up the g3w-client (admin) development server:

docker
  docker compose --env-file ../g3w-suite-docker/.env --file ../g3w-suite-docker/docker-compose-dev.yml --project-name g3w-suite-docker --project-directory ../g3w-suite-docker

Create and start containers (run default admin server at localhost:8000):

docker:up
  npm run docker up -- -d

Stop and remove containers, networks, images, and volumes:

docker:down
  npm run docker down

Validate and view the Compose file (load and parse docker-compose-dev.yml and .env variables):

docker:config
  npm run docker config

View output from containers:

docker:logs
    npm run docker logs

For more info:

• Overview of docker-compose CLI

2. How can I inspect actual docker configuration?

If you are having trouble with your current project configuration you can use the docker config command to inspect the actual values of the variables passed to your docker container:

npm run docker config

If your container struggles to boot properly you can also use the docker logs command related to a specific container:

npm run docker logs g3w-suite -- -f
npm run docker logs postgis -- -f

For more info:

• Overview of g3w-suite dockerization

3. How can I keep client plugins updated ?

Currently built-in and custom plugins are managed with several "independent" git repositories, so there is currently no automated task to achieve this.

You can use the following commands to fetch the latest changes of built-in plugins:

cd /g3w-client/src/plugins/editing

git pull editing

cd /g3w-client/src/plugins/openrouteservice

git pull openrouteservice

cd /g3w-client/src/plugins/qplotly

git pull qplotly

cd /g3w-client/src/plugins/qtimeseries

git pull qtimeseries

If you are looking for an alternative workflow, also try to take a look at git submodules or git subtrees

4. How can I add a custom item to main menu?

Example, adding a custom link to "change map" modal:

You can achieve this through the following python setting:

# g3w-suite-docker/config/g3w-suite/settings_docker.py

G3W_CLIENT_HEADER_CUSTOM_LINKS = [{
  "i18n":   True,
  "icon":   "fas fa-sync-alt",
  "title":  "changemap",
  "type":   "modal",
  "target": "#modal-changemap"
}]

which is roughly equivalent to:

// path/to/your/custom.js

g3wsdk.core.ApplicationService.once('initconfig', () => {
  initConfig.header_custom_links = [{
    "i18n":   true,
    "icon":   "fas fa-sync-alt",
    "title":  "changemap",
    "type":   "modal",
    "target": "#modal-changemap"
  }];
});

For more info: G3W_CLIENT_HEADER_CUSTOM_LINKS

5. How can I translate this project?

Depending on your current project version, you can edit one of the following files and then submit a pull request:

• /g3w-client/src/locales/ (> v3.4)
• /g3w-client/src/config/i18n/index.js (<= v3.4)

Changelog

All notable changes to this project are documented in the releases page.

---

Compatibile with:

---

License: MPL-2