You create a widget by copying the original JavaScript, template, and SCSS files
associated with the widget you want to customize and editing the copied files.
Important: Use the simplest method possible for customization. If you can complete a customization
requirement by setting a theme variable or by extending a widget, then set the theme variable!
Extending a widget should be a last resort.
Steps to create a widget manually
-
Identify if there is a built-in widget you can extend.
-
Create the JavaScript (.js) file and add the code to implement the widget.
For information about the contents of this file, see Widget JavaScript file.
-
Create the template (.tpl.html) file to contain the HTML code structure of
the widget. For information about the contents of this file, see Widget template file.
By default, the JavaScript and template files share the same name.
Tip:
Follow the naming convention MyxxxWidget, where
xxx is the parent widget name.
For example, if extending the EditWidget, call the files
MyEditWidget.js and MyEditWidget.tpl.html.
-
Save both files in the customization-project-dir/js
directory.
-
If your template file uses a different name to the JavaScript file, or if you want to reuse an
existing template file, specify the template file in the JavaScript file with
__templateName
. For example:
__name: xxx,
__templateName: "yyy"
-
If your widget requires a library, add the library to the customization-project-dir/resources/lib/ directory and add a reference in the config.json
file:
{
"compile": {
"libraries": {
"library-name.js": "customization-project-dir/resources/lib/library-name.js"
}
}
}
-
Add any necessary styles. You can either:
-
Save your changes and rebuild your customization using
gbc build
:
$ gbc build
--customization customization-project-dir
-
Test that your changes work as expected.
What to do next:Once you have created your widget, you
are ready to begin customizing it. For examples of how you might use widgets, go to Widget examples.