Samstag, Januar 26, 2008

Data bound fields for Ajax forms

An overview of the Ajax forms implementation of the AjaxEngine framework has already been published some days ago at

Here are more details of the concept around binding html elements to Open Ajax events.


Client side API for data bound elements

The API for the data controls is unified as far as possible and for all the data controls the following common features are implemented:


If this attribute is set the the element will listen to and possibly publish an OpenAjax hub event to exchange the changed value through the eventing mechanism. If the value of the eventname attribute does not contain a full namespace but only the local name of the event, the eventnamespace attribute of any parent element is used to complete the namespace. This may be in many cases the surrounding DataFormBehavior element.


This attribute can be set to the name of the datatype of the values. This enables some datatype specific behavior implementation within the element for example converting the non-string datatypes to the specific notation. If this attribute is not set then the exchanged data will is used without any special formatting conversions and no other restrictions are applied. Just like a string type.

This attribute should not be changed by JavaScript. Use the setDatatype(type) method in the case you need that.


This method is available to set the value of the control directly by using JavaScript. This method is also used internally for all cases when the value of the control has to change. This method can be overwritten by other, derived controls.


This method is available to JavaScript implementations that need to access the value of a (input) field directly. Don't use the innerText or value attributes of an HTML element directly because there may be type conversion and/or translations necessary that are executed for your convenience when using this method.


When the datatype of an data item is not known when loading the page and by using the datatype attribute this method can be to pass the new datatype.

All the values that are exchanged between the Ajax form element and the inner data controls are using the format defined by the XML datatypes (here simply called the standard format) . This implies that the inner data controls have to take care about converting the values into some more useful formats and that the Ajax form and more important the server doesn't have to care about these specific formats.

There is also another way how values can be exchanged among different controls that is the OpenAjax event mechanism. Every time the Ajax form gets a new dataset is also published all the values by using the eventnamespace of the Ajax form. OpenAjax events are also used to sync the inner data controls that all deal with the same data item.

name attribute

This attribute of an inner element is not used. Using this attribute is heavily used by the classic HTML form mechanism. This still allows "hybrid" web pages where the user gets some advice and aid by using AJAX calls to the server but where the form.submit functionality is still used for the real processing of the data of the form.


Data bound elements and behaviors

DataOutput Controls

If you have data items that come from the server an that will not be changed by the user you can use the DataOutput control. The DataOutput Behavior only registers for the appropriate event that is specified through the eventname attribute and displays all published values inside the control.

The implementation uses a <span> element for displaying the values but other Controls that derive from DataOutput can also use different element eventually by overwriting the setData method. The setData method can also be used to display values when implementing directly with JavaScript.

It also takes care of the datatype attribute. If this attribute is set the given value in the standard format will then be converted into the national language specific notation within the setData method by using the nls object that will be described later.

The reference documentation can be found at

DataInput Controls

The DataInput component is a general purpose JavaScript Behavior based control that implements the functionality for binding a regular <input> element to OpenAjax events for building Ajax forms.

The implementation takes also care of the datatype in a special way by using the implementation of datatype specific functionality that are available through the nls object that will be described in a later article in detail.

  • When a key is pressed the keyCode / charCode of the pressed key is identified and only valid characters are passed. This allows to keep unwanted characters away from the field value in many cases. However it is possible to paste any character by using the clipboard so do not trust this tiny filter. It's only implemented to assist - not to prevent.
  • If a datatype is given, the XML values will be converted into the national language specific notation within the setData method or when an OpenAjax event with the appropriate eventname was published.
  • If a datatype is given, the national language specific notation of the input value will be converted back into the the XML value that is used on the server site within the getData method.
  • It the data is changed and the cursor leaves the field or the <enter> key is pressed, an OpenAjax event will be published using the standard format.

You can build more specific components based on this JavaScript Behavior by deriving from this implementation and adding some special features.

The reference documentation can be found at

The DataFade control

The DataFade Behavior implementation inherits from the DataOutput implementation and adds the Fade effect. Every time a new value is set into this element the background becomes yellow and is then smoothly fading to the original background color to attract the users attention.

A sample page for this effect can be found at

The reference documentation can be found at

Sonntag, Januar 06, 2008

Building menus with OpenAjax events

Implementing menus is often based on publishing events. I personally cannot remember any system that does not.

The web control that is used to implement menubars is therefore a good sample for a html, css and JavaScript based component that is extendable and completely relies on a declarative approach (also a widely used pattern menu system).


The html code for building a menubar is implemented by using an outer <div> element and on level of inner elements that can implement image-buttons, text-buttons and separators by using <span> and <img> html elements.

The look and feel of all the elements is defined by using CSS rules based on class names.

The class name "VEMenuBar" is used for the outermost element. Buttons are marked by using “VEMenu” and the separators are marked with the class name “VEMenuSeparator”.

Here is a small sample:  

<div class="VEMenuBar" eventnamespace="de.mathertel.datasource"> 
  <span class="VEMenu" eventname="search">Search</span> 
  <img class="VEMenuSeparator" alt="" src="../controls/images/white.gif" /> 
  <img class="VEMenu" alt="show first record" eventname="first" src="../controls/images/first.gif" /> 

Based on the class names the design can be specified. Some of the class names are modified when the hover effect is enabled on the page.

