GBC
Basics
What is the GBC? Key Players How the GBC works Downloads Customization fundamentals Migrating customizations Customization and Theme Selection View the documentation Tour the GBC
Customization fundamentals

Before getting into the technical details behind the customization process, it is good to have an understanding of the theory.

Projects, Customizations, Themes, and Theme Parts

A customization is made of various components: projects, customizations, themes, and theme parts. These components contain the files that do the actual work of the customization: the json files, the scss files, and the javascript files.

At the root is the GBC project directory. In most cases, your team will only have one GBC project directory for each version of the GBC project package that they download. A project directory is referred to as the <GBC_PROJECT_DIR>.

Within the project directory, your team can add customization projects. A customization project will contain any of the javascript and scss files that you create to customize the widgets. Each customization that you may add has its own customization directory, which we refer to as a <customization_project_dir>.

Within a customization project, you can define multiple themes. Themes allow the user to change the look-and-feel while remaining within the same customization. For example, if you do nothing else but keep the themes that are provided by default with the customization package, the user will be able to switch between a default theme and a high contrast theme, the latter providing them with an interface with larger fonts. Other possible themes could include providing with a light interface and a dark interface, or providing different color options.

A theme is comprised of theme parts. A theme may have only one theme part, or it may be made up of multiple theme parts. A theme part can define theme variables, resources (such as images), and conditions (such as a check on whether the client is desktop or mobile). The theme parts may be local (contained within the customization folder) or they can be global (for theme parts that you may want to use across multiple customizations within the project). You combile theme parts to create a theme - think of them as Lego building blocks that you snap together.

The GBC will display the application according to the customization and theme selected.

Planning for the customization

The first step is to answer the question "What do I need to do to complete the customization that I wish to achieve?"

To answer this question, you have to identify your goals.

  • Do you have a single audience for your application, and only need to customize the interface to apply some corporate branding?
  • Do you want to give your users the ability to change how the interface appears? For example, you could:
    • Provide a default view and a high-contrast view (as done in the default runtime package)
    • Providing a lighter-color view and a darker-color view
  • Do you have different audiences that require a completely separate and distinct look-and-feel?

To plan for these approaches, let's examine each scenario

I have a single audience and only need to apply corporate branding

To achieve this, you would have a single customization containing a single theme. This theme may be comprised of one or more theme parts.

I want to give the user the ability to choose between different look-and-feels

To achieve this, you start with a single customization, but you will create multiple themes within that customization. Each theme will provide a specific look-and-feel. These themes may share some theme parts, however remember that it is the combination of theme parts that ultimately define the theme.

I want the UI to change based on the device the user is using

To achieve this, you start with a single customization, and you create a theme for each device type that the application may encounter. Within the definition of the theme, you specify which device the theme is valid for. When a user accesses the application from a device, only those themes that are allowed for that device are presented as an option.

I have two separate audiences, each whom should have their own look-and-feel

To achieve this, you would create two separate, distinct customizations. If you have any themes that you wish to provide to both of the groups (for example, a default and a high-contrast theme), you would use theme parts that are defined globally for the project, and then reference those theme parts with the themes set up in each of the customizations.

Getting the right customization and theme to the user

After you have modified a customization and its themes, you package your customization and deploy it to the Genero Application Server (GAS). You can have many customizations deployed to the GAS, but only one can be marked as the default customization. Unless otherwise specified, a user receives the default customization.

Methods to change which customization is used:

  • A different customization can be specified in the URL.

Within the selected customization, a default theme is used unless:

  • The user has previously accessed the application and selected a different theme. The last selected theme for the user is the theme that is chosen.
  • The theme is specified specifically in the URL.
  • The theme is set by a frontcall from the application itself.

Once the application is running, the theme can be changed, but the customization used cannot. To change the customization used, the application would need to be restarted with the new customization selected.