This section deals with creating pages in the WebBrick Gateway. There are a number of approaches depending on the required outcome. Most pages are written using the KID template template language. The benefit of this is that it enables a clean separation between data and style. It also allows us to generate user interface's that have 'standard' (for the installation) display elements on all pages, which are tailored for the end user.
BoilerPlate
All templated pages are based on the following boilerplate and this can be found as BoilerPlate.kid. It is this that pulls in the default headers and footers on each page.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:py="http://purl.org/kid/ns#" py:extends="'master.kid'">
${output_head("WebBrick Gateway Home page")}
<body>
${output_nav("WebBrick Gateway")}
Insert page specific code in here.
${output_site_info_bar()}
</body>
</html>
In this there is an header section, a call to generate a display header with standard navigation buttons. The page specific data then goes next followed by a call to generate a standard page footer (information area).
User interface Elements
An element on a page with a wbType attribute is generally a dynamic element and has associated javascript. Depending on wbType there may be other attributes.
The UI may have any of the following dynamic elements.
| wbType | Description |
| PushButton | sends a command when clicked or touched using wbTarget, displays the state of wbSource |
| Indicator | a variant of pushbutton that only displays state. |
| Numeric | displays a numeric value retrived using wbSource. |
| NumericBar | Used to display a numeric display as a grahical bar. |
| WbBackGround | Used to do dynamic updates to the display background using wbSource to retrive image name. |
| Caption | Que |
| PushSelect | Multiple push buttons |
| Text | display dynamic text retrived using wbSource |
| TextEntry | Not yet implemented |
| WbTimeDisplay | Used for formatted time display. |
| WbTimeEntry | Used for time display and to enter a time by a user performing updates. |
| WbDayEntry | Used for display and to enter a day or set of days by a user performing updates. |
| WbNumericEntry | Used for numeric display and to enter a numeric value by a user performing updates. |
| WbOnOffEntry | Used for On Off state display and for use to enter On Off or Ignore by a user performing updates. |
Common attributes on these dynamic elements are:
| attribute | Description |
| wbSource | URI providing the state to retrived and displayed |
| wbTarget | URI providing target for element command |
| wbLoad | name of javascript function used to start the dynamic element. If not given then a function called load<wbType> is looked for, where wbType is replaced by content of wbType attribute. |
An example of a simple push button would have this fragment in the template.
<td wbType="PushButton" wbLoad="loadButton()"
wbTarget="/wbcmd/heating.webbrick/DI/0"
wbSource="/wbsts/heating.webbrick/DO/0">
Ensuite Fan
</td>
PushButton, Indicator
A push button when selected uses the URI given in wbTarget to generate some action at the WebBrick Gateway, and uses the data retrived from the wbSource URI to control the look of button. This latter allows the button to show the state of an output or some other information. This element can also be used purely as an indicator by ommmiting the wbTarget attribute.
| attribute | Description |
| wbType | PushButton |
| wbSource | URI providing the state to retrived and displayed. The returned string is either a numeric string or one of the strings 'true','false','on','off'. |
| wbTarget | As Above |
| wbLoad | As Above |
| stateVals | contains a string of comma separated state names, if not given the state names 'Off' and 'On' are used |
| baseClassName | contains a base name for the CSS classes used by the element, if not given the base name'button' is used |
The state names and the baseClassName are used to set the CSS class name for this element based on the value returned by wbSource which is an index into the stateVals. The default CSS class names are buttonOff and buttonOn. This indicator functionality is intended to be used where the number of distinct values that wbSource returns are from a small set.
Default CSS class names.
| cssClass | Description |
| buttonOff | used when wbSource returns 0 or false or off |
| buttonOn | used when wbSource returns non zero or 'true' or 'on' |
An example of a slightly more complex push button would have this xhtml fragment in the template.
<td wbType="PushButton" wbLoad="loadButton()"
wbTarget="/wbcmd/garage/DI/4"
wbSource="/localstate/Garage/Door/1"
stateVals="Ajar,Closed,Open,Error"
baseClassName="door"
>
Garage Door
</td>
In this case we are getting the garage state in a processed form that returns a number between 0 and 3. The display element maps this to the states "Ajar,Closed,Open,Error". The baseClassName is used so the CSS class names used are "doorAjar,doorClosed,doorOpen,doorError". When the button is clicked then the webbrick input that corresponds to the correct digitral output connected to the door motor is activated. The target output could be aactioned directly but normally there will be a physical button as well.
Numeric
A numeric element retrives the numeric string using wbSource and displays it using formatting information provided to the wbLoad function.
| attribute | Description |
| wbType | Numeric |
| wbSource | URI providing the state to be retrieved and displayed. The returned string shouyld be a numeric string. |
| wbLoad | As Above, also the wbLoad function can take further parameters to control the formatting of the numeric. These are: prefix a string to put in front, a format string and postfix a string to puit after the number. |
Default CSS class names.
| cssClass | Description |
An example of a Numeric display would have this xhtml fragment in the template.
<td wbType="Numeric" wbLoad='loadNumericDisplay("CH Flow: ","##.#","ºC")'
wbSource='/wbsts/heating/Tmp/4'> </td>
This uses the extended load function to put a label before the value, specifies a format for the number and a postfix string to be put after the value. The td element has a non blank space so that the td is correctly formatted at load time before it has the value to display.
The wbSource for this element when displaying webbrick information is typically one of /wbsts/heating/Tmp/n, /wbsts/heating/AI/n, /wbsts/heating/AO/n.
NumericBar
A numeric bar displays a numeric value graphically.
| attribute | Description |
| wbType | NumericBar |
| wbSource | URI providing the state to retrived and displayed. The returned string is a numeric string. |
| wbLoad | As Above |
| minvalue | data value that corresponds to left hand end of scale. default is 0 |
| maxvalue | data value that corresponds to right hand end of scale. default is 100 |
| graphic0 | graphic image used for left hand section of display, default is /static/images/green.png |
| graphic1 | graphic image used for centre section of display, default is /static/images/red.png |
| graphic2 | graphic image used for right hand section of display, default is /static/images/green.png |
| curvalue | Initial value for display |
If the value retrieved is less than minvalue then the marker will be at the left hand end, if it is greater than maxvalue then the marker will be at the right hand end.
Default CSS class names.
| cssClass | Description |
An example of a NumericBar display would have this xhtml fragment in the template.
<td class='NumericBar' id='ambientTemp'
wbType="NumericBar"
wbSource='/wbsts/heating/Tmp/4'
minvalue="-5"
maxvalue="70"
graphic0="/static/images/clear.png"
graphic1="/static/images/WhiteVPointer.png"
graphic2="/static/images/clear.png"
curvalue="0"
height="10px" width='80%' >
</td>
In this case the default graphics have been replaced by alternates, that only display a white pointer. The range of the display is -5 to 70. We have also provided a height and width for the element.
WbBackGround
WbBackGround Used to do dynamic updates to the display background using wbSource to retrive image name. This is generally applied to the Body element by the master.kid template. It could be applied to other elements but this could result in messy displays.
| attribute | Description |
| wbType | BackGround |
| wbSource | URI providing the name of an image file to be used as the element background. |
| wbLoad | As Above |
Default CSS class names.
| cssClass | Description |
An example of a background display element would have this xhtml fragment in the template.
<body wbType="WbBackGround" wbSource="/localstate/background"> </body>Note that this is the default in master.kid and affects the complete display area. Most times it is not expected that this will be changed, but some weird effects could be caused by this. e.g.
<div wbType="WbBackGround" wbSource="/localstate/backgroundTop">
</div>
<div wbType="WbBackGround" wbSource="/localstate/backgroundMiddle">
<div wbType="WbBackGround" wbSource="/localstate/backgroundLeft">
</div>
<div wbType="WbBackGround" wbSource="/localstate/backgroundright">
</div>
</div>
<div wbType="WbBackGround" wbSource="/localstate/backgroundBottom">
</div>
You would need to set up the event handling to update the backgroundXxx states but this would result in different background images on different parts of the screen. An example may be for camera displays you may change background on a PIR trigger.
Caption
A caption is mainly a place holder for labeling the user interface, it is not currently dynamic.
| attribute | Description |
| wbType | Caption |
| wbSource | As Above |
| wbLoad | As Above |
Default CSS class names.
| cssClass | Description |
| caption | always used |
PushSelect
PushSelect
Multiple push buttons
| attribute | Description |
| wbType | Caption |
| wbSource | As Above |
| wbLoad | As Above |
Default CSS class names.
| cssClass | Description |
Text
Text Display dynamic text retrieved using wbSource
| attribute | Description |
| wbType | Caption |
| wbSource | As Above |
| wbLoad | As Above |
This has an alternate load function loadTextDisplay that takes optional prefix and postfix for the text. Default CSS class names.
| cssClass | Description |
| textPending | We are waiting for the text. |
| textAbsent | The text cannot be retrieved. |
| textPresent | The text has been retrieved. |
An example of a text display element would have this xhtml fragment in the template.
<td wbType="Text" wbSource="/"> </td>
TextEntry
Not yet implemented
| attribute | Description |
| wbType | Caption |
| wbSource | As Above |
| wbLoad | As Above |
Default CSS class names.
| cssClass | Description |
WbTimeDisplay
WbTimeDisplay Used for formatted time display.
| attribute | Description |
| wbType | Caption |
| wbSource | As Above |
| wbLoad | As Above |
Default CSS class names.
| cssClass | Description |
WbTimeEntry
WbTimeEntry Used for time display and to enter a time by a user performing updates.
| attribute | Description |
| wbType | Caption |
| wbSource | As Above |
| wbLoad | As Above |
Default CSS class names.
| cssClass | Description |
WbDayEntry
Used for display and to enter a day or set of days by a user performing updates.| attribute | Description |
| wbType | Caption |
| wbSource | As Above |
| wbLoad | As Above |
Default CSS class names.
| cssClass | Description |
WbNumericEntry
WbNumericEntry Used for numeric display and to enter a numeric value by a user performing updates.
| attribute | Description |
| wbType | Caption |
| wbSource | As Above |
| wbLoad | As Above |
Default CSS class names.
| cssClass | Description |
WbOnOffEntry
WbOnOffEntry Used for On Off state display and for use to enter On Off or Ignore by a user performing updates.
| attribute | Description |
| wbType | Caption |
| wbSource | As Above |
| wbLoad | As Above |
Default CSS class names.
| cssClass | Description |
Example Pages
Here we have some slightly more complex examples.NavigationPage
Here is an example of a page that purely provides navigation to other pages.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:py="http://purl.org/kid/ns#" xmlns:wb="http://id.webbrick.co.uk/"
py:extends="'master.kid'">
${output_head("Webbrick Gateway Home page")}
<!-- <link href="/static/css/wl-panel.css" rel="stylesheet" /> -->
<body>
${output_nav("Webbrick Gateway")}
<table class="navTable">
<colgroup span="4" width="25%"></colgroup>
<tr>
<wb:simpleLink target="/template/overview">Overview</wb:simpleLink>
<wb:simpleLink target="/template/garage">Garage</wb:simpleLink>
<wb:simpleLink target="/template/lighting">Lighting</wb:simpleLink>
<wb:simpleLink target="/template/heating">Heating</wb:simpleLink>
</tr>
<tr>
<wb:simpleLink target="/heating/list" label='Schedules'>Schedules</wb:simpleLink>
<wb:simpleLink target="/template/flashmeter">FlashMeter</wb:simpleLink>
<wb:simpleLink target="/template/flashbutton">FlashButton</wb:simpleLink>
</tr>
<tr>
<wb:simpleLink target="/template/security">Security</wb:simpleLink>
</tr>
<tr>
<wb:simpleLink target="/mediaaccess/showlist">Play Video Here</wb:simpleLink>
<wb:simpleLink target="/mediapanel?mediatitle=Video&medianame=VlcAccess">Video</wb:simpleLink>
<wb:simpleLink target="/mediapanel?mediatitle=iTunes&medianame=ITunesInDirect">iTunes</wb:simpleLink>
</tr>
<tr>
<wb:simpleLink target="/wbcnf/">WebBrick manager</wb:simpleLink>
<wb:simpleLink target="/wbsts/known">Known WebBricks</wb:simpleLink>
<wb:simpleLink target="/userinterface">Configure UI</wb:simpleLink>
</tr>
<tr>
<wb:simpleLink target="http://www.WebBrickSystems.com"><img src='/static/images/WebBrickSystems.png'/></wb:simpleLink>
</tr>
</table>
${output_site_info_bar()}
</body>
</html>
The core of this is a table containing td elements all with an onClick attribute, this means when the use clicks or touches the data element the browser is redirected to a new page. The pages with URIs that start /template do not require any extra data from the WebBrick Gateway and are then just build from the named template, i.e. Lighting loads template lighting.kid from the templates directory. other URIs generally require extra data from the WebBrick Gateway, for example heating schedule where the number of devices is configued elsewhere.
Heating
Here is an example of a page for creating a panel for control of central heating and hot water.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:py="http://purl.org/kid/ns#" xmlns:wb="http://id.webbrick.co.uk/"
py:extends="'master.kid'">
${output_head("Webbrick Gateway Heating")}
<body>
${output_nav("Heating")}
<table>
<colgroup span="4" width="25%"></colgroup>
<tr>
<wb:caption>Upstairs Zone</wb:caption>
</tr>
<tr>
<wb:simpleButton wbTarget="/wbcmd/test/DI/0" wbSource="/wbsts/test/DO/0">
Ensuite Fan
</wb:simpleButton>
<wb:simpleButton wbTarget="/wbcmd/test/DI/1" wbSource="/wbsts/test/DO/1">
Zone Valve
</td>
</tr>
</table>
<table>
<colgroup span="4" width="25%"></colgroup>
<tr>
<wb:caption colspan="4">Heating and Ventilation</wb:caption>
</tr>
<tr>
<wb:simpleButton wbTarget="/wbcmd/test/DI/5" wbSource="/wbsts/test/DO/5">
Boiler
</wb:simpleButton>
<wb:simpleButton wbTarget="/wbcmd/test/DI/2" wbSource="/wbsts/test/DO/2">
Radiator Valve
</wb:simpleButton>
<wb:simpleButton wbTarget="/wbcmd/test/DI/3" wbSource="/wbsts/test/DO/3">
Radiator
</wb:simpleButton>
</tr>
</table>
<table>
<tr>
<wb:caption>Key Temperatures</wb:caption>
</tr>
<tr>
<td width='50%'>
<table class='compositeWidget'>
<tr>
<wb:numericDisplay prefix="CH Flow: " format="##.#" postfix="ºC"
wbSource='/wbsts/test/Tmp/4' width='20%'>
</wb:numericDisplay>
</tr>
<tr>
<td class='NumericBar'><img src="/static/images/tempfade.png" width="100%" height="10"/>
</td>
</tr>
<tr>
<td class='NumericBar' id='ambientTemp'
wbType="NumericBar"
wbSource='/wbsts/test/Tmp/4'
minvalue="-5"
maxvalue="70"
graphic0="/static/images/clear.png"
graphic1="/static/images/WhiteVPointer.png"
graphic2="/static/images/clear.png"
curvalue="0"
height="10px" width='80%' >
</td>
</tr>
</table>
</td>
<td width='50%'>
<table class='compositeWidget'>
<tr>
<wb:numericDisplay prefix="CH Return: " format="##.#" postfix="ºC"
wbSource='/wbsts/test/Tmp/0' width='20%'>
</wb:numericDisplay>
</tr>
<tr>
<td class='NumericBar'><img src="/static/images/tempfade.png" width="100%" height="10"/>
</td>
</tr>
<tr>
<td class='NumericBar' id='ambientTemp'
wbType="NumericBar"
wbSource='/wbsts/test/Tmp/0'
minvalue="-5"
maxvalue="70"
graphic0="/static/images/clear.png"
graphic1="/static/images/WhiteVPointer.png"
graphic2="/static/images/clear.png"
curvalue="0"
height="10px" width='80%' >
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td width='50%'>
<table class='compositeWidget'>
<tr>
<wb:numericDisplay prefix="HW Flow: " format="##.#" postfix="ºC"
wbSource='/wbsts/test/Tmp/2' width='20%'>
</wb:numericDisplay>
</tr>
<tr>
<td class='NumericBar'><img src="/static/images/tempfade.png" width="100%" height="10"/>
</td>
</tr>
<tr>
<td class='NumericBar' id='ambientTemp'
wbType="NumericBar"
wbSource='/wbsts/test/Tmp/2'
minvalue="-5"
maxvalue="70"
graphic0="/static/images/clear.png"
graphic1="/static/images/WhiteVPointer.png"
graphic2="/static/images/clear.png"
curvalue="0"
height="10px" width='80%' >
</td>
</tr>
</table>
</td>
<td width='50%'>
<table class='compositeWidget'>
<tr>
<wb:numericDisplay prefix="HW Return: " format="##.#" postfix="ºC"
wbSource='/wbsts/test/Tmp/1' width='20%'>
</wb:numericDisplay>
</tr>
<tr>
<td class='NumericBar'><img src="/static/images/tempfade.png" width="100%" height="10"/>
</td>
</tr>
<tr>
<td class='NumericBar' id='ambientTemp'
wbType="NumericBar"
wbSource='/wbsts/test/Tmp/1'
minvalue="-5"
maxvalue="70"
graphic0="/static/images/clear.png"
graphic1="/static/images/WhiteVPointer.png"
graphic2="/static/images/clear.png"
curvalue="0"
height="10px" width='80%' >
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<table class='compositeWidget'>
<tr>
<wb:numericDisplay prefix="Ambient: " format="##.#" postfix="ºC"
wbSource='/wbsts/test/Tmp/3' width='20%'>
</wb:numericDisplay>
</tr>
<tr>
<td class='NumericBar'><img src="/static/images/tempfade.png" width="100%" height="10"/>
</td>
</tr>
<tr>
<td class='NumericBar' id='ambientTemp'
wbType="NumericBar"
wbSource='/wbsts/test/Tmp/3'
minvalue="-5"
maxvalue="40"
graphic0="/static/images/clear.png"
graphic1="/static/images/WhiteVPointer.png"
graphic2="/static/images/clear.png"
curvalue="0"
height="10px" width='80%' >
</td>
</tr>
</table>
</td>
<td> </td>
</tr>
</table>
${output_site_info_bar()}
</body>
</html>
The termperature display actually consists of multiple display elements, one displays the temperature textually and the other graphically, there is also an image between the two elements as a separator and to add a slightly different look and feel to the display.
PushButton examples
An Active Section
This section contains controls that send events to WebBricks, where they are acted upon:<table> <tr> <td wbType="PushButton" wbLoad="loadButton()" wbTarget="/wbcmd/heating.webbrick/DI/0" wbSource="/wbsts/heating.webbrick/DO/0">Ensuite Fan</td> </tr> </table>
Here there are several things to note, first lets examine the td that starts wbType="PushButton":
- wbType This sets the type of widget that will be rendered on the page, in this case "PushButton"
- wbTarget This is a URI that points to the resource that will be commanded if the widget is cleanly clicked.
- wbSource This is a URI that points to the resource that will be used to render the state of the widget.
To explain further: The WebBrick Gateway makes extensive use of the URI Universal Resource Identifier construction. As a design goal, all practicable inputs should be available as URI's. Here's a break down of the URI:
/wbcmd/heating.webbrick/DI/0
Generically this is /type/IPaddressOrName/object/index. Taking the example above, we have a command /wbcmd to a WebBrick called "heating.webbrick". The command is directed to the digital inputs /DI and the index is /0 i.e. the first digital input (Digital input 1)
Creating an indicator
An indicator differs from a button in two key ways:
- Operation: There is no command to be issued, therefore an indicator is not clickable.
- Representation: An indicator can represent a wide range of states, from simple On-Off through Alarm-Clear to more complex schemes. For example a garage door may have the states Open-Closed-Ajar-Error.
Within the WebBrick Gateway, the treatment is similar to a button, but somewhat extended, here is an example:
<td wbType="Indicator" wbLoad="loadButton()"
wbSource="/wbsts/kitchen/DI/3"
stateVals="Clear,NotReady"
baseClassName="indicator">
Coffee Ready
</td>
The parameters are
- wbType: Tells the WebBrick Gateway what kind of widget to render on the page.
- wbLoad: Calls the initialization code.
- wbSource This is a URI that points to the resource that will be used to render the state of the widget.
- stateVals: This is a list of states that the indicator can have. These states are numbered from 0 Zero.
- baseClassName: This is the Class Name as found in the CSS stylesheet. The actual class used is made up from baseClassName + currentState