.VEMenuBar { background-color:#eeeeee;padding:2px 8px 2px 8px;height:20px;overflow:hidden;}

This defines the background color of the menubar. The padding definition will keep the inner icons away from the border.

.VEMenuBar * { vertical-align:top;}

All elements will be vertically aligned by the top.

.VEMenuBar span {display:-moz-inline-box;display:inline-block;}

<span> elements inside the menubar can be used to create buttons with a text caption. This rule is used to position span elements by using the padding.
The IE will use the inline-block rule and Mozilla/Firefox will use the -moz-inline-box rule. They both don't understand the other syntax and will just ignore it.

.VEMenu { border:0px;padding:2px}

This rule is used for the state of an icon that is not hovered or pushed. In my layout it has no border and is padding the graphic by using 2 pixels on every side.

.VEMenuHover { border-style:solid;border-width:1px;border-color: #acc1e4 #203050 #203050 #acc1e4;padding:1px}

This is the state of an icon when the mouse is over it but is not pushed. In my layout I use 1 pixel of border on every side with some colors that makes the icon look like being raised a little bit. I reduce the padding to 1px to avoid the shifting and flickering of the graphic.

.VEMenuPushed { border-style:solid;border-width:1px;border-color: #203050 #acc1e4 #acc1e4 #203050;padding:1px}

This is the state of a icon when the icon is pushed down. In my layout I use 1 pixel of border on every side but with different colors and I reduce the padding to 1 px to avoid the shifting and flickering of the graphic.

.VEMenuSeparator { display:inline-block;height:20px;width:1px;border-left:solid 1px #203050;}

Separators between groups of symbols are included by using a 1x1 white pixel image with a classname "VEMenuSeparator" that is displayed with a darker border on the left side.

Declaring and publishing events

Event publishing is the duty of this component. All that we need to declare is what event will be published by a inner element and that is done by using attributes of these elements.


This attribute that is valid on any nested element of the menubar’s outermost <div> element contains the event name that will be published when the element is clicked. This attribute may contain only a local event name or a full qualified eventname including the namespace.


This attribute that on the menubar’s outermost <div> element and specifies a namespace that is used for any eventnames that are not fully qualified.

(Fully qualified eventnames are determined by the fact that they contain a dot character.)

The menubar behavior (MenubarBehavior)

This behavior implements all the basic functionality for menubars. When bound to a html element it also loops through all the children elements on the first level an sets the hover attribute to true for those elements that have a class name "VEMenu". This allows enabling the hover effect without implementing the hover attribute for every menu item.

If you set the tabindex property on menu items another functionality is enabled. By setting tabindex to a value greater then 0 the element can get the focus either by using the tab key until you reach the right element or by using the menu with the mouse. When pressing the space bar while the focus is on a specific menuitem the onclick method of the menuitem will be called. This allows you to use the keyboard instead of clicking with the mouse and also allows repeating menu commands in an easy way.

When using ASP.NET it is easy to build a menubar by using the available web control:

<ve:MenuBar runat="server" eventnamespace="de.mathertel.edit"> 

The implementation in JavaScript is available here:

A sample page that uses this control is available here:

(see the source code of the page by using the view link in the upper right corner)

Mittwoch, Januar 02, 2008

More OpenAjax compatible components

The PersistCookie control

OpenAjax events are not persistent. The specification is based on the fact that the subscribers are informed just in time when the event was published. But by using cookies the passed values can survive a page refresh or even some days.

In some applications it is important that the values that where published by OpenAjax events and have changed the web application in a specific way are presenting the state of the client. With the PersistCookie control it is possible to save these simple values into cookies and makes them available when the page is reloaded the next time the page loads by publishing a new OpenAjax event. By using this control it is possible to reload a page in the state that was given when the user visited it the last time or when using the refresh button.

Using this functionality is easy by just including a ASP.NET control like this:

<ajax:PersistCookie runat="server" eventnamespace="jcl" eventname="view" />

The control is designed for persisting the values of multiple eventnames of the same eventnamespace and is providing a mechanism for default values in the case of a first time load of the page.

Using Cookies

Cookies do not have a namespace based mechanism as we can see in the OpenAjax hub specification so the names that are used within the cookies will not contain the namespace used by the OpenAjax event but will only use the local eventname.

Another advantage of not using the namespace to build cookie names is a better use of the available storage space of cookies.

If you have to store values by using the same name multiple times in your web application it is important that the part of each used cookie value is more specific than the standard root. The PersistCookie control therefore uses the current url of the page, extracts the folder part of it and uses this as the path to store the cookies. So, in most cases you will not have to specify the path attribute of this control.


This attribute can be used for specifying the namespace that contain the to be persisted events.

The default namespace is set to "jcl".


This attribute can contain a list of event names together with the default values. Then event names are separated by semicolons and the default values are appended to the names using the equal sign.


This attribute specifies a specific path for the cookie. If this attribute is not set the current url of the page is used to build a path that specifies the current folder. This avoids conflicts with other cookies used on the same web site.

You will have to set this attribute only if you want to share cookies over multiple pages in different folders.


This attribute specifies how long the cookie values should be stored.

If this attribute is not set the values are only kept in memory while the browser remains open.


<ajax:PersistCookie runat="server" eventnamespace="jcl" eventname="view" />
<ajax:PersistCookie runat="server" eventname="kosten=120000;jahre=4;kapital=999" runat="server" expire="2" />

You can find the implementation here: