GBC 1.00.46 new features and upgrade notes

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

For more information about theme variables, see Theme variables reference.

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

For more information about theme variables, see Theme variables reference.

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

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.

For more information, see Theme reference and How customization works.

Until this version, GBC compilation meant:

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

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.

As 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.

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.

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

Font files are now considered a resource.

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

Several changes occurred 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.

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

  <imgsrc=""/>

  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");
  },
  

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().

For more information about theme variables, see Theme variables reference.