Help Topics

Creating Custom Widgets

HMIBuilder Data

Overview

To use the HMIBuilder program to create active widgets, HMIBuilder requires that certain data be included in the widget. This section describes that data.

Example Output Widget

Complete Example

The following is an example of a simple output widget. This example displays integer digits in an SVG text element. It could be used to display numeric data.


<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
   xmlns:svg="http://www.w3.org/2000/svg"
   xmlns="http://www.w3.org/2000/svg"
   xmlns:mblogic="http://www.example.com/mblogic"
   version="1.0"
   width="50"
   height="20">

<!-- This provides a text object. -->
<g mblogic:widgettype="text" 
	mblogic:widgetname="Integer Digits"
	mblogic:editcount="0"
	mblogic:menu='[{"value": "", "type": "tag", "name": "Output Tag", "param": "outputtag"}]'
	mblogic:inputfunc="[]"
	mblogic:outputfunc='MBHMIProtocol.AddToDisplayList(new MB_NumericDisplay(document, 
					"%(widgetid)s"), "%(outputtag)s", "read");'
	>

	<text x="50" y="20" stroke="red" fill="red" font-size="20" text-anchor="end">1234</text>

</g>
</svg>

Basic Artwork

The following shows the basic SVG widget artwork. This is similar to the example used for passive data, but two this should be noted. The first is that we have provided some default data for the "text" element ("1234" in this case). This data will be replaced with real data when the HMI is running, but in the mean time it provides some visible component while we are creating the drawing. Without this, the text element would be invisible. This is something that must be kept under consideration with some types of SVG elements.

The other point is we have enclosed the text element inside a set of "group" tags ("<g>" and "</g>"). Although these are not always necessary for the purposes of displaying simple SVG widgets, we will need this because we will store extra data as attributes which the HMIBuilder program will use. This means we must always provide a set of enclosing "<g>" and "</g>" around our widget.


<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
   xmlns:svg="http://www.w3.org/2000/svg"
   xmlns="http://www.w3.org/2000/svg"
   version="1.0"
   width="50"
   height="20">

<!-- This provides a text object. -->
<g>

	<text x="50" y="20" stroke="red" fill="red" font-size="20" text-anchor="end">1234</text>

</g>
</svg>

HMIBuilder Data

The following shows the attribute data which has been added to the widget. This data allows the HMIBuilder program to find the SVG widget in the SVG drawing, identify it, construct menus, and assemble the final Javascript which will enable it to function as an active widget. The presence of the 'mblogic:widgettype' attribute in a "g" tag is what identifies something as an HMI widget.


<g mblogic:widgettype="text" 
	mblogic:widgetname="Integer Digits"
	mblogic:editcount="0"
	mblogic:menu='[{"value": "", "type": "tag", "name": "Output Tag", "param": "outputtag"}]'
	mblogic:inputfunc="[]"
	mblogic:outputfunc='MBHMIProtocol.AddToDisplayList(new MB_NumericDisplay(document, 
					"%(widgetid)s"), "%(outputtag)s", "read");' >

</g>

XML Name Space

There is an addition step which must be taken. The SVG definition heading must have the 'mblogic' name space added to it.


<svg
   xmlns:svg="http://www.w3.org/2000/svg"
   xmlns="http://www.w3.org/2000/svg"
   xmlns:mblogic="http://www.example.com/mblogic"
   version="1.0"
   width="50"
   height="20">

HMIBuilder Data

The HMIBuilder program requires special data to be inserted into the widget file to be able to work with it. This data is stored in the form of attributes. An attribute is additional data or annotations added to a tag. These attributes must be in the "g" (or group) tag which encloses the widget (the same one you add the identifying "id" to). The data consists of the following components.

Basic Data

The basic data constitutes parameters that indentify the type of widget, and control the editing process:

mblogic:widgettype: The presence of this attribute identifies this to HMIBuilder as an SVG HMI widget. The value is unused at present, but may be used in future.
mblogic:widgetname: This name will appear in the widget menu when you edit the widget. The actual name does not matter as it is simply displayed. However, you should use a name which is recognisable and which does not conflict with other widgets.
mblogic:editcount: This is used by HMIBuilder to determine whether the widget has been edited yet. If the edit count is 0, it is assumed to have not been edited yet (and so requires configuration). If the value is not 0, it is assumed it has been edited. This value is saved in the HMI drawing when you save your changes so that if you edit a drawing over several sessions, it will remember which widgets have been configured and which have not. The editcount in a widget file (as opposed to an HMI drawing) must always be set to 0. If it is not 0, the HMIBuilder program will assume that it has already been edited and has valid parameters.


	mblogic:widgettype="text" 
	mblogic:widgetname="Integer Digits"
	mblogic:editcount="0"

