CoovaEWT - Coova.Org

wiki

CoovaEWT

CoovaEWT, the Coova Embedded Web Toolkit, provides development tools to quickly and easily build a complete, highly dynamic, user interface to edit just about any configuration. There are two parts to the solution: 1) the GWT-based CoovaEWT application/library itself, and 2) a back-end service in the form of a CGI or another web technology (a Java servlet, for instance).

For some background information, see:

Concepts

To begin, here are some basic concepts explained.

Input Menus, Sets, and Boxes

The user interface is a series of menus represented as a tab in the main navigation bar. Two levels of menus are currently supported; menus and submenus. On each menu page, one or more Input Sets can be defined and associated with a configuration object. Each Input Set can contain Input Boxes or other Input Sets.

Dependencies

Input Boxes can be defined to have dependencies to other Input Boxes or Input Sets. This allows for the dynamic displaying and hiding of Input Boxes or Sets based on the values of others. For instance, hiding an entire Input Set or individual Input Boxes when a feature is clicked as disabled.

Singleton vs. List

A singleton is an object in the configuration where only one is expected. In the user interface, this is presented as a single form ready to be filled in. It is ideal for any system wide configurations. The alternative is defining an Input Set with singleton disabled. In this case, the user interface presents a list of entries, with each element given an edit and delete option, in addition to a create new button.

References and Services

When creating a user interface, some setting may reference other settings. For instance, you may want a select box of the available network interfaces when configuring an application that requires one. Within the UI XML, references can be made for this purpose. Additionally, using a "service", the data for a select box, for instance, can be fetched from the back-end dynamically.

Separating Data from Interface

CoovaEWT is currently being used in a number of ways. Combined with a simple CGI program written in C, it can be used for web interfaces on devices with limited resources - both in space and CPU power. No time, for instance, is wasted by the device rendering HTML. Or, the user interface itself can be put into Adobe AIR and be made into a desktop application - thereby completely separating the interface from the device (only requiring the super-small CGI on the device itself). CoovaEWT is also used with other back-ends, including Java, as it just requires the back-end to receive and send JSON encoded objects.

XML User Interface Definition

The user interface is defined in XML and is dynamically loaded by the GWT-based CoovaEWT application. When loading, the application requests the user interface from the back-end.

Text Box

Text input boxes are the simplest form of input. It allows the user to enter a value in a HTML text box, subject to verification based on the dtype parameter.

  <menu name="Demo">
    <menu name="Settings">
      <inputset name="Global Settings" object="my.settings">
        <input label="Setting Name" key="foo" dtype="word"/> 
        <input label="Other Setting" key="bar"/>
        <input label="Number" key="foi" dtype="int"/> 
      </inputset>
    </menu>
  </menu>

In the above example, the user interface shown on the right is defined. It is a simple form to popular some values (based on key) in the configuration object my.settings.

Select Box

By adding options to an Input Box, it turns into a Select Box, as the following example shows:

  <inputset name="Global Settings" object="my.settings">
    <input label="Setup Type" key="type">
      <option name="Disabled" value="off"/>
      <option name="Type1" value="type1"/>
      <option name="Type2" value="type2"/>
    </input>
    ...

Suggest Box

Similar to a Text Box, but will popup with suggestions as input is typed. The suggestions can either come from pre-configured options, similar to the options defined in a Select Box, or the suggestions can be dynamically retrieved from a Data Service.

  <inputset name="Attributes" service="table" table="radreply" 
        object="radreply" singleton="false">
    <input label="Username" key="username" required="true"></input>
    <input label="Attribute" key="attribute" 
        type="suggest" service="attributes" required="true"></input>
    <input label="Op" key="op">
      <option name=":= (set)" value=":="/>
      <option name="+= (add)" value="+="/>
      ...
    </input>
    <input label="Value" key="value"></input>
  </inputset>
  ...

Check Box

To make things more interesting, the above example is changed to a combination of a Check Box and a Select Box.

  <inputset name="Global Settings" object="my.settings">
    <input label="Enable My App" key="enabled" 
           type="check"value="true">
      <dependency value="true" change="setupType"/>
    </input>
    <input label="Setup Type" param="setupType" key="type">
      <option name="Type1" value="type1"/>
      <option name="Type2" value="type2"/>
    </input>
    ...

In this example, the select box is only shown when the check box is enabled due to the dependency rule. Note how the Setup Type input box was given the param of setupType. This is what is being referred to by the dependency rule's change parameter. A dependency can change (i.e. make visiible or hide) both input boxes and input sets, based on the unique param parameter in both cases.

VarList Box

A VarList is an input dialog to manage a simple list of string, stored in a text delimited field. So, it is similar to a text box (or a select box), but with the ability to add and remove elements.

  <inputset name="Global Settings" object="my.settings">
    <input label="List of values" type="varlist" 
           key="valuelist" delim=" " />
  </inputset>
   ...

File Box

Files can also be edited, subject to path verification in the back-end. This example shows a single file being edited.

  <inputset name="Edit a File">
    <input label="Edit test file" 
           type="file" 
           dir="/file/path" 
           file="test.txt"/>
  </inputset>
   ...

FileList Box

It is also common to want to allow the editing of a variety of template-based files. For this purpose, the following is possible:

  <inputset name="Edit Files">
    <input label="Edit Template" 
           type="filelist" 
           def="Select File"
           dir="/file/path">
      <option name="Style Sheet" 
              value="css.txt|css.tmpl"/>
      <option name="HTML Text" 
              value="html.txt|html.tmpl"/>
    </input>
  </inputset>
   ...

Help Box

Help sections can be placed in the right column of the page, as the following example illustrates:

  <inputset name="Some Settings" object="my.settings">
    ...
    <help label="About this feature" id="featureX">
    <![CDATA[ 
    Use this feature to do something better.
    <p/><b>Setup Type</b>: Select the setup type you want.
    <p/><a href="javascript:window.help('info');">more info</a>
    ]]>
    </help>
  </inputset>
  ...

Date Box

  <inputset name="Settings" 
            object="my.settings">
    <input label="Start Date" 
           key="startDate" 
           type="date" />
  </inputset>
  ...

Map Box

  <inputset name="Location Map" 
            object="my.location">
    <input type="map" 
           width="400px" height="250px" />
    <help label="Map help" 
          id="map"/>
  </inputset>
  <inputset name="Location Coordinates" 
            object="my.location">
    <input label="Latitude" 
           key="latitude" />
    <input label="Longitude" 
           key="longitude" />
    <help label="About location" 
         id="location"/>
  </inputset>
 ...

The help text is not shown (or even loaded) until the header is clicked. A back-end request is then performed to fetch the help text. Links to other help blobs are possible using the above syntax. Every help blob should be uniquely named with the id parameter.

Not a Singleton

All the examples above show various forms you can create to edit a singleton object in the configuration. Editing a list of objects in the configuration is made possible by adding the parameter singleton="false" to an Input Set, as in this example:

  <inputset name="Interfaces" 
            object="my.interface" 
            singleton="false">
    <input label="Name" 
           key="id" 
           required="true" 
           dtype="word"/> 
    <input label="Device" 
           key="dev" 
           ref="status.host.interface" />
    <help label="About this feature" 
           id="interface"/>
  </inputset>
  ...

A table is shown of all the objects in the list, each with an edit and delete link. When an entry is edited, or create new is selected, a form is presented, similar to that of a singleton. In this example, we have a list of Network Interfaces. The name is required and of type word (which means a single word, no spaces). The dev is defined as a reference to the status.host.interface list (a special status object with the systems network interfaces). The example also shows a help box referencing a help blurb defined externally.

XML Configuration

Throughout the above examples, you might expect a configuration like the following:

 <sysconfig>
   <my>
     <settings enabled="true" type="type2" 
               foo="name" bar="setting" foi="10"
               valuelist="entryOne entryTwo" />
     <interface id="ethernet" dev="eth0"/>
     <interface id="tun" dev="tun0"/>
   </my>
 </sysconfig>

where under the object my, there are the singleton settings and the list interface containing two objects. The interface objects are using the special parameter id making the list suitable for referring to -- another configuration select box to specify an interface, for example. The id field acts as a standard "unique key" for cross referencing objects.

Back-end Data Services

Once the CoovaEWT web application is loaded - in browser or desktop application - it interacts with the back-end data services. The CoovaEWT host CGI application is written in C with shell scripts to process the configuration and write out application specific configuration files. It has also been implemented in Java, following the same JSON encoding rules.