GBC 1.00
Basics
What is the GBC? Key Players How the GBC works Downloads Customization fundamentals Migrating customizations Customization and Theme Selection View the documentation Search the documentation Tour the GBC
Home Page Application page Application ended page
Syntax
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

The GBC contains these components, as illustrated in Figure 1:

  • Projects
  • Customizations
  • Themes
  • Theme parts

Relationship of project, customization, and themes Figure 1: Relationship of project, customization, and themes

These components contain the files that do the work of the customization: the json files, the scss files, and the javascript files. See Figure 2 for the directory structure.

Directory structure showing project, customization, and themes

Figure 2: Directories for customization and themes

At the root is the GBC project directory. In most cases, your team has only 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 contains 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 keep the themes that are provided by default with the customization package, the user can 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 one or more 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). You combine theme parts to create a theme - think of them as Lego building blocks that you snap together.

The theme parts may be local (contained within the customization folder) or global (for theme parts that you may want to use across multiple customizations within the project).

TIP: To ease migration, it is recommended that you use local theme parts.

The GBC displays 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?"

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 your users to be able to change the appearance of the interface? For example, you could provide:
    • A default view and a high-contrast view (as in the default runtime package)
    • A lighter-color view and a darker-color view
  • Do you have different audiences that require a separate and distinct look-and-feel?

Let's examine each scenario.

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

Use a single customization containing a single theme. This theme may be comprised of one or more theme parts.

I want the user to be able to choose between different look-and-feels

Start with a single customization and create multiple themes within that customization. Each theme provides a specific look-and-feel. These themes may share some theme parts, but the combination of theme parts define the theme.

I want the UI to change based on the user device

Start with a single customization and create a theme for each device type that the application may encounter. Within the definition of the theme, specify which device the theme is valid for. When users access the application from a device, they see only those themes that are allowed for that device.

I have two separate audiences and want each to have their own look-and-feel

Create two distinct customizations. If you want to provide any themes to both groups, 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 modify a customization and its themes, you package your customization and deploy it to the Genero Application Server (GAS). You can deploy many customizations to the GAS, but only one can be marked as the default customization. Unless otherwise specified, a user receives the default customization.

You can use the URL to specify a different customization.

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 chosen.
  • The theme is specified specifically in the URL.
  • The theme is set by a frontcall from the application.

When the application is running, the theme can be changed, but the customization cannot. To use a different customization, restart the application with the new customization selected.