Customization project

You can modify features and styles of a Genero Browser Client (GBC) front-end within a customization project directory.

In the customization-project-dir, you add your custom JavaScript, HTML, and CSS sources. These sources are compiled into a new front-end for distribution.

Within customization-project-dir, these are the directory structures and files that you must understand and manage.

Directory or file Description
customization-project-dir/js (folder) The project's JavaScript and widget template HTML files.
customization-project-dir/locales (folder) The project's translation texts for localization.
customization-project-dir/resources (folder) Project resources, to include images in an img subdirectory.
customization-project-dir/resources/img (folder) The img subdirectory containing images.
customization-project-dir/sass (folder) Cascading Style Sheet files for instructing the browser how to display specific widgets. You can change colors, fonts, layout, how text is layed out, and so on.
customization-project-dir/sass/customization.scss (file) Entries here modify the stylesheet. While you can add css details directly into this file, a preferred method is to use the @import statement to import other stylesheets contained in the sass folder. For example, if you had a file named myHeader.scss in the customization's sass folder, you would include @import "myHeader" at the top of the customization.scss file.
customization-project-dir/theme (folder) Customization-specific theme parts, with each theme part in its own directory.
customization-project-dir/theme/<theme_part>/theme.scss.json (file) When using a theme that contains this theme part, change the default GBC color and theme settings for your windows, widgets, messages, buttons, tables, and so on.
customization-project-dir/config.json (file) Customization specific configuration file. This one will override information of custom.json file (see Configure your compilation).
customization-project-dir/theme.scss.json (file) Change the default GBC color and theme settings for your windows, widgets, messages, buttons, tables, and so on. [DEPRECATED] Changes using scss should now be completed within a theme part, in a file of the same name.

Creating a customization project

To create a customization project, create a directory under gbc-project-dir/customization. This directory becomes your new customization-project-dir, and you can start adding your customized files. You can have many customization projects. Each must have a unique name. A customization project must be compiled to be usable. See Set up your GBC build environment.

Finding the right UI component

Customization initially consists of working with the GBC client to identify which component in the interface to customize. Each element of the UI is a widget/component. Each widget has a defined class name in the format "gbc_xxxWidget", where "xxx" is the widget name. The widget name is often the name used in the AUI tree.

TIP: Use your browser's developer tools to select the UI element you want to change.

Finding the widget files

Once you have identified the widget, locate the corresponding widget files in the gbc-project-dir/src subdirectories: The js subdirectories contain the xxxWidget.js and xxxWidget.tpl.html files. The sass subdirectories contain the xxxWidget.scsz For more information on widgets, see Widgets.

IMPORTANT: We recommend that you leave the core sources untouched.

Extending widgets

For the widgets you want to customize, create MyxxxWidget.tpl.html and MyxxxWidget.js files in your customization project's js directory. These contain the minimal HTML and JavaScript code needed to inherit and extend the parent widgets.

Create your Myxxx.scss file in your customization project sass directory. Import your .scss in the customization.scss file.

Follow the recommended naming convention to define new widgets with the same name in the format "MyxxxWidget", where "xxx" is the parent widget name. For example; MyHeaderBarWidget.js, MyHeaderBarWidget.tpl.html, and MyHeaderBarWidget.scss.

See Customization.

Compiling and testing as you go

As you add or update your project files, run the gbc command to compile your project. Open an application to test the customization.