CometVisu/Config

From CometVisu
Jump to: navigation, search

NOTE

This page will be updated to the new configuration syntax that is used in the current SVN versions.

This is incompatible to the syntax used in the releases till 0.5.2. For those releases please consult the older verion of this page that you can find under [1]

Old Text

The configuration of the CometVisu templating engine is done with a simple XML file. The minimal set up looks like

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<pages>
  <meta>
    <plugins>
    </plugins>
    <mappings>
    </mappings>
    <stylings>
    </stylings>
    <statusbar>
    </statusbar>
  </meta>
  <page name="Foo">
  </page>
</pages>

Meta

The meta section contains configuring information about the page. Non of it's content is directly visible but it defines how the pages will look like. It contains elements as described in the next sections.

Plugins

This defines the plugins to load. All plugins must be available in the corresponding subdirectory under "plugins".

    <plugins>
      <plugin name="colorchooser" />
    </plugins>

This example loads the plugin "colorchooser".

Mappings

The mappings allow to define representations for values on the bus.

    <mapping name="OnOff">
      <entry value="0">Off</entry>
      <entry value="1">On</entry>
    </mapping>

Each mapping consists out of an <mapping> tag with a name attribute inside the <mappings> section. Inside this tag can be multiple <entry> tags that define with their value attribute the content that is displayed when the value is sent on the bus.

To specify a range the range_min and range_max attributes might be used, like in this example:

    <mapping name="Sign">
      <entry range_min="-1e99" range_max="0">Negative</entry>
      <entry value="0">Zero</entry>
      <entry range_min="0" range_max="1e99">Positive</entry>
    </mapping>

Please note, that the entries having only a value will have a higher priority than the elements with a range. So the example above works as expected.

Stylings

The styling section works like the mapping section.

    <styling name="RedGreen">
      <entry value="0">red</entry>
      <entry value="1">green</entry>
    </styling >

This section maps CSS classes to the corresponding values on the bus.

If a info block (see below) would look like

<info address="1/2/3"  datatype="1.001" mapping="OnOff" styling ="RedGreen">Main supply</info>

and the right CSS is included, it would result in a entry in the visualisation that would look like

Main supply On

or

Main supply Off

Statusbar

This section defines the content of the status bar (usually the footer of the page).

    <statusbar>
      <status type="html">
        <![CDATA[
          <img src="icon/comet_64_ff8000.png" alt="CometVisu" /> by <a href="http://www.cometvisu.org/">CometVisu.org</a>
          - <a href=".">Reload</a>
        ]]>
      </status>
    </statusbar>

All <status> elements are concatenated and inserted in the status bar. The <status> element might contain an condition attribute. There are currently two possible values defined:

  • edit
  •  !edit

This will show the content of that tag conditionally if the visualisation is currently in edit mode ("edit") or not ("!edit").

Pages

This is the main section of the XML file. This defines all pages and their elements you want in the visualization.

Attributes

The pages-tag has a single attribute to select one of the available designs.

<page>

The page-tag defines groupings and hierarchy of elements on the visualization. Each page-tag can be nested in other page-tags to allow for subpages to be created. The content of the page-tag is any combination of element-tags or pages.

Attributes

The page-tag has only one valid attribute:

name
the name of the page is displayed on the visulization page
if the page is a subpage, this text will be used as the label for linking to the subpage on its parent
type
the type might be text, 2d (not implemented!) or 3d (not implemented!) and describes the kind of page.
src
the src attribute is only needed if the page type is 2d and describes the background image of the page.
flavour
the optional flavour attribute selects for that page one of the variants of the selected designs (if available).

Example-Code

To have a set of subpages on a page named "main" you could use code like this:

<page name="main">
  <page name="first floor">
  [...fill in some elements here...]
  </page>
  <page name="second floor">
  [...fill in some elements here...]
  </page>
</page>

<text>

The text-tag defines static (non-changing) text to be displayed on a page. The content of a text-tag is free text.

Attributes

The text-tag has no valid attributes.

<toggle>

A toggle-tag is used to both display and change the state of an address. toggle only knows two different states (e.g. 0 and 1) and toggles between them each time the element is pressed. The content of this tag is used as a label for this element on the visu.

In standard-configuration, this element is displayed as a button.

Exemplary usage: to toggle lights (on/off)

Attributes

address
defines which address to use for sending the new value to when the element is pressed
new values sent to this address by other sources (from e.g. a different client or a device on the bus) will be used to update the element
datatype
which datatype (DPT-notation, e.g. 1.001) to use for sending the new value
response_address
defines which address to listen to for receiving additional value-updates
this is needed to allow for changes that happen not by sending a new value, but by other means (e.g. by a programmed timeout on the addressed actuator)
also needed if the addressed actuator listens to more than one address, it can propagate a new status on this address
response_datatype
which datatype (DPT-notation, e.g. 1.001) to use for decoding new values received on response_address
pre
text to be prepended to the current value of the address
is displayed inside the element/button
is also applied to mapped values - please see mapping for details
post
text to be appended after the current value of the address
is displayed inside the element/button
is also applied to mapped values - please see mapping for details
mapping
please see documentation on mappings
styling
please see documentation on stylings

