WEM Widget Structure

If you want to create your own custom widgets.

Go to this Forum Post to find: ExampleWidgetsLibrary.zip Library with some working example widgets, so you can review and learn the code.

BasicWEMWidgetExample.zip Basic WEM Widget Example with explanation of the structure and the code.

Widget Development Tab/Elements

• Script: the actual functionality that will be added to the interaction node/template/page where widget is added to the template;

• Properties: properties to be used by widget, parameters to be set on an instance of the widget; possible links to fields in data model;

• View state: fields that will be added to and accessible from view state;

• Events: definition of events and eventhandler scripts (refresh screen, execute flowchart, follow exit);

• Resources: files (scripts or images) to be included; these are files that will be included in the package and also in the published resources when projects using the widget are published. So files need to be as small as possible;

• Styles: CSS style definitions specific to the elements in the widget. LESS can also be used if you are familiar with it. Be smart and use unique identifiers and limited scope;

• Editor script: define the display of the widget (informative, not interactive) in the Modeler Template Editor when user places widget onto a template.

Typical widget script outline

1. scriptreferences: referring to local or remote JavaScript files - local files are preferred, because remote files may become unavailable in future or may conflict with other widgets after updates - local files will keep all resources you need for the widget to work available and under control;

2. register inputs: to enable widget properties to be handled as input and linked to fields in the Data Model;

3. register events: to enable your defined events on the Events tab as operational events in the script;

4. script module block: JavaScript that will be added to the html once to be re-used;

5. startup script block: JavaScript that is executed just after html is rendered, to initialize an instance of a widget;

6. submitscript block: JavaScript that is executed on submit;

7. unloadscript block: JavaScript that will be invoked after the request/post gets new response from server but before the new HTML result is rendered, use to cleanup JavaScript instances;

8. Html (to present visible user interaction and presentation, also the hidden input elements to store and update values linked to fields in data model).

Unique ID

A widget can be placed on a page more than once by actually placing it more than once or having it inside a repeating element. To distinguish between different instances of a widget, it needs a unique identifier within the html-DOM.

• A page-level unique id can be created using the function OutputId().

• A specific unique id for instance of a property on page (useful for input fields): OutputId(@Property).

Linking input fields in Widget to WEM Data model

• add property of type Data Field;

• Enable option ‘Data field must be writable’;

• Register as input: register input @DataField;

• Add html input field (hidden or other), like: <input type="hidden" name="<?attr OutputId(@DataField) ?>" id="<?attr OutputId(@DataField) ?>" value="<?attr @DataField ?>" />

• Update the value of this input-field linked to WEM Field using JavaScript in the widget-code.

Events

1. Create an event (name and event script);

2. In Widget Script tab, add: register event @EventName;

3. In the JavaScript widget-code where this event should be triggered, add: <?raw @EventName ?>

Typical WEM-events are:

• execute @Flowchart

• follow @Exit

• navigate @NavigationItem

Typical example for an event, using properties:

• @EventType: Dropdown options like “FollowExit”, “ExecuteFlowchart”, “NavigateTo”, “RefreshScreen”, “DoNothing”;

• @Flowchart: user can select a flowchart when configuring the widget;

• @Exit: user can select an exit when widget is on a template which has exits;

Eventhandler script:

if @EventType = "ExecuteFlowchart" 
    execute @Flowchart 
elseif @EventType = "FollowExit" 
    follow @Exit 
elseif @EventType = "NavigateTo" 
    navigate @NavigationItem 
end

Register event (only when it is not chosen as DoNothing):

if @EventType <> "DoNothing" 
    register event @EventName 
end

Trigger event:

function triggerEvent() {
    <?raw @EventName ?>
}

If an EventType is selected by user (like a FollowExit or ExecuteFlowchart) but there is no Exit specified to follow, or a Flowchart to Execute, there will be a Page Refresh.

Editor script

Using the Editor Script, you can define the display of the Widget when a User places the Widget onto the Template Canvas in the WEM Template Editor.

One good option would be to create an example with your widget, run it in Preview, make an image of the rendered result, add the image to the Resources (as PreviewImage) and use that Resource in this Editor Script:

var widgetPreview = utility.createElement("div");
widgetPreview.className = "widgetPreview";

var title = utility.createElement("div");
title.className = "widgetPreviewTitle";
title.appendChild(utility.createTextNode("Name Of Widget"));
widgetPreview.appendChild(title);

var previewImg = utility.createElement("img");
previewImg.src = resources.PreviewImage;
widgetPreview.appendChild(previewImg);

return widgetPreview;

The widgetPreview CSS classname is defined in the Styles tab, for example:

div.widgetPreview {
    border: 2px solid #dddddd;
    position: relative;
    width: 100%; 
    
    > div.widgetPreviewTitle {
    	background: #f8f8f8;
    	display: inline-block;
    	padding: 10px 2%;
    	width: 96%;
    }
    
    > img {
    	max-width: 100%;
    }
}