Menu Data

The menu data is used to construct the menus which appear in the parameter menu which appears in HMIBuilder. The menu data is encoded as JSON data which is embedded in the attribute string. The web page will merely see this as a string, but HMIBuilder will attempt to convert the string into actual data.

The JSON data must be an array (list) of objects, with each array element representing one menu entry. Each objects must have certain attributes. These are:

name - The name of the parameter. This name will appear on the menu when you edit the parameter.
type - The expected data type.
value - The data value. Default data may be created by inserting it here. When the SVG drawing is saved, the current value (entered by the user will be stored here.
param - The name used to help substitute the data into the input or output functions. This will be described in more detail below. However, this name must be unique within each widget (although other widgets may use the same name).

The widgetid param is automatically defined by HMIBuilder in order to make the id attribute available, so you do not have to create this in your menu.

The valid types are:

tag - An address tag. This will appear as an option menu list. The list will be derived from the selected HMI configuration file.
int - A valid integer.
float - A valid floating point number.
str - A valid string.
textlist - A comma separated list of values.
colour - A colour. This will appear as an option menu list.
layer - An drawing layer name. This will appear as an option menu list. This will be derived from the layers found in the drawing.
none - A special type used to indicate an empty menu. This is used when a widget requires no parameters.

When the HMI drawing is saved, the selected parameters will be saved with the parameter.


	mblogic:menu='[{"value": "", "type": "tag", "name": "Output Tag", "param": "outputtag"}]'

Output Functions

The output function attribute is used to construct the Javascript code which is used to control "output" devices. Output devices are those which display data read from the server.

The output function attribute data is a string which contains the Javascript code which will be inserted into the HMI web page. This string may contain multiple lines of Javascript. The string itself contains codes which are used by HMIBuilder to find where to substitute in the menu data.

The string substitution codes have the format %(param)s, where "param" is the parameter value defined in the menu. For example, for "param": "outputtag" the code would be %(outputtag)s.

The widgetid code is automatically created by HMIBuilder, so do not attempt to use this as one of your own code names. You may use the same code multiple times in the output function string if the same value must be present several times.

Note that due to problems which will arise if you "overlap" single ( ' ) and double ( " ) quotes, you must take care when entering quotes to use one type of quote for embedding within the string, and another type for enclosing it. However, you can "escape" embedded quotes (cause them to be ignored by either preceding them with a back slash (e.g. \", or representing them with the alternate HTML symbol (e.g. "). This only works for embedded quotes however, not those used to enclose the attribute string.


	mblogic:outputfunc='MBHMIProtocol.AddToDisplayList(new MB_NumericDisplay(document, "%(widgetid)s"), 
			"%(outputtag)s", "read");'

Input Functions

Input functions have characteristics similar to both menus and are similar to output functions. Input functions are encoded as JSON embedded in an attribute string. They consist of arrays (lists) of objects with the following attributes:

event - This is the event handler attribute the resulting Javascript code will be attached to.
func - This a string containing the event handler code to be executed.


	mblogic:inputfunc='[{"event": "onclick", 
	"func": "MBHMIProtocol.WriteToggleImmediate(\"%(inputtag)s\", \"%(inputtag)s\");"}]'

You can have multiple different types of event handers by adding more objects.

Examples

The following shows some typical examples of SVG widgets. These examples show just the SVG and attributes to implement the widgets themselves, but for the sake of clarity omit the additional SVG heading and colour gradient declarations.

You can view the actual text of the SVG widget files themselves for complete examples.

Toggle Push Buttons

This shows a simple input example. Note that the output function ("mblogic:outputfunc") is an empty string.


<g class="buttonactivate" 
	mblogic:widgettype="pb_toggle" 
	mblogic:widgetname="Toggle Push Button 1"
	mblogic:editcount="0"
	mblogic:menu='[{"param": "inputtag", "type": "tag", "name": "Input Tag", "value": ""}]'
	mblogic:inputfunc='[
		{"event": "onclick", 
		"func": "MBHMIProtocol.WriteToggleImmediate(\"%(inputtag)s\", \"%(inputtag)s\");"}]'
	mblogic:outputfunc=""
	>

	<rect x="7" y="7" width="80" height="80" rx="15" fill="grey" 
		stroke="none" stroke-width="0px" filter="url(#MB_DropShadowFilter)"/>
	<rect fill="url(#MB_IndigoGradient)" x="0" y="0" width="80" height="80" rx="15"/>
	<text x="40" y="50" font-size="24" stroke-width="2px" text-anchor="middle">PB</text>

</g>

