Customization Project

You modify features and styles of a Genero Web Client for JavaScript (GWC-JS) front-end within a customization project.

Note: This document will use the variable custom_project_dir when referring to the customization project directory.

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

Within custom_project_dir, these are the directory structures and files that you must understand and manage.

Table 1. Default customization directory
Directory	Description	Usage examples
resources	Project resources, to include images in an img subdirectory.	See Add an image to the application title
js	The project's JavaScript and widget template HTML files.	See Widget JavaScript file See Add header and footer text
locales	The project's translation texts for localization.	See Add localized texts
sass	Cascading Style Sheet files for instructing the browser how to display specific widgets. You can change colors, font, layout, and how text is positioned, etc.	See Widget scss file
theme.scss.json	Change the default GWC-JS color and theme settings for your windows, widgets, messages, buttons, tables, etc.	Customizing the theme Display or hide the side bar

Creating a customization project

Create your customization projects in the project_dir/customization directory. To create a new customization project, create a copy of the customization template directory (project_dir/customization/template) and rename your copy. When you copy the template, you copy the directory structures needed for a customization project. This copy becomes your new custom_project_dir, and you can start adding your customized files.

You can have many customization projects. Each must have a unique custom_project_dir name.

A customization project must be compiled to be usable. See Compile a customization project. To have an application use a customization project, see Apply customization to an application.

Finding the right UI component

Customization initially consists of working with the GWC-JS 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 project_dir/src subdirectories:

The js subdirectories contain the xxxWidget.js and xxxWidget.tpl.html files.
The sass subdirectories contain the xxxWidget.scss

For more information on widgets, see the Understanding GWC-JS widgets section.

CAUTION:

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.

The How Do I … ? section provides examples that illustrate how to extend widget classes.

Compiling and testing as you go

As you add or update your project files, run the grunt command to compile your project.

Open an application to test the customization. See Apply customization to an application.