UI Designer Custom widgets

To extend the standard widgets, develop your custom widgets using HTML, AngularJS and Javascript.

After creation, custom widgets are available in the palette to design pages, application layouts, forms or fragments.

Description

In UI Designer editor, custom widgets are composed of:

A template that describe the widget HTML markup
A controller that describe the widget logic
Properties exposed by the widget
A description that briefly describes the widget
Some assets if the widget uses external JavaScript libraries, CSS definitions, or images
AngularJS modules declaration if the widget uses services or directives that are not built in to the AngularJS framework
The Bonita REST API resources if needed for the widget.

Custom widget implementation is based on the AngularJS framework.
When you open the custom widget editor to create a new custom widget, a simple example is displayed to show the basic uses of these concepts.

For more information, see the AngularJS guide on templates and controllers.

For now, the definition of custom containers is not yet available in the product.

Note that UI Designer always prefix the ID of the custom widgets by "custom", whereas the standard widgets are internally using the prefix "pb". If you build a widget outside of the UI Designer, your widget ID must not start with "pb".

Custom widget properties

Properties are variables that can be set in the properties panel when adding a custom widget to a page, layout, form, or fragment.
A property is constant, dynamic, a bidirectional bond, or an interpolation. You can chose between these treatments when you edit the widget property. Use properties when you want the front-end developer using the widget to customize widget appearance or behavior. In a custom widget, a property can be used either in the template or in the controller.

A property has a name which can be referenced in the controller or the template, a label which will be printed in the properties panel in an editor, a default value, and a type. There are several property types:

text user specifies the property value with some text
choice user chooses the property value from a list that you define
html user specifies the property value with some text that can contain basic HTML tags
integer property value is an integer
boolean property value is a Boolean
collection property value is an array

Each of these types will allow the front-end developer to bind the property value to a variable.

Using an external AngularJS directive or service in a custom widget

Many Angular libraries are available on the Internet and can be used in a custom widget. To do so, download the library you want to use and add it to your custom widget as a JavaScript asset. The downloaded library will specify a module to add to your application: add this module to the custom widget definition in the Required Angular modules field. Now you can use the imported library directives in the custom widget templates and services in the controller by injecting them in function arguments (example: function($scope, myImportedService)).

Translation filter

The Multi-language pages tutorial explains how to manage localization (l10) inside developped pages, layouts, forms or fragments. During page loading, the l10n strings are loaded to the l10n mechanism.

You can use this mechanism in your custom widgets to process content to translate. There are two ways to use the localization: either the uiTranslate angular filter or ui-translate directive:

Use the uiTranslate filter in custom widgets for dynamic content to be translated
Use the ui-translate directive in custom widgets for static content to be translated

For instance, with a custom link widget :

<div>
    <a title="{{ properties.title | uiTranslate }}" ui-translate>Submit</a>
</div>

The link text which is static is translated using the ui-translate directive. The link text title held inside the properties.title variable is translated using the uiTranslate filter.

Advanced example

This section explains how to use the carousel and slide directives from the ui.bootstrap library.

Following the ui.bootstrap documentation, download ui-bootstrap-tpls.min.js and declare the module ui.bootstrap as a dependency of the application. Specifically, to use these directive in a custom widget, you need to:

Download ui-bootstrap-tpls.min.js.
Add it as local JavaScript asset to the custom widget.
Declare the ui.bootstrap module in the Required angular modules field.

You can now use the carousel and slide directives in your template. Here is a simple example of the template and controller for a carousel.

Template:

<div uib-carousel>
      <div uib-slide ng-repeat="slide in slides track by $index" index="$index" >
        <img ng-src="{{slide.url}}" style="margin:auto;" alt="{{slide.alt | uiTranslate}}">
      </div>
</div>

If you want use carousel and slide directives in the same page as widgets that import ui-bootstrap-tpls-0.13.0.min.js as asset, please use this syntax for carousel and slide directives in your template.

<uib-carousel>
      <uib-slide ng-repeat="slide in slides" >
        <img ng-src="{{slide.url}}" style="margin:auto;" alt="{{slide.alt | uiTranslate}}">
      </uib-slide>
</uib-carousel>

Controller:

function ($scope) {
      $scope.slides = [
        { url: 'http://placekitten.com/601/300', alt:'kitty looking down' },
        { url: 'http://placekitten.com/602/300', alt:'kitty in hand' },
        { url: 'http://placekitten.com/603/300', alt:'kitty outside' },
        { url: 'http://placekitten.com/604/300', alt:'4 kitten in basket' }
       ];
    }

Troubleshooting

When i drag and drop my custom widget in my page editor, i see nothing.

Potential cause Your custom widget html template contains certainly only dynamical code.

Possible solution To fix this issue, you need to define in the html template, a html tag with ng-if="environment attributes to retrieve better your custom widget in your artifact to display the widget name

    <span ng-if="environment">{{environment.component.name}}</span> (1)

1	environment is a keyword to define if the code is executed on editor mode.