GBC 1.00.46

GBC 1.00.46 was released July 13th, 2018.

This page provides information about new features, as well as changes you need to take care of when migrating your customization to this version.

New theme variable to customize calendar dropdown

Added a new theme variable gbc-DateEdit-daysOff-color to set the (faded) color of the Pikaday calendar disabled days defined in the presentation style attribute daysOff

Variable Type Comment
gbc-DateEdit-daysOff-color color default value is theme-secondary-faded-color

New theme variable to customize CommandLinkWidget

Added a new theme variable gbc-CommandLinkWidget-ttf-color to set the color of the ttf icon in Button widget with style commandLink

Variable Type Comment
gbc-CommandLinkWidget-ttf-color color default value is theme-secondary-color

New css classes for client-side field validation

2 classes have been added to formfield widgets to help one to customize the client-side field validation:

  • gbc_Required for any field widget with a mandatory value
  • gbc_NotNull for any field widget with a value that cannot be null

The method getAllowedValues() on any field widget can be called to get values defined in .per with attribute INCLUDE

StartMenu Widget html structure

Please note the minor change in the StartMenuWidget html structure: a new div with the class wrapper has been added around the widget container element.

CommandLink Widget html structure

Image container and text container have been separated in CommandLinkWidget html template. Please refer to the CommandLinkWidget.tpl.html source for better understanding.

Typo fix in class names

Old Classname Renamed to
gbc_startMenuText gbc_StartMenuText

Themes

Starting from GBC 1.00.46, you will be able to define more than one theme within a compilation. Until now, you were able to define theme variables in a customization, with theme.scss.json file, and add custom scss in adjacent files.

MIGRATION: Your existing customizations will continue to work after some minor modifications from your part. See below for details.

New concepts

Multiple theme in one runtime

Until this version, GBC compilation meant:

GBC code base + ONE customization (including theme) = ONE runtime

Now with GBC 1.00.46, customization and theme are split in two concepts, permitting multiple themes available per runtime

GBC code base + ONE customization + n theme definitions = ONE runtime including n themes

The first available theme will be the active one at the first run. The end user may switch the theme from the GBC settings dialog. The end user selection is stored for the subsequent run.

Source theme parts

As per in the project package, you will now have a theme folder which will contain several sub folders. You will find:

  • theme/platform/desktop
  • theme/platform/mobile
  • theme/colors/highcontrast

These folders are not themes, strictly speaking, but are theme parts, which can be combined to generate runtime themes.

A theme part can contain several compounds, described here:

  • theme.config.json file (optional) This json file will contain theme applicable conditions
      // sample: theme/platform/mobile/theme.config.json
      {
        // optional
        // array of conditions that filters applicable themes (see theme conditions below)
        "conditions": ["isMobile"]
     }
    
  • theme.scss.json file (optional) This file can be used to set theme variables (as it was already done in customizations)
  • sass/ folder (optional) This folder can contain scss definitions themeVariables.scss (as you have customVariables.scss in customization), theme.scss (as you have customization.scss in customization), and other scss files that can be imported by the first two.
  • resources/ folder (optional) This folder can contain theme parts resource files.

Theme definition

As said before, theme parts will be able to be combined to produce runtime themes. To do that, these themes will have to be defined.

These definitions can be set in optional custom.json or the configuration file given by gbc build's option --configuration= as a themes entry.

// sample: custom.json
{
 "compile": {
   "mode": "cdev"
 },
 //here we have the theme definitions
 // it is an array of definitions
 "themes": [{
     // name of the theme
     // this one should be unique, only contain [a-z0-9_-] characters as
     // it will be the name of the folder in the runtime themes/ folder
     "name": "default",
     // title that will be displayed in the theme selector
     "title": "Default",
     // optional
     // ordered list of theme parts to combine in this theme
     "uses": ["platform/desktop"],
     // optional
     // conditions to add to the theme parts' ones
     "conditions": […]
   },
   {
     "name": "highcontrast",
     "title": "High contrast",
     "uses": ["platform/desktop", "colors/highcontrast"]
   },
   {
     "name": "default_mobile",
     "title": "Default",
     "uses": ["platform/mobile"]
   },
   {
     "name": "highcontrast_mobile",
     "title": "High contrast",
     "uses": ["platform/mobile", "colors/highcontrast"]
   }
 ]
}

