This quick start prepares your working environment for GBC customization development.

Prerequisites

You need some tools installed on your system:

Node.js the LTS version (12.x.x) is recommended with python 2.7
git

Under Windows, you can directly install proper nodejs, npm and python versions by using nvm :

Download and install nvm

Then run commands :

Note that versions displayed below may be out of date because Node.js and npm evolve each month. The basic rule is to pick the LTS version of Node.js including the latest recommended npm.

$ nvm list available 
|   CURRENT    |     LTS      |  OLD STABLE  | OLD UNSTABLE |
|--------------|--------------|--------------|--------------|
|    14.11.0   |   12.18.4    |   0.12.18    |   0.11.16    |
...
$ nvm install 12.18.4
$ nvm use 12.18.4

Follow the instructions provided by the tools to install them on your system. Once the installation is complete, you should have the following tools available from the command line:

$ node -v
v12.18.4
$ npm -v
6.14.6

You need to master these command line tools in order to work on GBC customization.

Next, install grunt using the npm tool. From the console, execute the following command:

$ npm install -g grunt-cli

You must have internet access.

You may need super user rights on your system.

Unless you reinstall node.js or a new version of grunt-cli is required, this command is only needed once.

Your environment is now ready.

Setup your customization project

Get the latest GBC project package from the Four Js Products download area and extract it to a location of your choosing. We will refer to this location (where you extract the package) as the gbc-project-dir throughout this documentation.

Next, prepare your working copy:

$ cd $GBC_PROJECT_DIR
$ npm install

you must have internet access

Run this command whenever you get a new version of the project package

Finally, execute the default compilation:

$ grunt

The gbc-project-dir/dist/customization/sample folder is created. It contains the compiled version of the GBC with the provided customization sample defined in gbc-project-dir/customization/sample.

Test using the standalone GAS

To test your newly built customization, you need to run the standalone GAS by executing the following command:

$ httpdispatch -E res.path.gbc.user=<gbc-project-dir>/dist/customization

Launch the Genero Workplace Window to ensure an environment suitable for Genero commands (such as httpdispatch).

It can very helpful to add the following arguments to the httpdispatch command:

-E res.log.output.type=CONSOLE,DAILYFILE

-E res.log.categories_filter=ALL

Use a dedicated console to run the httpdispatch command. This allows you to rebuild your GBC customization without needing to re-execute httpdispatch afterwards.

The resource res.path.gbc.user amends the default GBC_LOOKUP_PATH. To run a given application using a given customization, amend the application URL with the query string parameter gbc=customization_name.

For example, in order to run the Genero demo with the default customization (named sample) that was built earlier in this procedure, open the following URL in your prefered browser:

http://localhost:6394/ua/r/gwc-demo?gbc=sample

Build a project continuously

To make the development cycle quicker, there is a built-in rule that will watch for any modifications in your customization, then immediately rebuild the customization when modifications are detected. To use this rule, execute the following command from a dedicated command prompt:

$ grunt dev

You will need to refresh your browser once compilation completes.

Use a dedicated console, as this is designed to run permanently. It will not return to the command prompt.

Depending on your operating system, it is advised to abort and re-run the command if you add new files.

Create your own customization project

To create a new customization project, see Create a new customization project.