Customizing your application using widgets

The Genero Browser Client (GBC) comes with built-in widgets that define the user interface. If a built-in widget does not meet your needs, you can extend or override the widget.

You usually start with an existing widget (such as the EditWidget or ButtonWidget) and extend its functionality. For example, you might want to include a custom color picker. You could start with the ButtonWidget and add code to display a color wheel that allows user selection.

To create or extend GBC widgets, you require some knowledge of JavaScript.

Required files

Each widget is defined by the following:
  • A JavaScript (.js) file managing the widget creation, behavior, and listeners.
  • A template HTML (.tpl.html) file containing the HTML code structure of the widget. The template file determines whether your widget is:
    • A simple widget, which defines elements that implement basic functions; for example, an EditWidget or LabelWidget.
    • A container widget, which provides a placeholder for child widgets; for example, a MenuWidget.
  • A sass (.scss) file that serves as the widget's style sheet.

Some widgets require a library. The library must be in the customization directory under resources/lib/, and must be referenced by the config.json file.

Important:

Be careful when adding libraries to the GBC. If the library has access to GBC context, it might behave in an unexpected way. If the library is not optimized, it might cause performances issues.

Resources, such as images, may also be included with the widget.

Source files

You can explore the source files to familiarize yourself with how the front-end is implemented. The source files for the built-in widgets of the default GBC are found in the gbc-project-dir/src directory.

Warning:

Do not modify the original source widget files.

Overriding and extending widgets

In terms of widget development, it's important to distinguish between two key techniques:

  • Overriding: replaces the existing widget.
  • Extending: creates a new widget based on an existing widget.

Both techniques are essential for customizing and enhancing widgets, enabling you to create more flexible and powerful applications.

Overriding, a widget allows you to replace the default functionality of an existing widget with your custom implementation. Using the command gbc create-widget customization/customization-project-dir MyEditWidget --base EditWidget --override, the custom widget is created with the following functionality:

  • Automatic Actions:
    • The --override option automatically copies the HTML template from the original widget, EditWidget.tpl.html.
    • It registers the custom widget in the JavaScript file MyEditWidget.js with the line: cls.WidgetFactory.registerBuilder('EditWidget', cls.MyEditWidget), replacing the original registration.
  • Inheritance:
    • MyEditWidget inherits features from EditWidget.
    • You can add new features or override inherited ones in the JavaScript file, MyEditWidget.js.
  • Replacement: Any instance of EditWidget in your program will be replaced by MyEditWidget.

For an example overriding the ButtonWidget, go to Widget overrides.

Extending a widget allows you to create a new version of an existing widget while retaining its functionality and adding new features. Using the command gbc create-widget customization/customization-project-dir MyEditWidget --base EditWidget, the new widget is created with the following functionality:

  • Inheritance:
    • MyEditWidget inherits features from EditWidget.
    • You can add new features or override inherited ones in the JavaScript file, MyEditWidget.js.
  • HTML Template:
    • The template file MyEditWidget.tpl.html will be empty.
    • Options include copying the original template from EditWidget.tpl.html or creating a new template.
  • Coexistence: Both EditWidget and MyEditWidget can be used together in the application.

For an example extending the MainContainerWidget, go to Extend the MainContainerWidget.

For details about the gbc create-widget command, go to gbc tool page.