It is possible to force these definition for a particular customization in a config.json file, then it will supersede other theme definitions.

MIGRATION: By default, we provide custom.json defining the 4 themes as defined above (default, highcontrast, default_mobile and highcontrast_mobile). If you have defined your own custom.json, be sure to merge it with the new delivery to benefit from the theme feature.

Compilation overrides

Orders of precedence are set to produce coherent runtimes. Themes variables and resources will be compiled in a deterministic way, this is why order of theme parts in theme definitions is important.

  • Theme variables For a given theme, theme variables defined in GBC codebase will be superseded by customization overrides, then superseded by each theme part in order.

  • Resources Resource management changes with this new feature. GBC own resources (including fonts, see below) and customization resources are now considered as global resources at runtime. Resources existing in customization will supersede GBC codebase ones, if they exist in both. Each theme part can add or override resources, considered then as theme resources. Same rule applies here, last supersede wins.

  • Theme conditions Each theme part or theme definition can declare conditions. At build time, these conditions will be combined as the produced theme will have to fit all conditions possible in the execution context.

    Possible values for theme conditions are:

    isDesktop the running platform is a desktop (e.g. Windows, Linux)
    isTouchDevice the running platform has touch abilities (e.g. mobile device, Microsoft Surface)
    isMobile the running platform is a mobile (e.g. Android, IOS)
    isAndroid the running platform is Android
    isIOS the running platform is IOS
    isChrome the running browser is Google Chrome
    isEdge the running browser is Microsoft Edge
    isFirefox the running browser is Mozilla Firefox
    isIE the running browser is Microsoft Internet Explorer
    isOpera the running browser is Opera
    isSafari the running browser is Safari

Beware of conflicting conditions! If a theme gets for example "isDesktop" and "isMobile" conditions, this theme won't be usable in any case.

Font files

Font files are now considered a resource.

MIGRATION: In your existing customizations, just move your fonts folders to resources/fonts.

Runtime file structure changes

Several changes occured in the file structure of the runtime packages. It should not impact you directly as it is not recommended to modify these files directly.

  • lib/js/ was renamed js/third-party/
  • lib/fonts/ was renamed resources/fonts/ (See Font files above)
  • css/, containing only main.css, is replaced by themes/, which contain a folder per compiled theme, each containing its own main.css, plus theme specific resources, if any.

Theme resources API

In order to ease resource linking, a new resource access mechanism has been defined.

  • In SCSS files Resources up to this had been linked by some relative paths like ../resources/img/logo.png. Starting from 1.00.46, resources will be linked with special variable $$RES, e.g. $$RES/img/logo.png. This will permit the gbc build process to point to the correct path of global resource or theme resource.

    MIGRATION: Review your resources paths (including fonts links) in your SCSS sources to use $$RES variable.

  • In JS files In javascript too, one can link resources. For the same reason as accessing global resource / theme resource, this:
    this._productInformation.setLogo("resources/img/logo.png")
    
    becomes this in 1.00.46:
    this._productInformation.setLogo(context.ThemeService.getResource("img/logo.png"));
    

    MIGRATION: Review your resources paths (including fonts links) in your JS sources to use gbc.ThemeService.getResource().

  • In tpl.html files In tpl.html files, however, the $$RES variable can not be used. Therefore, you probably do not need to change the way you reference an image in your project's resources directory by setting the path relative to your <GBC_PROJECT_DIR>/customization/<customization_project_dir> directory, ( for example, <img src="./resources/img/logo.png"/>). See Add header image. But alternatively, you can achieve the same result by setting the HTML file part with
    <img src=""/>
    
    and in the JS file part: Set the img path via JavaScript in the _initElement method of your widget:
    _initElement: function(){
      $super._initElement.call(this);
      this._element.querySelector("img").src = context.ThemeService.getResource("img/logo.png");
    },
    

Theme variables API

The same as with resources, theme variables access has changed. This:

context.constants.theme["theme-grid-inner-gutter"]

becomes this in 1.00.46:

context.ThemeService.getValue("theme-grid-inner-gutter")

MIGRATION: Review your theme value accesses in your JS sources to use gbc.ThemeService.getValue().