Momentary Push Buttons

This shows an input with multiple event handlers. Note that there are multiple input event handlers defined.


<g class="buttonactivate" 
	mblogic:widgettype="pb_momentary" 
	mblogic:widgetname="Momentary Push Button"
	mblogic:editcount="0"
	mblogic:menu='[{"param": "inputtag", "type": "tag", "name": "Input Tag", "value": ""}]'
	mblogic:inputfunc='[
		{"event": "onclick",	"func": "MBHMIProtocol.WriteImmediate(\"%(inputtag)s\", 1);"}, 
		{"event": "onmouseup", "func": "MBHMIProtocol.WriteImmediate(\"%(inputtag)s\", 0);"}, 
		{"event": "onmouseout", "func": "MBHMIProtocol.WriteImmediate(\"%(inputtag)s\", 0);"}]'
	mblogic:outputfunc=""
	>

	<rect x="7" y="7" width="80" height="80" rx="15" fill="grey" 
		stroke="none" stroke-width="0px" filter="url(#MB_DropShadowFilter)"/>
	<rect fill="url(#MB_PurpleGradient)" x="0" y="0" width="80" height="80" rx="15"/>
	<text x="40" y="50" font-size="24" stroke-width="2px" text-anchor="middle">PB</text>

</g>

Pilot Light

This shows a simple output. Note that the input function ("mblogic:inputfunc") is an empty array (not just an empty string).


<g mblogic:widgettype="pilot_light" 
	mblogic:widgetname="Pilot Light"
	mblogic:editcount="0"
	mblogic:menu='[{"value": "", "type": "tag", "name": "Output Tag", "param": "outputtag"}, 
		{"value": "black", "type": "colour", "name": "Init Colour", "param": "initcolour"}, 
		{"value": "", "type": "colour", "name": "Off Colour", "param": "offcolour"}, 
		{"value": "", "type": "colour", "name": "On Colour", "param": "oncolour"}]'
	mblogic:inputfunc="[]"
	mblogic:outputfunc='MBHMIProtocol.AddToDisplayList(new MB_PilotLight(document, 
		"%(widgetid)s", "%(initcolour)s", "%(offcolour)s", "%(oncolour)s"), 
		"%(outputtag)s", "read");'
	>
	<!-- This is a decorative nut. -->
	<polygon transform="translate(5,5)" fill="grey" stroke="none"
		filter="url(#MB_DropShadowFilter)"
			points="63,0 27,0 0,27 0,63 27,90 63,90 90,63 90,27 63,0" />
	<polygon  fill="url(#MB_SilverGradient)" stroke="none"
			points="63,0 27,0 0,27 0,63 27,90 63,90 90,63 90,27 63,0" />
	
	<!-- This is the part which changes colour. -->
	<circle cx="45px" cy="45px" r="35px" stroke="black" stroke-width="5px"/>

</g>

Selector Switch

This shows a selector switch, which has both input and output functions.


<g mblogic:widgettype="ss2short" 
	mblogic:widgetname="2 Pos SS"
	mblogic:editcount="0"
	mblogic:menu='[
		{"type":"tag", "name":"Input Tag", "param":"inputtag", "value":""}, 
		{"type":"tag", "name":"Switch Tag", "param":"switchtag", "value":""}]'
	mblogic:inputfunc='[
		{"event": "onclick", 
		"func": "MBHMIProtocol.WriteToggleImmediate(\"%(inputtag)s\", \"%(inputtag)s\");"}]'
	mblogic:outputfunc='MBHMIProtocol.AddToDisplayList(new MB_2PosSSDisplay(document, 
		"%(widgetid)s", -60, 60), "%(switchtag)s", "read");'
	>

	<!-- This is a decorative nut. -->
	<polygon transform="translate(5,5)" fill="grey" stroke="none" filter="url(#MB_DropShadowFilter)"
		points="18,-45 -18,-45 -45,-18 -45,18 -18,45 18,45 45,18 45,-18 18,-45" />
	<polygon  fill="url(#MB_SilverGradient)" stroke="none"
		points="18,-45 -18,-45 -45,-18 -45,18 -18,45 18,45 45,18 45,-18 18,-45" />
	
	<g class="buttonactivate" >
		<!-- This forms the circular rotating inner area of the switch. -->
		<circle cx="0px" cy="0px" r="35px" fill="red" stroke="black" stroke-width="5px"/>
	
		<!-- This is the rotating actuator. -->
		<rect x="-8" y="-33" width="16" height="66" rx="5" fill="grey" stroke-width="2px"/>
		<polygon fill="white" points="0,-30 -5,-20 5,-20 0,-30" />

	</g>
	
</g>