<trigger>

A trigger-tag is used to send a fixed value to an address. trigger does not care about changes of an address, nor does it know about any other value than the one it's defined with in the configuration. The content of this tag is used as a label for this element on the visu.

In standard-configuration, this element is displayed as a button.

Exemplary usage: to send the stop-command for a blind.

Attributes

address
defines which address to use for sending the new value to when the element is pressed
datatype
which datatype (DPT-notation, e.g. 1.001) to use for sending the new value
value
defines the one single value this element can send
pre
text to be prepended to the value of the address
is displayed inside the element/button
is also applied to mapped values - please see mapping for details
post
text to be appended after the value of the address
is displayed inside the element/button
is also applied to mapped values - please see mapping for details
mapping
please see documentation on mappings
styling
please see documentation on stylings

<info>

An info tag is used to display the value of an address. It is non-interactive, but changes the text when changes to the addresses value happen. The content of this tag is used as a label for this element on the visu.

Exemplary usage: to display outside temperature

Attributes

address
defines which address to use to listen to for value-changes
datatype
which datatype (DPT-notation, e.g. 9.001) to use for decoding a received value
pre
text to be prepended to the current value of the address
is displayed inside the element/button
is also applied to mapped values - please see mapping for details
post
text to be appended after the current value of the address
is displayed inside the element/button
is also applied to mapped values - please see mapping for details
mapping
please see documentation on mappings
styling
please see documentation on stylings

Example-Code

To display a temperature you could use an xml-code like:

<info address="7/6/0" datatype="9.001" pre="ca. " post=" °C">outside temperature</info>

<slide>

slide is used for displaying a slider input and sending an absolute value, by default between 0 and 100. It reacts to changes of the address and adjusts the displayed value accordingly. The content of this tag is used as a label for this element on the visu.

Exemplary usage: for changing the dimming-level of some lights.

In default configuration, the slide-tag is displayed as a slider. If the value of the address is changed, the change will be animated.

Attributes

address
defines which address to use for sending the new value to when the element is pressed
new values sent to this address by other sources (from e.g. a different client or a device on the bus) will be used to update the element
datatype
which datatype (DPT-notation, e.g. 1.001) to use for sending the new value
response_address
defines which address to listen to for receiving additional value-updates
this is needed to allow for changes that happen not by sending a new value to the address, but by other means (e.g. by a programmed fading/dimming on the addressed actuator)
also needed if the addressed actuator listens to more than one address, it can propagate a new status on this address
response_datatype
which datatype (DPT-notation, e.g. 5.010) to use for decoding new values received on response_address
min
change the minimal value of the silder. When not set, it defaults to 0
max
change the maximal value of the slider. Wehen not set, it defaults to 100
step
change the step size of the slider. When not set, it defaults to 0.5
mapping
please see documentation on mappings
styling
please see documentation on stylings

<dim>

dim is used to display a widget for dimming lights. It is basically the same as the slide tag.

<switch>

switch-tags are basically like toggle, but will be able to handle more than two states (which is not implemented yet). Please feel free to use switch-tags already in your configuration. Attributes, content and display can be taken from the documentation for toggle.

<line>

A line tag is used to display a horizontal line in the browser to allow for a grouped and thereby tidy display of elements on one page. This tag has no content and should only be used as <line /> in the configuration.

Attributes

A line-tag has no attributes.

<break>

A break tag is used to start in new line for a grouped and thereby tidy display of elements on one page. This tag has no content and should only be used as <break /> in the configuration.

Attributes

A break-tag has no attributes.

<image>

image is used for displaying an image or webcam that works by regularily updating an image. The content of this tag is used as a label for this element on the visu.

Attributes

src
defines the address for the image
width
the width of the image to show. This attribute is optional. It has to be a valid CSS value, like 100px.
height
the height of the image to show. This attribute is optional. It has to be a valid CSS value, like 100px.
refresh
the time after that the image is reloaded in seconds. This attribute is optional and defaults to "0" which is no refresh at all.

<video>

video is used for displaying an HTML5 video. The content of this tag is used as a label for this element on the visu.

Attributes

The attributes are the same as those for the image tag.

<iframe>

iframe is used for displaying an iframe, i.e. an embedded web page. The content of this tag is used as a label for this element on the visu.

Attributes

src
defines the address for the image
width
the width of the image to show. This attribute is optional. It has to be a valid CSS value, like 100px.
height
the height of the image to show. This attribute is optional. It has to be a valid CSS value, like 100px.
frameborder
draw a border around the iframe (yes or no). This attribute is optional. If not provided a border will be displayed.
background
change the default background behaviour from transparent to a provided color. This attribute is optional. It has to be a valid HTML value, like #000000.