GBC 4.01
Customization
How customization works
Planning for the customization Getting the customization to the user
Set up your GBC build environment Create a customization project Rebuild the GBC
Create a runtime package Deploy on GAS Deploy on JGAS Change the version customization suffix
Manage themes
Add a theme part Add a theme Modify a theme Delete a theme
Replace an image
Change the favicon Change background image for empty tabbed container
Use theme variables
Display or hide the sidebar Customize the chromebar Change checkbox icons Display the Genero context menu Change relog prompt
Use style sheets
Center progress indicator icon Center file loading icon
Use widgets
Add header image Add header image using style class Add header text Add footer text Change file loading icon Redirect application end Extend the MainContainerWidget
Internationalize your app
Add localized text Configure right-to-left languages Customize translation text Default encoding
Migrating customizations
Set up your GBC build environment

Before you customize GBC, you need to prepare your working environment. Preparing your environment starts with the installation of third-party software, then with the download and preparation of the GBC project package.

Required third-party software

You need these tools on your system:

  • Node.js - You can install Node.js directly, or you can use NVM (Node Version Manager) to install Node.js. To use NVM, see the instructions below.
  • git
  • Python - Python is a required dependency by some of the tools used to build customizations. Python 2.7 is required.

Using NVM to install and manage Node.js

For many, NVM is a useful tool for the installation and management of versions of Node.js.

  1. Download and install NVM.
  • For Windows, see here.
  • For MacOS and Linux, see here.
  1. Use the "nvm list available" command to identify the latest LTS (long-term support) version.
$ nvm list available
|   CURRENT    |     LTS      |  OLD STABLE  | OLD UNSTABLE |
|--------------|--------------|--------------|--------------|
|    16.0.0    |   14.16.1    |   0.12.18    |   0.11.16    |
|    15.14.0   |   14.16.0    |   0.12.17    |   0.11.15    |

NOTE: The versions displayed in this example may be out-of-date date, as Node.js and npm are updated regularly.

  1. Use the "nvm install" and "nvm use" commands to install and configure Node.js and npm, specifying the latest LTS version.
$ nvm install 14.16.1
$ nvm use 14.16.1

Verify your third-party software

If you have installed the tools properly, these commands will successfully return the version numbers.

$ node -v
v14.16.1
$ npm -v
6.14.12

NOTE: The command to return the installed version of Python is platform-specific. Regardless, if you do not have the correct version of Python installed, you will be informed by an error message when you attempt to build your customization.

Set up a customization project

With the third-party tools installed, download the GBC project package and prepare it for your customization efforts.

  1. Download the latest GBC project package from the Four Js Products download area.

  2. Extract it to a location of your choosing. This directory is known as the "GBC project directory". This documentation uses the placeholder variable gbc-project-dir. Replace with the path to your GBC project directory.

  3. From a command prompt, navigate to the GBC project directory.

$ cd gbc-project-dir
  1. Install the Node Package Manager (npm) in the GBC project directory.
$ npm install
  • You must have internet access.
  • Run this command whenever you get a new version of the project package.
  1. Install the gbc build package using the Node Package Manager.
$ npm run install-gbc
  • You must have internet access.
  • You may need super-user rights on your system.
  • Unless you have reinstalled Node.js, this command is only needed once.
  1. Execute the default compilation.
$ gbc build

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, execute this command to run the standalone GAS:

$ 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 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 using the default customization (named sample) built earlier in this procedure, open the following URL in a 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:

$ gbc build -w

You will need to refresh your browser once compilation completes.

  • Use a dedicated console, as this option 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 customization project, see Create a customization project.