Aspects of AJAX

How to read cookie values in JavaScript

2009-12-05T20:22:00.003+01:00

I recently had some odd effects with some pages that use cookies to store some local information. The bug seems to be widely spread in many web applications so here are my findings:

To read the value of a specific cookie that was set previously you have to analyze the string in document.cookie that contains all cookies. It’s a very readable format and looks like:

a=a101; aha=aha101; bob=bob101; b=b101; c01=c0101

The trick is to find the right cookie in this string and extract the value.

I used a JavaScript function, named getCookie() that searched for the position of the cookie name by using

start = document.cookie.indexOf(name + "=");

… and this is wrong in some cases.

If you search for the cookie named "b" in the sample above you will get a starting-position within the cookie named "bob" because the indexOf function stops at the first occurrence of the text "b=".

This seems to be a very common approach and some educational web sites still publish this kind of code that contains the mistake.

http://www.w3schools.com/js/js_cookies.asp

It’s easy to fix this line by including the space character:

var start = document.cookie.indexOf(" " + name + "=");
if (start >= 0) {
  start += 1
} else if (document.cookie.indexOf(name + "=") == 0) {
  start = 0;
} // if

But there is a more elegant solution when using regular expressions and even the retrieval of the value gets easier that I found at

http://www.elated.com/articles/javascript-and-cookies/

Here is the full function:

function get_cookie (cookie_name)
{
  var results = document.cookie.match('(^;) ?' + cookie_name + '=([^;]*)(;$)');
  if (results)
    return (unescape(results[2]));
  else
    return (null);
}

Check your code.

Extending the initialization sequence of JavaScript behaviors

2008-11-15T23:49:00.001+01:00

This topic was recently discussed in the OpenAjax group and here is the implemented solution for the AjaxEngine framework. The consensus was to solve the initialization problem on the application level and not within the OpenAjax hub.

When multiple components resist side by side on the same page the initialization sequence of the components can become critical for the page to work as expected. Therefore the JavaScript behavior mechanism supports 3 phases of initializing the application when a page loads:

The optional init() method is called first for every control that was initialized by LoadBehavior. This method should contain all initialization code that puts the control in a fully working state. Especially the control should register for any interesting OpenAjax event.
The optional initstate() method is called then and allows the control to inform other controls about their existence and publish state information by using OpenAjax events or direct method calls if appropriate.
The optional afterinit() method is called at last to controls can finish the setup where all other controls are also working.

All controls can participate in the initialization phases by implementing the calls. They are all optional. All 3 methods will be called when the onload event is raised for the window object.

The term method

Another method named "term" can be defined in the JavaScript prototypes to implement a method that is called just before a page unloads. There is a real need for implementing code just before all HTML and JavaScript objects are thrown away in Microsoft Internet Explorer, because there is a well known problem with the memory management used by the HTML DOM and JavaScript. Both object libraries do have their own garbage collector implementation and in some cases circular references between objects of both worlds are not properly detected and memory will not get freed and useless memory consumption is the unwanted result.

The best solution against this “design weakness” is to set all references of JavaScript variables to HTML elements to null in this method.

There is also a great tool and some more background information available that helps to detect this kind of memory leak named Drip available at http://outofhanwell.com/ and is a definitive TO-DO when supporting older browser versions of IE.

How to set up a web project using the AjaxEngine – Part 1b

2008-07-07T23:56:00.001+02:00

Some days ago I posted part 1a - a short instruction about how to set up a minimal project.

The sample I used to demonstrate that the infrastructure works was as simple as possible and is using a RPC style of Ajax calls to the server. Some topics have not been touched so here they come.

How to get the files

The easiest way to get all the files I’ve talked about is to go get them directly from the repository hosted as sourceforge.

http://sourceforge.net/projects/ajaxengine/ is the projects's home page and you can browse the repository directly by using the url http://ajaxengine.svn.sourceforge.net/viewvc/ajaxengine/trunk/.

Here all the development progress will be available as soon as soon as I write about it.

Another possible way to get the files is to use a subversion client for example http://tortoisesvn.tigris.org/ that includes more functionality like getting a copy of all the current files at once, looking into the change log and comparing different versions of the same file.

From time to time the download archives are updated too. You can find them on my site at http://www.mathertel.de/AjaxEngine/#view=Downloads

Calling web services the right way

I have to mention, that this is not the best way of calling a server because synchronous calls may block or freeze the client during the call and the call time may be very long when the network or the server is used a lot. Using asynchronous calls is the answer to that problem and there is simple but great mechanism inside the ajax.js file that makes asynchronous programming quiet easy. Here is just a brief explanation of how to use it. More of the mechanism and it's options can be found in the book Aspects of Ajax.

The typical AJAX scenario follows the following pattern and can be split into 4 separate problems:

Waiting for an event that will start the Ajax call to the server.
Sometime that’s an easy thing to do, because there is a button clicked and we just can attach the initializing code to an event. But sometimes events have to be queued up to avoid a race condition and get wrong answers.
Collecting some data on the client side.
It is often necessary to do this right before you call the server and not in the moment when the call is initiated.
Communication with the server.
That is done by using the client stub that is generated for each SOAP based web service.
Finally using the result from the server.
That must be done, when the data is available and is the typical asynchronous functionality of Ajax.

Many grown-up Ajax implementations are using a JavaScript object that binds the JavaScript functions that all together will solve the scenario and so does the AjaxEngine:

// declare an AJAX action
var action1 = {
  // the prepare function collects and returns the data for the server side method.
  // It just returns an array with the parameters and marks it with "multi".
  prepare: function(obj) {
    var p = [];
    p[0] = document.getElementById("n1").value;
    p[1] = document.getElementById("n2").value;
    p.multi = true; // the hint for the ajax Engine
    return (p);
  },

  // the call element points to the proxy for the server call as usual
  call: proxies.CalcService.AddInteger,
  
  // the result will be written it into the appropriate html field.
  finish: function (p) { document.getElementById("outputField").value = p; }
} // action1

This action can be used to start an Ajax call by using some inline code like this:

<input id="n1" onkeyup="ajax.Start(action1)" />

Now Ajax starts getting robust enough in a real web application.

The code is from the sample that you can find in the sample at

http://www.mathertel.de/AJAXEngine/S02_AJAXCoreSamples/CalcAJAX.aspx

Calling WCF and SOAP based webservices from AJAX

2008-07-06T00:15:00.001+02:00

The JavaScript proxy that is implemented for the Ajax engine to call SOAP based web services has been used on the ASP.NET platform for a long time and was ported to other platforms like Java. Some derived work can also be found for PHP and the Qooxdoo. It’s pretty stable for a while and that’s a good message.

When working with some specific Java based platforms there was a specific problem with the automatic generated WSDL descriptions, because they use an external schema for defining the structure of the passed data:

<wsdl:types> 
  <xsd:schema targetNamespace="http://tempuri.org/Imports"> 
    <xsd:import schemaLocation=http://localhost/AJAXEngine/S02_AJAXCoreSamples/CalcFactors.svc?xsd=xsd0
      namespace="http://tempuri.org/" /> 
    ... 
  </xsd:schema> 
</wsdl:types>

The workaround was to write the JSON structure that is used by the JavaScript proxy by hand (and that is still a good idea for high trafic web sites).

When adopting the WCF .svc services this kind of using WSDL and XML schema definitions can be found too.

A solution for this is quiet simple and can now be found in the wsdl.xslt and the GetJavaScriptProxy.aspx files.

wsdl.xslt

The WSDL to JavaScript transformation now looks for import nodes under the wsdl:types and then imports the referenced schema by using the xslt document() function. Then this imported document is searched for the right element and the parameter and return value description is generated through the soapElem template. Here is the added xslt code:

<xsl:when test="/wsdl:definitions/wsdl:types/s:schema/s:import">
  <!-- importing an external schema –>
  <xsl:variable name="inputElementName" select="substring-after(wsdl:part/@element, ':')" />
  <xsl:for-each select="/wsdl:definitions/wsdl:types/s:schema/s:import">
    <xsl:variable name="doc" select="document(@schemaLocation)"/>
    <xsl:for-each select="$doc/s:schema/s:element[@name=$inputElementName]//s:element">
      <xsl:call-template name="soapElem">
        <xsl:with-param name="name" select="@name" />
        <xsl:with-param name="type" select="@type" />
      </xsl:call-template>
      <xsl:if test="position()!=last()">,</xsl:if>
    </xsl:for-each>
  </xsl:for-each>
</xsl:when>

GetJavaScriptProxy

In the .NET environment the document function will not work for security reasons without some special instructions for the xslt transform. When passing a XmlUrlResolver when loading the xslt file the document() function can retrieve the referenced external document.

XmlUrlResolver resolver = new XmlUrlResolver();
resolver.Credentials = CredentialCache.DefaultCredentials;

XslCompiledTransform xsl = new XslCompiledTransform();
xsl.Load(Server.MapPath("~/ajaxcore/wsdl.xslt"), XsltSettings.TrustedXslt, resolver);

Implementing a WCF service for Ajax

Implementing a WCF service for Ajax is almost as simple as programming an *.asmx based service but you can also use an external C# class or interface for implementing the service.

You can find a sample source code in:

http://www.mathertel.de/AJAXEngine/S02_AJAXCoreSamples/CalcFactors.svc

The configuration

By default the WCF services use the SOAP 1.2 format but we don’t need the ws-* functionality and the soap basic profile is perfect for using webservice with AJAX solutions. This can be done by using the following configuration in web.config:

<system.serviceModel>
  <behaviors>
    <serviceBehaviors>
      <behavior name="AjaxBehavior">
        <serviceMetadata httpGetEnabled="true" />
        <serviceDebug includeExceptionDetailInFaults="false" />
      </behavior>
    </serviceBehaviors>
  </behaviors>

  <services>
    <service behaviorConfiguration="AjaxBehavior" name="CalcFactors">
      <endpoint address="" binding="basicHttpBinding" contract="CalcFactors" />
    </service>
  </services>
</system.serviceModel>

How to setup a new AjaxEngine web project

2008-06-22T20:47:00.001+02:00

I was asked how to setup a web project that uses the AjaxEngine so here is step by step tutorial for a minimal Ajax web project that calls a server side web service:

1. Create a new web project (I prefer using c#) or use your existing web project.

I started with a new project and named it "mini". There is nothing special that you have to set up. It even works without a web.config.

2. Copy the ajaxcore folder to your project.

You can find this folder and the files on sourceforge http://sourceforge.net/projects/ajaxengine/
in the subversion repository by using the path https://ajaxengine.svn.sourceforge.net/svnroot/ajaxengine
or in one of the source code downloads like http://www.mathertel.de/Downloads/Start_AJAX_new.aspx.

For this project you only need the following core files
ajax.js: the client side AjaxEngine

GetJavaScriptProxy.aspx: the JavaScript proxy generator
wsdl.xslt: the WSDL to JavaScript transformation

That’s all you have to do to prepare the web project to use the core part of the AjaxEngine. I suggest you use the ajaxcore folder

3. Create a folder named "/calc"

This folder will contain the minimal web application by using a web form and a web service.

I guess you don't implement pages in the root folder of your web application so I follow this best practice here too.

4. Implement a service /calc/WebService1.asmx

There is only one method we need so here is some c# code:

using System.ComponentModel;
using System.Web;
using System.Web.Services;
using System.Web.Services.Protocols;

namespace mini.calc {
  /// 
  /// Summary description for WebService1
  /// 
  [WebService(Namespace = "http://tempuri.org/")]
  [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
  // To allow this Web Service to be called from script, using ASP.NET AJAX, uncomment the following line. 
  // [System.Web.Script.Services.ScriptService]
  public class WebService1 : System.Web.Services.WebService {

    [WebMethod]
    public double Add(double sum1, double sum2) {
      return (sum1 + sum2);
    }
  }
}

5. Create a new page named WebForm1.aspx in the calc folder

I just use the new item wizard from visual Studio to do this so the typical elements are there already.
There is not much code that must be put into this file.

6. include the ajax.js:

<script src="../ajaxcore/ajax.js" type="text/javascript"></script>

The ajax.js file reference should be included in the <head> element.

7. include the proxy for the webservice:

<script src="../ajaxcore/GetJavaScriptProxy.aspx?service=/calc/WebService1.asmx" type="text/javascript"></script>

This script include should also be included in the <head> element and will make the just implemented webservice and webmethod available through the JavaScript object proxies.WebService1.Add.

8. Implement the User interface

A minimalist UI means just 3 fields and some text.
You also have to remove the <form> element because the fields are not used to post data to the server.

<input id="sum1" type="text" /> + <input id="sum2" type="text" /> = <input id="result" type="text" />

9. Implement the JavaScript code

This is the trickiest part of it, but it's simple too:
A timer is used to call a function every 200 milliseconds that checks for some changed input values.
The web service is called if any value has changed.

<script type="text/javascript">
  var sum1_obj = document.getElementById("sum1");
  var sum2_obj = document.getElementById("sum2");
  var result_obj = document.getElementById("result");
  var sum1_val = "";
  var sum2_val = "";

  window.setInterval(window.checkValues, 200);
  
  function checkValues() {
    if ((sum1_obj.value != sum1_val) || (sum2_obj.value != sum2_val)) {
      sum1_val = sum1_obj.value;
      sum2_val = sum2_obj.value;
      
      result_obj.value = proxies.WebService1.Add(sum1_val, sum2_val);
    } // if
  } // checkValues
</script>

10. And that's all

Start the Web Form and see how it works.

OpenAjax Call-to-Action to Ajax Developers for Browser Wishlist

2008-04-02T22:11:00.001+02:00

The OpenAjax Alliance is developing an Ajax industry wishlist for future browsers, using a dedicated wiki for this initiative (http://www.openajax.org/runtime/wiki). The main purpose of the initiative is to inform the browser vendors about what future features are most important to the Ajax community and why. So far, the alliance has interviewed roughly a dozen industry leaders, including representatives from the ASP.NET AJAX, Dojo, Ext JS, Douglas Crockford of JSON fame, jQuery, Spry, and XAP, and recently held a townhall discussion on the feature request list among its members. The members have concluded that the wishlist (~25 items) is ready for public comments.

The alliance is now issuing a call-to-action to Ajax developers to participate in this initiative, which is open to both OpenAjax Alliance members and to non-members. The alliance especially would like participation from Ajax toolkit developers and leading web developers with expertise in using open browser technologies to achieve rich user experiences. To join the effort, create a wiki login for yourself by following the instructions on the wiki home page (http://www.openajax.org/runtime/wiki). After you have a login, you can then add new feature requests or comment on existing feature requests as you see fit. The initiative operates on an honor-system basis.

The moderators have attempted to make it possible that the community can add comments and vote on particular feature requests without large time commitments. For example, it is possible to simply vote for your favorite feature requests by adding a single row to a wiki table. The alliance’s wiki uses the same markup language as wikipedia.

Here is the timeline:

April - Phase I review, where participants not only add comments, but also are asked to identify their Top 5 features (i.e., those features that are most critical for inclusion in next-generation browsers).
May - The moderators reorganize and possibly trim away feature requests for which little interest was shown.
June - Phase II review, where participants will be asked to provide importance ratings for each of the feature requests on a scale of 0.0 to 5.0.
July - The moderators will produce a summary report and notify the major browser vendors about the results.

The process is completely open and Wiki-based, so feel free to contribute^.

Data bound fields for Ajax forms

2008-01-26T20:57:00.001+01:00

An overview of the Ajax forms implementation of the AjaxEngine framework has already been published some days ago at http://ajaxaspects.blogspot.com/2007/12/using-openajax-events-for-building-data.html.

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:

element.eventname

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.

element.datatype

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.

element.setData(newValue)

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.

element.getData()

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.

element.setDatatype(newType)

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

http://www.mathertel.de/AJAXEngine/documentation/ViewDoc.aspx?file=~/controls/DataOutput.js

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

http://www.mathertel.de/AJAXEngine/documentation/ViewDoc.aspx?file=~/controls/DataInput.js

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

http://www.mathertel.de/AJAXEngine/S04_VisualEffects/FadeDemo.aspx.

The reference documentation can be found at

http://www.mathertel.de/AJAXEngine/documentation/ViewDoc.aspx?file=~/controls/DataFade.js

Building menus with OpenAjax events

2008-01-06T22:18:00.001+01:00

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).

HTML

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" /> 
</div>

CSS

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.

eventname

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.

eventnamespace

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"> 
  ...
</ve:MenuBar>

The implementation in JavaScript is available here:

http://www.mathertel.de/AjaxEngine/documentation/ViewDoc.aspx?file=~/controls/menubar.js

A sample page that uses this control is available here:

http://www.mathertel.de/AjaxEngine/S04_VisualEffects/InlineEditDemo.aspx

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

More OpenAjax compatible components

2008-01-02T19:26:00.001+01:00

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.

eventnamespace

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

The default namespace is set to "jcl".

eventname

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.

path

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.

expire

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.

Samples

<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:

http://www.mathertel.de/AJAXEngine/documentation/ViewDoc.aspx?file=~/controls/persistcookie.js

Useful OpenAjax Event Logger

2007-12-27T14:59:00.001+01:00

While working on further adopting the OpenAjax event mechanism I wrote this small JavaScript include file that helps inspecting the current OpenAjax events.

It is implemented by using a single JavaScript include file that can be found at http://www.mathertel.de/AjaxEngine/controls/OpenAjaxEventLog.js (view source).

It is easy to include this file into ANY web page by using a small JavaScript link (a.k.a. bookmarklet) that you can type into the address bar or save as a link in your favorites:

Create any Link in your favorites, or the link bar and name it for example like this:

Here is the url that you can paste into the url field in the property dialog of the link.

javascript:void(document.body.appendChild(document.createElement('script')).src='http://www.mathertel.de/AjaxEngine/controls/OpenAjaxEventLog.js')

There will be one dialog that warns you about the fact that the url is using JavaScript (an unregistered program - what means that ?) and that this may be unwanted. But in this case it is what we need.

You can open any of the sample pages from the http://www.openajax.org/member/wiki/InteropFest_1.0 and try it.

If you click on the link you just created a extra area will be appended at the bottom of the page and all OpenAjax events will be shown in there.

If you like to know more about bookmarklets you can google this term and you will find a lot more tricks.

My favorite is:

javascript:'<xmp>'+document.documentElement.outerHTML+'</xmp>'

Passing values around with OpenAjax events

2007-12-19T21:04:00.001+01:00

When publishing and receiving OpenAjax events there is the built-in mechanism of passing a payload a.k.a publisherData around together with the event. When implementing applications based on OpenAjax events there are some more things you should care about when using the publisherData feature. In the specifications you can also find some guidelines.

1. Don’t change the publisherData when handling an event.

That’s already said in the specification. Another and not so explicit mentioned argument for not doing so is the fact that there may be multiple subscribers to the same event. Because the sequence of the elements that receive the event is not determined you do not know whether a control gets the original or the modified publisherData. Anyway these situations are hard to debug – another reason to avoid them.

2. Don’t use objects – use strings instead

Right now the OpenAjax hub implementation is client side only but you can expect that events can also be spread other windows on inner iframes. In both cases direct object references are a problem because they cannot pass completely. If you need more than simple values consider using a proprietary format like "29.0016;18.5337", a JSON or an XML string.

And don’t assume when passing a numeric value that the subscribers get them as a JavaScript Number object.

It seems that strings are fine. :-)

3. Don’t use language specific formats

Users like to enter values into fields by using their culture or national language specific notations. Most keyboards here in Germany have a comma in the numeric keypad and a many people would not agree in typing dots when filling out fields for example with prices.

If you pass a "1.777,88" around you must assume that all subscribers can understand this specific notation. You can’t assume that if you like to live in meshup scenarios where the connected components come from different world wide vendors or sites. You even can’t assume that when writing a web application for the German speaking market: the Swiss people like the format: "1'777.88".

A good idea is to pass the values as defined by JSON and make them directly useable by scripting.

4. Don’t pass date values

Passing date values is somewhat problematic because there is no JavaScript constant definition (a.k.a. JSON) for that datatype. :-(

I recommend using the XML notation that is based on ISO 8601 date and time formats: "2007-12-24T18:00:02", but I must admit that that's my personal preference based on the fact that I prefer XML and SOAP.

Using OpenAjax events for building data-centric and forms based AJAX applications

2007-12-12T21:39:00.001+01:00

Most of the business web applications on the Internet are HTML forms based applications where html elements are bound to data is the core functionality. I am talking about registration forms, dialogs and pages to display and modify records of a server side relational database system like in ERP or CRM systems.

Usually there is not a lot of drag & drop activity or popping visual effects here but the most active elements deal with data that comes from databases or other data sources. We need to display, edit and control records from a company's database and implement transactions on these entities.

Here is an approach to use the OpenAjax event mechanism to implement this kind of web applications. The beauty of it and the reason why I implemented this for the AjaxEngine open source project is that using events and namespaces is a far more open approach then the mechanism that I introduced some time ago and has a neat extensibility model.

Typical data-centric web pages

From a high level viewpoint onto pages that implement data-centric applications you see that the elements on the page can be categorized into the following cases:

Fields and other elements where values are shown and edited by the users (Input fields, checkboxes, ...)
Buttons that help editing these values (calendar popup, drop-down lists, ...)
Foreign key Lookup mechanisms (checking against a list of countries, ...)
Buttons that offer a way of navigation through huge data sources (|< first, next >>, ...)
Buttons that commit a current state to the backend system ([Update])
Buttons that trigger special transactions or back-end calculations

Forms in this kind of scenario are just a collection of html elements that together can be used to display or edit a single record of a given schema.

Where to use OpenAjax events

Events can help in these situations where a direct connection between components is not desired or otherwise problematic:

1. events on the field-level

On the field-level (inside the form) data is passed around when the value of a field or another data control is changed. This happens either by a user interaction with a field or another data control or as part of a situation on the record level for example when a new record is displayed.

If a field exists it can subscribe to the appropriate event and can display the value passed around. On the other side it can also publish a new event if the user changes the value.

It doesn’t matter if a real field is used or a slider, a calendar popup or a 3d spin control. Even multiple controls that subscribe to the same event can coexist side by side without knowing from each other.

Conclusion 1: Using OpenAjax events gives us the advantage of having a simple plugin mechanism that is extendable.

2. events from the menubar

Clicking a button already publishes the HTML built-in onclick event. However this event is only passed to those elements that are clicked directly or are part of the control hierarchy of the html object model. The menubar catches these events and transfers them into OpenAjax events that are passed to all elements that are interested because they have subscribed them. These events in contrary to the html DOM events are carrying a semantic by using the full eventname and eventually by carrying some data with them.

Conclusion 2: Using OpenAjax events can add semantic statements to events.

Conclusion 3: OpenAjax events are independent from the html DOM layout and therefore can help separating the UI model from the event model.

These 2 scenarios fit well into the OpenAjax event standard.

Antipatterns to OpenAjax events

1. events between tight coupled components

The datasource controller and the form element are 2 components that share some information flow. However every situation in this scenario is started by the datasource controller. The case where a user wants to “update” the datasource controller has to request the current form data from the form. Using is not practical because the form element that would receive the event will not be able to “attach” the current form data. A direct connection is more adequate approach by sharing a common interface like the 3 methods.

Conclusion 4: Using OpenAjax events to retrieve information is not a practical solution. Tight coupled components are still an option.

Note: Maybe some other control is interested in the fact that new data is available in the form which is done through a write() call. This can be the reason for publishing an event by the datasource controller that expresses that.

2. events between passed between client and server

The datasource controller also has to exchange data with the server. This is a direct end to end communication that happens every time a record is fetched from the server or a record should be updated. OpenAjax events can’t cross this boundary (yet) and again there is return data that is not available immediately when using asynchronous calls (I hope you do for reasons of robustness).

Conclusion 5: Remote Procedure Calls situations should be implemented by using a high level AJAX protocol.

Using attributes on controls to define the event names

One design convention that is used within the DataControls is that the eventnames that are used by controls can be split into 2 parts: the namespace and the local name.

The event “de.mathertel.datasource.search” that is used by the search button in the menubar has the namespace “de.mathertel.datasource” and the local name “search”. The eventname can be specified on the button itself ion 2 ways.

When the eventname attribute contains a dot character it is assumed that the value already contains a full qualified event name.
When the eventname attribute contains no dot character the parent elements are scanned for a “eventnamespace” attribute ant the effective event name is built by combining them.

Here is the sample of the html code:

<div id="datamenubar" class="VEMenuBar" eventnamespace="de.mathertel.datasource">

  <span hover="true" class="VEMenu" tabindex="1" eventname="search">Search</span>

...

</div>

This convention helps writing short html attributes and allows an easy changing of the namespace that is used for a collection of controls.

Currently the menubar control and the ajax form control both use this mechanism for building the full qualified even names from the eventname / eventnamespace attributes.

That’s the blue print of the current changes that took place in the AjaxEngine project. The even simplified the way Ajax Forms can be implemented and helps minimizing the code that we usually need to connect all the elements in a typical data-centric web application.

Have a look at the sample: http://www.mathertel.de/AJAXEngine/S06_AJAXForms/SimpleReader.aspx. If you scroll down the page you can also see a region with a protocol of the raised events.

AjaxEngine is now full based on the OpenAjax specification

2007-11-20T22:34:00.001+01:00

During the last weeks a lot of work was done to remove the old DataConnection implementations in the Ajax Engine open source project. Now it's done. You can find a first version of it in the repository on Sourceforge: http://sourceforge.net/svn/?group_id=200182

and the sample web site http://www.mathertel.de/AJAXEngine was also published with this version today.

The current version will be tagged 1.5.nnnn.beta1 and a donwloadable zip file will also be available soon.

The OpenAjax hub specifications seems to be almost finished so not much work will be left until a final full compatible version.

A alternative to JSON is available: web services

2007-11-09T20:20:00.001+01:00

The discussions about the security concerns of JSON coming up again. Are you looking for alternatives ?

I am not used to advertise for my web site but there is an alternative cross browser solution available since 2005. It's robust code and it's running inside many web applications on Java and ASP.NET.

standard web services on the server.
SOAP (XML) used on the network.
JavaScript proxies on the client to allow RPC style calling of the server.
AJAXEngine layer that solves the typical timing problems.
No eval() !!! - no evil from eval !!!

One approach for multiple platforms.

By using the standard protocol on the server side you don't need to incorporate any special new interfaces for you AJAX solutions and take the full advantage to the stable and secured server ports.

On the client all the coding is plain JavaScript. That's why the communication part of this project works on Java as well as on ASP.NET ad PHP should not be a problem too.

Have a look at http://www.mathertel.de/AjaxEngine/

It's Open Source using a BSD style license and available on http://sourceforge.net/projects/ajaxengine/

Calling web services with structured parameters from JavaScript

2007-10-13T14:37:00.001+02:00

In many situations it is better to use structured parameters when calling SOAP based web services then using a long list of simple parameters. The proxy layer of the AjaxEngine now also supports these parameters by converting JavaScript Objects to the XML notation used in the transferred SOAP message.

Parameters

Using methods with structured parameters using JavaScript Objects is directly supported, just pass them with the right properties.
Here is a partial sample for a web service definition in C#:

// Define a point in the 3D space. public class Point3D {
  public double x, y, z;
} // Point3D

[WebMethod(Description = "Calculate the distance of 2 points in the 3D space.")]
// Test function passing structured objects.
public double CalcDistance3D(Point3D p1, Point3D p2) {
  Point3D v = new Point3D();
  v.x = p2.x - p1.x;
  v.y = p2.y - p1.y;
  v.z = p2.z - p1.z;
  double dist = Math.Sqrt((v.x * v.x) + (v.y * v.y) + (v.z * v.z));
  return (dist);
} // CalcDistance3D

Calling this method from JavaScript by using the generated proxy method is easy by using JavaScript Objects:

var p1 = {x:3, y:2, z:-4};
var p2 = {x:1, y:1, z:1};
var dist = proxies._types.CalcDistance3D(p1, p2);

If you like to use XmlDocuments ???

Structured return values

Methods of web services may also return structured values. Here is a sample of a method for calculating a vector in the 3D space:

[WebMethod(Description = "Calculate the vector between 2 points in the 3D space.")]
// Test function returning a complex object.
public Point3D CalcVector3D(Point3D p1, Point3D p2) {
  Point3D v = new Point3D();
  v.x = p2.x - p1.x;
  v.y = p2.y - p1.y;
  v.z = p2.z - p1.z;
  return (v);
} // CalcVector3D

Structured values that are returned by methods are available as XmlDocuments when you call a method like this. If you prefer to have the value as an JavaScript Object there is a function available in the proxies namespace that you can use:

var p1 = {x:3, y:2, z:-4};
var p2 = {x:1, y:1, z:1};

var xmlVector = proxies._types.CalcVector3D(p1, p2);
var v = proxies.xml2json(xmlVector);
alert(v.x + "/" + v.y + "/" + v.z);

Limitations

Objects used as parameters cannot be too complex. JavaScript Objects that have native values
(not Arrays nor Objects) are supported.
The data must be available in the format that can be de-serialized on the server
so take care of decimal points and date values.

Up to now the only way to use complex parameters with SOAP methods
was to use a server side XmlDocument Object and to extract the given values by using the appropriate methods.

Download

This addition was done in the current version under development. Because ajax.js is almost independent from the other current changes you can download it to existing projects from the sourceforge repository at http://ajaxengine.svn.sourceforge.net/viewvc/ajaxengine/trunk/ajaxcore/ or from the website http://www.mathertel.de/AJAXEngine/ajaxcore/ajax.js.

The plan for Q3/2007

2007-09-03T21:04:00.001+02:00

I've got some mails that have asked about the future of the AjaxEngine framework and here are some statements on that topic:

I will support and extend the framework in the future so companies and other open source projects that reuse it will have the support I can give. Some of the current topics that I'll hope to finish this month are:

OpenAjax compatibility for all controls including a InterOp fest compatibility test case.
Extending the functionality and the documentation of the Ajax form and the data controls.
Writing some more input helpers.
Writing about all of it...

I will make a beta version then and have some weeks to get the new functionality stable before publishing a new version.

You can always see the current implementation state in the svn based OpenSource repository at Sourceforge: http://sourceforge.net/svn/?group_id=200182

as well as the demo site that will also be based on the current version under development.

If anyone wants to add some core directly to the project instead of sending me mails let me know.

Extending the OpenAjax hub

2007-08-14T00:00:00.001+02:00

Extending events over the network by using an OpenAjax hub compatible approach.

The current version of the OpenAjax hub implementation (Hub 1.0) is focusing on a client-side solution for integrating components into a web application. But it doesn't address any needs that might come with the scenarios where events have to cross the boundaries of the current client side window.

However the hub specification does not explicit exclude these scenarios and is extendible without changing the API itself by introducing a OpenAjax compatible extender component.

Another approach is currently discussed in the OpenAjax member wiki at http://www.openajax.org/member/wiki/OpenAjax_Hub_1.1_Roadmap that is designed by extending the API of the hub itself.

Building an OpenAjax hub extender

The idea behind building an extender is to capture the events in one window and pass it over to other windows.

When the windows exists in the same frameset and share a common top window the message just needs to cross the boundaries. If the window is on another computer the client has to capture the event, and pass it to a server where other clients can then attach and retrieve the events.

1. capturing events

For the local hub implementation the part of the hub extender that captures the local events is just another subscriber. It can register to any local events or can just listen to some of the events that come around. The attribute "capture" is used to specify what events are sent to the server by specifying a semicolon separated list of namespaces using the same syntax as the subscribe method.

The other attribute that we need is the name of the service where the events can be send to using the server site publish method.

// registering for the local event.
OpenAjax.hub.subscribe(this.capture, "_catchLocalEvents", this);

// this function is called whenever a local event was published
_catchLocalEvents: function(eventName, eventData) {
  if (! this._replay) {
    // it's a real local event so publish it.
    var a = [eventName, eventData];
    a.multi = true;
    this.lastLocalAction = eventName + ":" + eventData;
    ajax.Start(this.sendAction, a);
  } // if
}, // _catchLocalEvents

The _replay flag is taking care about the fact that the events that are coming from the server should not be repeated back to the server.

The sendAction is the description how the server should be called. The call should be started at once and multiple calls for publishing an event to the server can be queued. There is no return value in this case.

// The Ajax action to send an event to the server
sendAction: {
  delay:0,
  queueMultiple:true,
  prepare: function (a) { return(a); },
  call: "proxies.OpenAjaxChat.Publish",
  finish: null,
  onException: proxies.alertException
}, // sendAction

2. listening to events

Listening to events that come from the server is somewhat more complicated because the normal http interaction schema for web applications is client side initiated. The server just has no chance to send messages to "all" or "specific" clients but has to wait until a client asks for an update.

So the client loops by using another Ajax action that is specified with a small delay and calls the server to retrieve new events. The server will return all newer events that have been recorded since the last call of this client that is determined by using a marking counter that can be passed from the client.

// this function is called after retrieving all the events from the server.
_republish: function(events) {
  this._replay = true;
  var aList = events.split('\n');
  for (var n = 0; n < aList.length - 1; n++) {
    if (aList[n] != this.lastLocalAction) {
      var a = aList[n].split(':');
      OpenAjax.hub.publish(a[0], a[1]);
    }
  } // for
  this._replay = false;

  // remember the current marker
  this.marker = aList[aList.length-1];

  // start another pollAction
  ajax.Start(this.pollAction, this);
},

The action is calling the serer by passing the current marker of the client and the asynchronous result will be passed to the _republish method.

// The Ajax action that polls the events from the server
pollAction: {
  delay:200, // wait 200 msec before calling the server (just to be smart).
  prepare: function (obj) { return(obj.marker); },
  call: "proxies.OpenAjaxChat.PullEvents",
  finish: function (ret, obj) { obj._republish(ret); },
  onException: proxies.alertException
} // pollAction

The action and the _republish method will be called repetitive to poll the server.

One thing is left to do in the implementation of this action is the fact that local events already have been published on the client and should not be republished when the server returns them again. To stop publishing an event twice the hub extender records the last event that has been captured locally and sorts this event out.

The Server API

Calling the server for publishing and retrieving the latest events is implemented by using a real SOAP based webservice with the 2 methods Publish and PullEvents.

The communication layer is not as complex as the one defined with Bayeux from the Dojo Foundation but it helps in most scenarios. It is restricted in some way because complex objects cannot be used by the eventData.

The return value of pullevents method is complex object that contains an array of eventname and eventdata and the value of the current marker that is transported using a string too by using the following format:

[namespace.eventname:data\n]*
marker

A sample application

A small sample is showing how all together can be used. It is a kind of chat application where anyone can participate in the same conversation by just opening the url: http://www.mathertel.de/AjaxEngine/S06_AJAXForms/OpenAjaxChat.aspx

You can change your current alias in the configuration section of the page. The large textarea is used to display all the events as the arise and the small textfield beneath can be used by you to type some text. Feel free top open another window and see that your written text also appears on the other side and maybe you can see others typing too. (I suggest talking about animals).
The data itself is a combination of the user's name and the typed text.

The first component is the one that is used for entering a new message and it publishes the event de.mathertel.chatsample.message whenever a line is finished by using the return key. The implementation is quite simple:

<fieldset style="width: 424px"><legend>new message:</legend>
  <input id="newmessage" style="width: 390px;" />
</fieldset>

// the functionality of the new message field.
var newmessageBehavior = {
  onkeypress: function(evt) {
    evt = evt || window.event;
    // send the message when pressing <enter>
    if (evt.keyCode == 13) {
      OpenAjax.hub.publish("de.mathertel.chatsample.message", document.getElementById("username").value
        + " - " + this.value);
      this.value = "";
    }
  } // onkeypress
} // newmessageBehavior
OpenAjax.hub.registerLibrary("newmessageBehavior", "http://www.mathertel.de/OpenAjax/newmessageBehavior");
jcl.LoadBehaviour("newmessage", newmessageBehavior);

The next component implemented is the larger textarea where the all the events will be logged:

<fieldset style="width: 424px"><legend>Chat log:</legend>
  <textarea rows="10" cols="50" id="chatlog" disabled="disabled">
  <textarea />
</fieldset>


// the functionality of the chat log area.
var chatlogBehavior = {
  // registering for the event.
  init: function () {
    OpenAjax.hub.subscribe("de.mathertel.chatsample.**", "_log", this);
  }, // init

  // append another line to the log text and cut the first one if there are too many.
  _log: function(eventName, eventData) {
    var txt = this.value.split('\n');
    if (txt.length > 9)
      txt = txt.slice(-9);
    txt.push(eventData);
    this.value = txt.join('\n');  
  } // _log
} // chatlogBehavior
OpenAjax.hub.registerLibrary("chatlogBehavior", "http://www.mathertel.de/OpenAjax/chatlogBehavior");
jcl.LoadBehaviour("chatlog", chatlogBehavior);

Implementing these 2 components a "local" chat applications ready to run.

The third component is the hub extender that is invisible and is introduced above. The complete source code of the page can be seen here:

http://www.mathertel.de/AJAXEngine/ViewSrc.aspx?file=S06_AJAXForms/OpenAjaxChat.aspx

and you can see the sample live at:

http://www.mathertel.de/AJAXEngine/S06_AJAXForms/OpenAjaxChat.aspx

If you are interested in the web service implementation the source is available here:

http://www.mathertel.de/AJAXEngine/ViewSrc.aspx?file=S06_AJAXForms/OpenAjaxChat.asmx

Discussion

The sample above shows how easy it is to extend a hub into other browser windows by not extending the API but by adding a component that does the job.
The huge advantage with this approach is that the additional functionality is strictly separated from the core implementation is and encapsulated into it's own JavaScript file. Therefore it is an optional component and will be not part of the download if not needed in a specific application.

Using the OpenAjax hub

2007-08-05T23:13:00.001+02:00

What's the problem ?

On the client side it is a common scenario that multiple independent developed controls have to be linked together.

Let's think about a web application that consists of several pages that all should share some common functionality, let's say a button that pops up a calendar to pick up a date.
Its a good idea to separate this kind of functionality into a separate JavaScript include file and a web control or tag library to make it reusable.

Well it's not always the same implementation we need because sometimes the field, that holds the that is named "shipping day", "birthday", "reply until" or any other and sometime there is more than one field on the same page.
Coding the name of the field into the common files seems not to be a good idea.
And it can be worse if there is not only a calendar button and a single field that needs to be connected but there might be also other fields foe example showing the duration between the 2 dates or even some validation functionality. All these "components" need to be linked together.

How links components ?

Hard-coding the IDs of the html elements into the JavaScript code is a bad idea that you can see often in JavaScript . A better idea (for the first sight) is to use attributes on the html elements that contain the IDs of the other elements. For example you can add a "targetControlID" to the calendar popUp and set it to the id of the field.
Sounds good, but it's still limited to be used for the scenario where more than one component needs to be attached to another.

Another idea is to link these components together by using a global available eventing mechanism where it is possible to publish events with values and to register for events on the other side.

Firing events means that one component that has detected a new situation or data constellation can make this available to all other listening components but without knowing if there are any. This results in scripts that are really independent of each other and can be reused in other pages where other constellations are present. Every component that is part of a specific use case can plug itself into the scenario.

That's the idea of the OpenAjax hub specification.

Using the OpenAjax hub to loosely couple components

The 2 main methods the hub specification offers are publish and subscribe -- simple but powerful. (The third defined method is unsubscribe).
Publishing is just as easy than calling a method of another component and the result is that all components (if there are any) that are interested in the event will be called.
To separate different events from each other and to specify the meaning of an event, each event needs a unique identifier that is build by using a namespace and local name.

OpenAjax.hub.publish("de.mathertel.openajax.tasksample.startdate", "2007.08.05");
OpenAjax.hub.publish("de.mathertel.openajax.tasksample.enddate", "2007.08.12");

These samples will tell all subscribers that the values have been changed. The new values are sent together with the event notifications.

OpenAjax.hub.subscribe("de.mathertel.openajax.tasksample.*", "calc", document.getElementById("duration"));

Using the subscribe method this way will cause that the calc method of the duration field will be called each time a event of the namespace de.mathertel.openajax.tasksample is published.

This sample only shows some main aspects about the OpenAjax hub only. You can find the complete specification on the OpenAjax web site (see links below).

Implementing a sample page

To show how to work with the OpenAjax hub implementation a sample page with a hypothetic task definition is used. The only aspects we have a look at are the start and end dates of this task and some more components around.
To keep the sample as simple as possible only one date notation is allowed: "yyyy.mm.dd". Keep that in mind, if you play around with the sample.

First of course we need a OpenAjax hub implementation. You can get the one from the reference implementation (see links below) or use the smaller one that comes with the JavaScript Common behavior library of the AjaxEngine Open source project. This one is also used in the samples implementation you can try out at
http://www.mathertel.de/AJAXEngine/S06_AJAXForms/TaskSample1.aspx

Here is the include statement:

<script src="../controls/jcl.js" type="text/javascript"></script>

The sample also contains 2 fields (startdate and enddate).
Another readonly field (duration) is used to display the duration of the hypothetic task.
A third and invisible component is also included in the page and this component will take care of the fact that the start date cannot be in the past.

Implementing the input fields

The fields we use here are just regular input fields that are extended by some JavaScript:

var fieldBehavior = {
  // after loading the page the other components should know about the current value.
  afterinit: function () {
    OpenAjax.hub.publish("de.mathertel.openajax.tasksample." + this.id, this.value);
  }, // init 
 
  // when leaving the field the new, changed value must be published.
  onchange: function (evt) {
    OpenAjax.hub.publish("de.mathertel.openajax.tasksample." + this.id, this.value);
  }, // onchange
 
 
} // fieldBehavior
jcl.LoadBehaviour("startdate", fieldBehavior);
jcl.LoadBehaviour("enddate", fieldBehavior);

After the page and all components have been loaded the current value of each field is published around so all other components know about it. When the value is changed through editing the event is published again.
I hope it is understandable what how the script works.
The way the script is bound the the 2 fields is part of the JavaScript Behavior mechanism that is not part of the OpenAjax specification. You can find how it works in some older posts on this block.

Implementing the duration field

Again a regular input field is used to display the duration of the hypothetic task. The script for this field is a little bit different and also uses the OpenAjax hub mechanism.

var durationBehavior = {
  _startDate: null,
  _endDate: null,
    
  init: function() {
    OpenAjax.hub.subscribe("de.mathertel.openajax.tasksample.*", "calc", this);
  }, // init
    
  calc: function (propName, propData, regData) {
    if (propName == "de.mathertel.openajax.tasksample.startdate")
      this._startDate = propData;
    if (propName == "de.mathertel.openajax.tasksample.enddate")
      this._endDate = propData;

    if ((this._startDate != null) && (this._endDate != null)) {
      var da = this._startDate.split('.');
      var sd = new Date(da[0], da[1], da[2]);
      da = this._endDate.split('.');
      var ed = new Date(da[0], da[1], da[2]);
      this.value = (ed - sd) / (60*60*24*1000);
    }
  } // calc
} // durationBehavior
jcl.LoadBehaviour("duration", durationBehavior);

The init method subscribes to all events that are published in the namespace I use in this sample. In this case the specific name of an event must be analyzed within the subscription method and because of that is passed as a parameter too.

Implementing the validation

The validation code is just registering the for startdate event and is checking the date value. If it's not a date an alert box is shown - that's all.

// a validator function to the startdate
function validate(propName, propData, regData) {
  var da;
  if (propData != null) {
    da = propData.split('.');
    if (da.length != 3) {
      alert(propData + " is not a date value formatted yyyy.mm.dd");
    } else {
      var d = new Date(da[0], da[1], da[2]);
      if (d.valueOf() < (new Date()).valueOf())
        alert(propData + " is not a date in the past.");
    } // if
  } // if
}; // validate
OpenAjax.hub.subscribe("de.mathertel.openajax.tasksample.startdate", validate);

Extending the OpenAjax hub

As you've seen the mechanism of the OpenAjax hub is really powerful and helps connecting components on a page without hard-coding the ids into the JavaScript code.
But there are still some minor topics undone.

1. initial events

After loading the page every component might have to publish the initial value to all the other components to make them know about the value. This cannot be done in an onload script because then it will depend on the initialization order of the components what components will receive the event.

The current OpenAjax hub specifications seems to have the understanding that events are used after the page has been loaded. I think the mechanism is also good to be used in the phase of the page loading but there is no suitable specification for this right now. The init and afterinit methods in the JavaScript Behavior implementation can help on this.

2. saving latest values

When events are published a component that needs to know about the values of several other events and has to combine them always has to collect this information on its own as you can see in the implementation of the duration field.

I think that this is a common scenario and can be supported in a general way too.

3. nesting events

The third issue I see is that the code that is started by a published event should not start another event.
Think about the validation functionality above. If a start date in the past is detected it would be easy to publish the current date as a substitute. The problem then is that other components will get the event once with the older value and once with the newer value. The order of these events is not deterministic and it might occur that the older value will be published to a component after the newer value.

Links:

http://sourceforge.net/projects/ajaxengine
The open source AjaxEngine project, including a public subversion repository.

http://www.mathertel.de/AJAXEngine/

The AjaxEngine project live with samples and documentation.

http://www.mathertel.de/AJAXEngine/controls/jcl.js
The JavaScript Common behaviors library containing a second source OpenAjax implementation.

http://www.openajax.org
Here you can find all the white papers and the specifications.

http://sourceforge.net/projects/openajaxallianc
Here you can find the reference implementation of the hub.

Tree view Ajax control update

2007-07-26T23:04:00.001+02:00

The tree view control was introduced some time ago and some details of its implementation can be found at http://ajaxaspects.blogspot.com/2006/01/tree-view-ajax-control.html or in the book at http://www.mathertel.de/AJAXEngine/documentation/AJAXeBook.aspx.

Now there is an update available and also a step by step sample how to use this control inside your web application.

The sample page can be found at: http://www.mathertel.de/AJAXEngine/S03_AJAXControls/TreeView.aspx.

1. Building a web service

Using Ajax with a tree view control is based on the idea that the full data that builds a complete tree might have a size that cannot be downloaded to the browser in one time. The server therefore has to offer a method that enables downloading fragments of a hierarchic data structure exactly in that moment when the user opens a new sub tree.

The tree view Ajax control binds to a webservice with only one function GetSubNodes(string path) that has to be built for your specific solution. If you like you can also use a different name for the method.

The structure of the XML node that must be returned by this method looks like this:

<tree>
  <folder name="AK" title="Alaska">
  <file title="Aguila" name="ZIP85320" link="http://weather.aol.com/main.adp?location=USAZ0001"/>
  <file title="Ajo" name="ZIP85920" />
  <file name="Redmond" img="redfile" />
  <file name="Alpine" />
  <file name="Yuma" />
</tree>

The outer element must be a <tree> node that contains <folder> and <file> nodes.

As you can see the name attributes do have a special purpose in this structure because the values of these nodes together and separated by slashes will build a path to each available element for example "/AZ/Ash Fork".

When clicking onto folders and files this path will be used for loading a subtree or for the events that are published when a final <file> node is clicked.

The title attribute is optional. Its text will be displayed behind the icon. If it's not present the name will be used instead.

The link attribute can be used when a click on a final node should just open a regular hyperlink.

When there is no link present on a file node an OpenAjax event "de.mathertel.treeview.click" with the path of the node in the data is published. You can register to this event for catch all clicks if no navigation is required.

You can find a webservice implementation here and here.

Having built such a web service most of the work is done.

2. importing the webservice

The webservice must be made available on the page containing the Ajax tree view control by using a simple JavaScript include:

<script type="text/javascript"
   src="../ajaxcore/GetJavaScriptProxy.aspx?service=../S03_AJAXControls/TreeView.asmx"></script>

Now the webservice is available through the proxies.TreeView object and the GetSubNodes method can be called by using the generated proxies.TreeView.GetSubNodes() function.

3. embedding the Ajax tree view control

The control is implemented as a user control in the file ~/controls/TreeView.ascx. If you use Visual Studio 2005 you can drag this file onto a page and the control will be registered for this page or you can register the control by using a @Register tag at the beginning of the page:

<%@ Register Src="../controls/TreeView.ascx" TagName="TreeView" TagPrefix="ajax" %>

The other way to register a user control is putting an option into the web.config file. This is the better solution if you want to reuse the control on multiple pages and like to use the same prefix all over the web application.

<configuration>
  <system.web>
    <pages>
      <controls> 
<add src="~/controls/TreeView.ascx" tagName="TreeView" tagPrefix="ajax"/>

The control itself can be used now:

<ajax:TreeView ID="TreeView1" runat="server" 
  service="proxies.TreeView.GetSubNodes" title="Cities in the USA" />

You can see the complete source of the page by using this link: [view source of TreeView.aspx].

4. CSS and specific icons

Some tree view might not only use folders and files so there is a special feature for that too.

The CSS code that is used by the tree view control is shown here:

div.TreeView .du {height:18px;overflow:hidden;cursor:hand; 
  background-image:url(controls/images/dc.png);background-repeat:no-repeat}
div.TreeView .do {height:18px;overflow:hidden;cursor:hand;
  background-image:url(controls/images/do.png);background-repeat:no-repeat}
div.TreeView .dc {height:18px;overflow:hidden;cursor:hand;
  background-image:url(controls/images/dc.png);background-repeat:no-repeat}
div.TreeView .de {height:18px;overflow:hidden;
  background-image:url(controls/images/de.png);background-repeat:no-repeat}
div.TreeView .fl {height:18px;overflow:hidden;
  background-image:url(controls/images/file.png);background-repeat:no-repeat}
div.TreeView .ft {padding-left:40px}
div.TreeView .subframe {margin-left:18px;}

Using these short classnames for attaching the style results in small html code fragments and you can link to the right images just by modifying the style rules. I put this baseline definition into the main css include file of the web application.

By specifying the img attribute on a file node in the data that is returned from the server another classname can be included for the ft-class elements. To avoid individual image tags in the tree view this classname extension also is handled by using a style rule that you can add:

div.TreeView .fl.redfile {background-image:url(../controls/images/redfile.png)}

This definition can be found in the sample page itself but you can also put it into the mail css include file if you like. Search for Redmond(WA) to see it work.

5. handling the events

If you just like to show information in a tree fashion and like to use hyperlinks on the file nodes you don't need to have a look at the eventing system that is also built in.

When clicking a file node and if there is no hyperlink set then the tree view controls publishes an event that event handlers can catch. The eventing system that is used here is the OpenAjax compatible event hub. You can find the documentation about it on the http://www.OpenAjax.org site and the implementation is part of the ~/controls/jcl.js file that is included automatically.

To register for such an event you need a little bit of JavaScript code:

// a function that will catch the tree events by listening to de.mathertel.treeview.**.
function showTreeEvent(name, data) {
  alert("click on " + data);
} // showTreeEvent

OpenAjax.hub.subscribe("de.mathertel.treeview.**", showTreeEvent);

The OpenAjax.hub.subscribe is registering the showTreeEvent function and this function will be passed the name of the event and the path in the data payload.

About the updated features

New to the current implementation is the support for the link attribute in the <file> elements and the publishing of events when clicking final nodes.

If you want to see more features or want to have more supported scenarios then let me know by using the feature request function on http://sourceforge.net/projects/ajaxengine/.

AjaxEngine is now on sourceforge.net

2007-07-07T22:33:00.001+02:00

You can now find a repository with the current version of the AjaxEngine, including the samples on

sourceforge at http://sourceforge.net/projects/ajaxengine/.

There are some real great advantages by using a public community site:

discussions and bug tracking

I plan to use the bug tracking and forum tools and hope you'll find this helpful too.

repository

I was using subversion all over the last years on my local site so it was easy to switch to a public server.

You can now find the latest stable version (1.2) and the current work in progress also there:

tsvn:https://ajaxengine.svn.sourceforge.net/svnroot/ajaxengine

collaboration

Another big advantage of an open community platform is that it makes working together really easy.

New Developers for the project are welcome !

Of course the existing web site http://www.mathertel.de/AJAXEngine will remain active so you still can see all the samples live there.

The fade effect and the DataFade control

2007-06-29T22:58:00.001+02:00

Here is a nice visual effect for data fields:

When a page contains multiple values that might change from time to time it is a good idea to bring the users attention to the updated value. The DataFade implements this by changing the background color of a field and fading it from yellow to the original background color that defined by the regular style.

The fading effect takes about a second and this is enough time for a human reader to focus the new field and reading the new value. The effect even seems to work if there are more values that are changed at the same time and it seems that the eyes can remember for some short time what fields have changed.

Here is a simple implementation using a horizontal scrollbar and a simple field.

http://www.mathertel.de/AJAXEngine/S04_VisualEffects/FadeDemo.aspx

When the DataFade control is initialized the actual background color is detected and stored in the local orgcolor field.

If the DataFade control detects that the value has changed it sets the background color to yellow and by starting a timer the background color is changed by smoothly adopting the red, green and blue to the original color that was found when the control was initialized.

The DataFade control is implemented using a JavaScript Behavior so it can be used inside AjaxForms for displaying, but not entering values. This is because it is inheriting the DataOutput Behaviour it implements a setData(newValue) method that is detected by the ajaxForms implementation and is used for setting the new value.

Aspects of OpenAjax

2007-06-19T23:19:00.001+02:00

You know I like standards.

Even if it is some kind of more complex to implement a solution based on a standard than using a direct and efficient but proprietary way, there are benefits on the long way that I just don't want to miss: the ideas and thoughts of others materialized in APIs, specifications and best practices.

That's why I use the SOAP standard webservice protocol for my Ajax implementations.

OpenAjax

Now OpenAjax Alliance is another try of a group of about 75 companies and organizations to define standards in the Ajax hemisphere. There are a lot of ideas and some good ideas too in the current discussions. We all know that it is hard to define a standard specification that gets agreed by the majority of the members. And it can take a long time until a standard proposal is adopted.

Right now a version 1.0 of the specifications are on their way and they contain some good stuff that I like to bring into the Aspects of Ajax framework and support an probably upcoming standard this way.

http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification

Libraries and Namespaces

There is only one world we live in and there is only one global namespace in JavaScript. The problem is that multiple frameworks when used simultaneously in one page MUST use different global variable names, different namespaces when implementing XHTML and different prefixes and aliases for the namespaces. Especially the global names might cause a lot of problems.

Did you try to use 2 libraries that both register the $() function but implement it differently?

The OpenAjax registerLibrary and unregisterLibrary methods that can be used to help mastering this problem space.

The ajax, the proxies and the jcl prefix will be used by the Aspects of Ajax framework because these are the names of the global variables I use (beside minor important stuff). I hope and pray that nobody else will use this prefix in any other AJAX framework. (I am the first - I won! :-)

No, and seriously: I don't like the global ajax variable being registered by any framework and right now I am not happy about this early (2005) decision any more.

The namespace used by the Aspects of Ajax frameworks will be de.mathertel because http://www.mathertel.de/AJAXEngine/ is the URL where the documentation and the samples can be found on the web.

... but maybe it's time to register a product name related web address :-)

When implementing a standalone AJAX framework you do not have to care about these problems. Being compatible (and friendly to other frameworks) can open a wide space in combining functionality from different sources.

Events - inter controls connections

Connecting multiple controls on a page by using JavaScript can be a nightmare because many little scripts will have to know about the existing other elements on the page. If you want to reuse generalized controls this situation becomes worse and if you like to reuse components of different manufacturers ...

So it's a good thing to define a common functionality that does the job and that controls can use to talk to each other using the well known subscribe and publish pattern and the idea of events.

The Aspects of Ajax framework has a small implementation since almost 2 years (see http://ajaxaspects.blogspot.com/2005/09/connecting-controls.html) called "page properties" or data connections that also allows this kind of connectivity through the DataConnections object but compared with the event system of the OpenAjax hub specification there are some pros and cons.

The OpenAjax hub has defined an idea of namespaces and namespace notation like the namespace ideas known from .NET, Java and other environments. Events that are published are prefixed by a namespace so different providers of the same event name can be distinguished. The page properties of the Aspects of Ajax framework only had one global namespace (the page).
Using the OpenAjax hub specifications it is possible to subscribe to specific events by specifying the long name of the event and by using a wildcards for registering to multiple events. In the Aspects of Ajax framework it was possible to subscribe to all events.
The Aspects of Ajax framework has a mechanism that allows to poll for a current value of a prior published property change / event. The OpenAjax hub has no such methods defined but it is easy to implement an invisible control that logs all changes and offers some methods for getting the latest values.
The Aspects of Ajax framework has some specific controls that helped while developing. One of them is a log of all events and the new values. Beside the changed implementation they also have a new parameter to specify what specific namespace they should watch.

Overall the OpenAjax implementation has some big advantages over the older DataConnections and the additional functionality can be added.

Implementation

The OpenAjax Alliance provides a reference implementation is available in an early version and other implementations of the specification are welcome. After reading the available specs and noticing that it is "just" better then my prior codings I decided to implement the specific details on my own and make them available in a standalone JavaScript file. Some requirements are implemented different than in the reference implementation and maybe you find the time to have a look at the difference if you like.

The size of the implementation

As of this writing the (unfinished) reference implementation is about 2801 bytes. The (current) implementation available on my side at http://www.mathertel.de/OpenAjax is about 1300 bytes. Maybe my implementation is a little bit slower because I rely on regular expressions but I have not done any detailed measures yet. Both sizes are calculated by comparing a shrinked version using the tool from the dojo framework that is available online at http://alex.dojotoolkit.org/shrinksafe/. This is because I don't want to compare the comment lines or different programming styles.

The same implementation is also embedded into the jcl.js implementation that also implements the JavaScript Behavior mechanism.

Future planning

I will have a look for the specification of the OpenAjax Alliance hub and I will post a compatible version. It is just good to have a second source.

The Aspects of Ajax framework. including the SOAP client for web services in JavaScript will register itself and will use the hub implementation as a substitution of the older DataConnections implementation that will be removed completely.

A simple page for displaying a record

2007-06-17T21:43:00.001+02:00

Building a page with a form to display and change a record is a common scenario and it should be easy to implement. Some of the basic ideas where already published last week and here is a concrete implementation. The page that can be found at http://www.mathertel.de/AJAXEngine/S06_AJAXForms/SimpleReader.aspx is built by a combination of the 3 components:

The Form contains DataInput fields and other Data Contol elements that are used to display the values.
The Menubar is used to offer the typical buttons for searching and navigating through the dataset.
The DataSource control controls the binding between these controls and the server side web methods.

The Form element

Many web applications need to display and modify relational data by using a form and a offering a single record at each time. The form itself contains input fields to display the columns of the record and other html elements like labels or other static text around them.

All these elements together are held together by using a html container element that is called the form element. Because we handle all data mechanisms by using AJAX functionality we do not need a real <form> element but use a <div> element instead.

The functionality that is attached to the form (the <div> element) of the page handles getting and setting values by respecting the correct formats for several datatypes and converting them to regular xml data formats.

The great benefit from this approach is, that the server has to support only the standard xml format for the known datatypes and not any country or language specific formats. More on that in another post.

The functionality of the form element is implemented by using the DataForm JavaScript Behavior that is built reusing the functionality that was built in the early days in ajaxForms.js. By using a behavior the code was simplified and reduced.

The Menubar element

This element contains the typical buttons that enable the navigation through a set of records.

These buttons and icons will trigger the corresponding methods of the datasource control by publishing events.

The DataSource control

This element is not visible to the end user and is containing the main functionality to transfer the data from the server to the form element. It also contains a client side cursor model that help keeping state information away from the server.

The following commands are available:

clear: This command will just clear all the values inside the form.

search: A call to the server is started to retrieve the keys of the found records. The current values of the form before the search is started are used as a template so you can easily find a specific record or a set of records. The retrieved keys are used to form the cursor.

first: The first record in the cursor is retrieved from the server and is displayed inside the form.

next: The next record in the cursor is retrieved from the server and is displayed inside the form.

previous: The previous record in the cursor is retrieved from the server and is displayed inside the form.

last: The last record in the cursor is retrieved from the server and is displayed inside the form.

(future extensions: add, update, delete, ...)

The DataSource element also publishes an event when the data of the form was changed to inform other elements on the page that a new situation is existing.

Searching and the AJAX calls in the background

The "search" button in the menubar must be used first to build the dataset. This is done on the server by searching for all the records that match the criteria given by the current values in the form fields. This is done by using the SearchAction that is passed to the AJAXEngine to call the search method of the webservice. This method is returning a list of unique keys, each one representing a record.

Here is a sample how to search:

You can write "UK" into the country field and press "search" to search all records that have "UK" in the country colum. The database provider also offers the possibility to search using wildcards. If you enter "U%" into the country field you will find all the records with a country starting with "U".

After finding some data the dataset control automatically will fetch the first found record and will display in in the given form fields. This is done by using the DisplayAction that is passed to the AJAXEngine to call the fetch method of the webservice and passing the retrieved record data to the form.

Using the arrow buttons you can step through the dataset. The clear button will clear the form without freeing the dataset but by loosing the current cursor position.

Events between the controls

Connecting elements on the page might be done by using scripts in one element that direct address the other element or by using events.

Events like onclick and onload are already well known in the web development but they are limited to those events that are built into the DOM (Document Object Model). It is not possible to reuse this mechanism for other, self-built events and another mechanism is needed for tasks like this.

The OpenAjax Alliance is targeting this problem with the hub implementation that is still under development for version 1.0.

Inside jcl.js (view source) you can now find a (almost) compatible version of the OpenAjax specification that has only about 1300 bytes of real code. When the specification is finished I will release a compatible version and will follow the idea of a common functionality and compatibility of the Ajax frameworks. More on that in another post...

Building data-centric and forms based AJAX applications

2007-06-11T19:39:00.001+02:00

Most of the business web applications on the Internet are HTML forms based applications where data, bound to html elements, is the core functionality. I am talking about registration forms, dialogs and pages to display and modify records of a server side relational database system, ERP or CRM systems. There are not a lot of drag & drop elements or popping visual effects here but most active elements deal with data that comes from databases or other data sources.

Many developers do not build E-Mail applications, portal frameworks, maps or mashups but we need to display, edit and control records from a company's database and implement transactions on these entities.

This part of the framework and the upcoming posts are about the aspects and coding the client side of this kind of web applications and here is my blueprint of the ongoing work that will extend and consolidate the framework in this direction.

The server side is kept minimal for now and you can adopt any data binding layer on the server you like as long as you implement the small ITableDataService interface on the web service that handles the AJAX calls.

Inside the archive file Ajax_new.zip download you can follow the development of this part of the framework in the S06_AJAXForms folder.

Typical data-centric web pages

From a high level viewpoint onto pages that implement data-centric applications you see that the elements on the page can be categorized into the following cases:

Fields and other elements where values are shown and edited by the users (Input fields, checkboxes, ...)
Buttons that help editing these values (calendar popup, drop-down lists, ...)
Foreign key Lookup mechanisms [check against a list of countries]
Buttons that offer a way of navigation through huge data sources (|< first, next >>, ...)
Buttons that commit a current state to the backend system ([Update])
Buttons that trigger special transactions or back-end calculations
Tables that display mass data by paging or scrolling
Tree Views that display hierarchical (mass-) data

Some of these features where already shown here on the blog but it's time to rearrange these features a little bit and make them working together. Here are some aspects about the major features.

Forms and binding data

A core functionality of this kind of business application is a data binding functionality that connects elements of the form to the corresponding data source. Because we want to keep the page loaded while navigating through many records coming from the server we need a client-side mechanism for moving data into html elements and back. The core of this mechanism was introduced in an early post using the ajaxForms.js include file. This mechanism will be extended and tuned a little bit.

Supporting national language specific notations

Of course we need some functionality to convert non-text datatypes to a string representation that can be read by the user and this frameworks goes further by converting values to human readable strings with the typical national language specific notations in decimal numbers and date values.

Because this is done on the client we need no conversion on the server and therefor have a server that must not care about the specific formats out there in the world. Supporting these notations is done by using a plugable mechanism that delivers the right conversion routines to the client based on the language settings of the browser.

Input Helpers

These elements are bound to a standard input field. They are built to help entering some specific datatypes by offering an alternative input method . This might be small dialogs like a calendar popup, drop-down buttons that open a list of possible values or sliders that can be used to adjust a value.

Some of these controls do already exist in the controls collection of this framework but again they have to be adjusted and extended a little bit.

Navigating through table data

In many cases the data comes from a data source on the server that stores many records in a table format. On the client we will need some elements that help us navigating through this kind of data. The most common used user interface elements are buttons that allow positioning to the first, previous, next and last record and support searching and modifying the current record.

By implementing a webservice on the server that implements a common interface and a set of controls on the client that use this webservice there will a set of basic functionality available without the need for scripting on the client.

Tree Data

A data bound tree sample has already been published at http://www.mathertel.de/AJAXEngine/S03_AJAXControls/TreeView.aspx

but we will see how to integrate it into the scenario by reusing the same web service interface for the Ajax call.

Common data interface on the server

Serving data from the server and some more functions is provided to the client by using several methods of a webservice. This webservice has to support several simple methods that will bring the databinding to the client through ajax calls. To support an easy development of these web services the ITableDataService interface is defined with the minimal set of methods.

AJAX Controls for AJAX forms

AJAX Form Controls are very similar to the PropXXX controls I had introduced some time ago. AJAX Form Controls are made to bind data from an external data provider and from web services using elements on a html page. The AJAX Form Controls are AJAX Controls that implement the Data Interface functions.

(The PropXXX Controls are using primarily the Page Properties storage mechanism and are used to control the state of the view of the page. This is typically something different than the data, but we will see some changes in this scenario too in some time to make it OpenAJAX compatible).

Technorati tags: AJAX, Forms, Controls, JavaScript

A simple menubar

2007-06-03T23:07:00.001+02:00

By using the hover effect it is possible to realize a simple menubar that will be used by an upcoming control that allows rich text editing. Here I focus on the implementation of the menubar that is implemented as a separate control and can also be used with small changes for other purposes.

Building the html code for the menubar

The html code for building a menubar is implemented by using an outer <div> element with a classname "VEMenuBar". This element is used as the wrapper for all parts of the menubar and is displayed in the background.

The inner elements and menu items can be implemented using <img> images or <span> elements with text content.

The third type of an inner element is a vertical line or separator that can be used to group elements.

Here is a small sample:

<div class="VEMenuBar">
  <span class="VEMenu" tabindex="1" onclick="datasource.search();">Search</span>
  <img class="VEMenuSeparator" alt="" src="../controls/images/white.gif" />
  <img class="VEMenu" alt="show first record" tabindex="1" src="../controls/images/first.gif" /> 
</div>

The hover effect

When positioning the mouse over any enabled item of the menubar the individual item for starting a specific command is highlighted. For implementing this effect the already known hover behavior is reused. All that we need to implement it is to include the hover.js include file in the head of the page and setting the hover attribute on every element.

<script type="text/javascript" src="../controls/Hover.js"></script>

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 of the outer element an sets the hover attribute to true for those elements that have a classname "VEMenu". This allows to enable 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. 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.

The HTML elements that build the menubar

First of all the outermost element of the menubar that will get attached the behavior is a div element with a classname "VEMenuBar". This element is used as the wrapper for all parts of the menubar and is displayed in the background.

The icons or other images are placed in the menu by using <img> elements as children inside the VEMenuBar element

and will have a classname "VEMenu". They will automatically get an attribute hover="true" to enable the hover effect.

CSS definitions

Some classnames need to be defined:

.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;}

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

This rule is used for the state of a 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 a 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 1 px 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.

Attaching functionality

The MenubarBehavior implementation has no special implementation for the onclick event on VEMenu items. The functionality of the menubar item should attached by using the onclick events directly.

You can find the state of the current implementation here:

http://www.mathertel.de/AJAXEngine/S04_VisualEffects/InlineEditDemo.aspx

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

Download the current version under development

I've added another downloadable archive file to the site : Ajax_new.zip.

This Zip-File contains the current version of the ASP.NET 2.0 web project that builds this side.
The complete AJAX Engine and all samples and also unfinished samples and componente are included.
Use this download If you want to experiment with the Engine or if you want to have a look for the newest additions and features.

Using webservice calls with multiple parameters

2007-05-21T21:19:00.001+02:00

The restriction that the AJAXEngine supported only methods with one parameter had been a topic to some postings in the blog and also to some good comments with good solutions.

Because the problem was only restricted by the AJAX Engine itself and not by the underlying JavaScript proxy layer I looked for a small and neat solution and finally found that the often overlooked Javascript method apply

helps here.

The implemented way of passing more than one parameter is (like suggested) to use an Array as a return value of the prepare function. Because arrays are also supported as a parameter to the called method itself a extra hint is used to distinguish these 2 scenarios.

Here is how to implement the prepare method for this case:

prepare: function (ds) { 
  var p = new Array();
  p[0] = ajaxForms.getData(ds.form);
  p[1] = "name";
  p.multi = true; // the hint for the ajax Engine
  return(p);
},

The changes in the AJAX Engine layer is only a condition check and a call using the apply method:

// start the call
ca.call.func = ajax.Finish;
ca.call.onException = ajax.Exception;
if ((data.constructor == Array) && (data.multi != null)) // 19.05.2007
  ca.call.apply(ca, data);
else
  ca.call(data);

If you want to use this feature, you can download the ajax.js file directly. A complete version will be available some day soon including new samples and features.

Accordion menu

2007-05-14T21:59:00.001+02:00

I added another visual effect for HTML that is called an accordion menu by using a JavaScript Behavior.

An accordion menu is a collection of multiple, stacked panels.

Only one of them is visible and another can be opened by clicking the header of a closed one using a smooth transition of the heights of the content area of the panels.

Have a look at: http://www.mathertel.de/AJAXEngine/S04_VisualEffects/AccordionDemo.aspx

A new version of the book "Aspects of AJAX" is online

2007-05-02T21:35:00.001+02:00

Beside writing some more pages it also contains some corrections and the new posts on this blog where added also.

You can get it for free from http://www.mathertel.de/Ajax/AJAXeBook.aspx..

Using Inheritance in JavaScript Behaviors

2007-04-05T21:25:00.001+02:00

While working on some samples using (different) menubar, I found it helpful to inherit a JavaScript Behavior from a more general JavaScript Behavior. This would give me the chance to implement the common general Javascript methods only once and leave specific functionality in the derived Behavior.

Here is the sample:

// this is a basic behavior definition for menubars
var MenubarBehavior = {
  init: function () {
    // activate the hover effect on all menu items
    var allitems = this.getElementsByTagName("*");
    for (var o in allitems)
      if (allitems[o].className == "VEMenu") {
        allitems[o].hover = true;
      }
  },
 
  onkeypress: function(evt) {
    evt = evt || window.event;
    var kc = String.fromCharCode(evt.keyCode);
    if ((this._attachedBehaviour.onclick != null)
      && (evt != null) && ((kc == " ") || (kc == "\r"))) {
      this._attachedBehaviour.onclick.call(this, evt);
    } // if
  } // onkeypressed
} // MenubarBehavior

This is a basic implemenation that enables the hover effect for all VEMenu items found inside the menubar and to simulate a click event if the spacebar or return key is used while the focus is on a menuitem.

// this is a basic behavior definition for menubars
var EditMenubarBehavior = {
  inheritFrom: MenubarBehavior,
 
  init: function() {
    MenubarBehavior.init.call(this);
  },
 
  onclick: function(evt) {
    evt = evt || window.event;
    var src = evt.srcElement;
    var cmd = src.name;
    if (cmd != null) {
      cmd = cmd.split(';');
      HtmlEditBehaviour.Command(cmd[0], cmd[1]);
    }
  } // onclick
} // EditMenubarBehavior

This is the implementation of the derived Behavior definition.

If you ask why I do not use the JavaScript inheritance mechanism, then you have a good question - i tried.

Using the new operator and the prototype mechanism does not work here because we attach methods to HTML elements and some other problems came up too.

The article of Nicholas C. Zakas at: http://www.sitepoint.com/article/javascript-objects also describes the topic.

You can find the state of the current implementation here:

http://www.mathertel.de/AJAXEngine/S04_VisualEffects/InlineEditDemo.aspx

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

The only code I had to add to the LoadBehaviour method (that does something very similar to the extends method of Zakas) are these 3 lines of code to recursively bind the Behaviors starting with the base class.

if (behaviour.inheritFrom != null) {
  this.LoadBehaviour(obj, behaviour.inheritFrom);
  this.List.pop();
}

See controls/jcl.js (view source)

(I'll publish a new version of the framework as a zip here file when this sample is finished).

JavaScript Behavior Tutorial

2007-02-24T23:22:00.001+01:00

The complete Tutorial is now online.

If you worry about too much JavaScript fragments in too many places you need a concept of reusing client side functionality on a component level.

This is a step by step instruction for building a new client side component by using the JavaScript behavior mechanism. It is first implemented without using any server side help by only implementing JavaScript in a plain html file. Later it is evolved into an ASP.NET user control.

See how to implement JavaScript behaviors from the scratch.

http://www.mathertel.de/AJAXEngine/S05_JSB/default.aspx

New release of the framework and samples

The zip files with the complete framework and samples have also been updated today:

Ajax.zip (1.367 kByte) This Zip-File contains the ASP.NET 2.0 web project that builds this side. The complete AJAX Engine and all samples are included. Use this project when you want to start building your AJAX web application.

AJAXEngine.zip (159 kByte) This Zip-File contains the core files of the AJAX engine and the AJAX controls. You can use this if you want to update your project with the updated core files.

Building JavaScript Behaviors - 3

2007-01-18T20:38:00.000+01:00

Methods for event handling

The methods that are used to handle events from the mouse, keyboard or system are identified by their name prefix "on". When the behavior is bound to the HTML element these methods are not just copied over from the JavaScript behavior declaration to the html element but are wrapped by a special function that looks like

function() {
  return method.apply(htmlElement, arguments);
}

This wrapper is generated automatically for all on__ methods to ensure that the JavaScript "this" pointer is pointing to the htmlElement the method belongs to. This really simplifies writing event code.

Simple Events

The first sample already used an event (onclick) and registered a method to calculate a new random number for the dice.

// classical event handler implementation
onclick: function(evt) {
  evt = evt  window.event;
  var src = evt.srcElement;

  src.rolling = 50;
  src.count = 0;
  src.rollNext();
}

Because the this pointer is adjusted to the htmlElement we can use it instead of finding the right element through the event property srcElement:

// simpler event handler implementation
onclick: function(evt) {
  this.rolling = 50;
  this.count = 0;
  this.rollNext();
}

Global Events

Sometimes it is not possible to implement an event code by using this simple on__ naming scheme because the event that the behavior needs is not thrown to the htmlElement of the behavior.

If you are interested in global events you need to attach a method by using the AttachEvent method that is available through the jcl object. Don't use the on___ naming scheme for this method:

jcl.AttachEvent(document, "onmousedown", this._onmousemove);

If you are not interested in these events all the time the handler can be detached by calling:

jcl.DetachEvent(document, "onmousemove", this._onmousemove);

Mouse Events

Mouse events are a little bit special when implementing a drag&drop scenario. The onmousedown will always be raised on the element that will be dragged around but the other 2 events mousemove (while dragging) and onmouseup (when dragging ends and the drop occours) may be raised on any other elent on the page or even on the document object itself. Because the event "bubbles up" we can get all the events by attaichg these 2 methods to the document object.

The sample at VBoxDemo.aspx is using the VBox.js behavior that allows changing the width of the vertical separation by dragging the line between the left and right content.

You can download the updated files from http://www.mathertel.de/Downloads/Start_JSBTutorial.aspx.

del.icio.us tags: JavaScript, behaviour, usercontrols

Building JavaScript Behaviors - 2

2007-01-08T17:06:00.000+01:00

The sample from the last post about building JavaScript Behaviors is not very realistic, because it is not configurable and missing parameters.

Properties, Attributes and Parameters

The way parameters are passed to the behavior implementation is some kind of tricky:

you write down a parameter into the *.aspx source file.
when the page is called from the server the parameter is passed to the server side control.
the parameter is then written out into the response (html) stream and send to the client.
when the behavior is attached to the html element it is made available to javascript.
the behavior implementation is using the parameter by using this.parameter.

There are some traps and tricks on the way.

Take care of uppercase characters in the parameter name. Parameters with uppercase characters work fine on the server but using them on the client breaks the xhtml format spec. You can use lowercase parameters on the server and the client and you don't get confused when writing code for the server platform and the client platform the same time.

If you want to make a parameter available to the server control you have to add a public property or a public field to the class.

Using public fields is working fine but Visual Studio will not help with intellisense then so I prefer using a encapsulated private field using a public property:

private string _datatype = String.Empty;

public string datatype {
  get { return _datatype; }
  set { _datatype = value; }
} // datatype

public string working_but_no_intellisense = String.Empty;

Passing null through a parameter just doesn't work because you cannot specify an attribute for a xml or html tag with a null value. I am using empty strings instead.

If no attribute value is specified in the source code you need to define a default value. The easiest is to assign the default value to the private server field declaration and always render the attribute into the response stream.

The firefox browser makes a big difference between attributes of a html element and a property of an object so when attaching a behavior to a html element all the attributes are copied into object properties.

Don't use any reserved words you know from C#, VB.NET, JAVA, JavaScript, HTML or the DOM specification as a name and don't start a name with "on" because this naming convention is used for identifying event handlers.

1. Adding a parameter to the dice sample server control

The sample up to now is only showing random numbers from 1 to 6. A new parameter named "maxnumber" should make it possible to get random numbers between 1 and any positive number greater than 2.:

private int _maxnumber = 6;

public int maxnumber {
  get { return _maxnumber; }
  set { _maxnumber = value; }
} // maxnumber

This parameter is not needed on the server side and we just pass it to the client through a html attribute:

<div id="<%=this.ClientID %>" class="Wuerfel" maxnumber="<%=this.maxnumber %>"
  unselectable="on">click</div>

You can find this implementation in wuerfel2.ascx.

2. Adding a parameter to the behavior

On the client side we need to declare tha parameter as well. The given assignment will always be overwritten be the attribute the server adds to the html element.

And then we must use.

// parameter to set the maximum number
maxnumber : 6,

// find a random number
var n = Math.floor(Math.random()*(this.maxnumber-1))+1;

You can find this implementation in wuerfel2.js.

3. Using the new feature

Now the new parameter can be used on any wuerfel2 tag:

<uc1:Wuerfel2 ID="Wuerfel2" maxnumber="42" runat="server" />

You can find it in Wuerfel_05.aspx.

You can download the updated files from http://www.mathertel.de/Downloads/Start_JSBTutorial.aspx.

del.icio.us tags: JavaScript, behaviour, usercontrols

AJAX Aspects is now available under the BSD license

2007-01-05T14:15:00.000+01:00

After some discussions and some reading I decided to change the license of my public software available from http://www.mathertel.de to a BSD style license. It's a better license for software projects then the previously used Creative Commons Attribution 2.0 Germany License.

The new license text is available at http://www.mathertel.de/License.aspx. The source code comments pointing to the license will be adjusted in the next days.

Building JavaScript Behaviors

2006-12-08T20:07:00.000+01:00

During the last months I got some good feedback from readers and friends that point me to some missing topics in my AJAX book. I will continue to publish new content here before bringing a new version of the book.

This is a step by step instruction for building a new ASP.NET Control with a rich client side functionality by using JavaScript and a Behavior mechanism.

The sample functionality I use to show this is a simple dice (German: Würfel). It's a sample that I also used in my session at the "AJAX in Action" Conference in Germany some weeks ago.

You can download all files from http://www.mathertel.de/Downloads/Start_JSBTutorial.aspx.

1. Coding it all in one place

The best place for writing a new control is inside a single HTML file that contains all the fragments that you will separate later into different locations:

a HTML object structure that will be used for rendering the new control. This should be a single outer element that may contain complex inner HTML elements. Give it a unique id that can be used to identify the first prototype.
a CSS section inside the <head> element that will hold all the style rules that we will later move out into the common css file. You can code all the css rules into the html elements first if you like. Later you should not include any CSS code inside the rendered html elements mo make some personalization and style adoption easier.
a <script type="text/javascript"> element that will contain the JavaScript behavior definition using a object notation in the JSON coding style and the statement for binding the JavaScript behavior object to the HTML element.
include the common behavior loading mechanism <script type="text/javascript" src="../controls/jcl.js"></script> in the <head> element.

The advantage of using this intermediate development state is that you can hit F5 in the browser and can be sure that all your code will reload as expected. You also will not have any timing problems that may happen when JavaScript or CSS files are cached locally. You need no server side functionality so a *.htm file is fine for now.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
  <title>Ein Wuerfel</title>
  <script type="text/javascript" src="jcl.js"></script>

  <style type="text/css">
    .Wuerfel {
      border: solid 2px green; width:40px; height:40px; overflow:hidden;
      cursor: pointer; background-color:#EEFFEE;
      font-size: 30px; padding:20px; text-align: center;
    }
  </style>

  <script type="text/javascript">
    var WuerfelBehaviour = {
      onclick: function(evt) {
        Wuerfel1.innerText = Math.floor(Math.random()*6)+1;
      }
    } // WuerfelBehaviour
  </script>
</head>

<body>
  <div id="Wuerfel1" class="Wuerfel" unselectable="on">click</div>
 
  <script defer="defer" type="text/javascript">
    jcl.LoadBehaviour("Wuerfel1", WuerfelBehaviour);
  </script>
</body>
</html>

The file wuerfel_01.htm contains an implementation in this state.

2. replacing all hard-coded references

If you want to make it possible to use the same control multiple times on the same page then you must avoid using hard coded ids or names. The only place where you should find the id of the outer HTML element is inside the first parameter of the jcl.LoadBehaviour function call.

All the other references should be replaced by using the "this" reference.

The other thing you should take care too are the parameters / attributes that you want to use together with the new control. You should define the as attributes in the outer HTML element and as properties of the JavaScript behavior definition. There should not be any constants inside the JSON object.

If everything is well done you can make a second copy of the outer HTML element with a new id and can bind the same behavior definition to it. Both elements should now work as expected independently. Check also if the parameters work as expected.

The file wuerfel_02.htm contains an implementation in this state.

3. separating the behavior code

The next step is to extract the core of the behavior into a new *.js file and reference this file by using a new <script type="text/javascript" src="wuerfel.js"></script> in the <head> element.

The advantage of a separate file for the behavior definition is that the implementation can be cached by the browser independently from the individual use and If the control is reused in different pages you can see dramatic performance improvements.

The file wuerfel_03.htm and wuerfel.js file contain an implementation in this state and wuerfel.js ??? has also got some more functionality.

4. separating the CSS style definitions

The style of the new control should not be coded inline into the html code but should be separated into some css statements. So I use a classname for the top element of the control by using the name of the behavior. If you have special inner elements they can be prefixed by the same name or you might use css selectors by specifying the outer and inner class names. Sample:

div.TreeView .do { ... }
div.TreeView .dc { ... }

Because the css statements are usually much smaller then the JavaScript code for a control I do not extract the css statements into separate files but include them all in a single css file for all the controls I've done. The *.css files are cached by the browser so loading them from the server doesn't occur too often.

5. converting to a ASP.NET User Control (*.ascx)

Now it's time to switch from a *.htm file to a *.aspx file because you will need some server side functionality now.

Rename the file and add a <%@ Page Language="C#" %> statement at the top of the page. In Visual Studio you will have to close the file and reopen it to get the full editor support for the right server side languages.

The html code and the javascript statement that binds the JavaScript Behavior of the new control is copied into the new User Control file wuerfel.ascx.

The id attribute that is rendered for the client should not be hardcoded to a static value. The UniqueID can be used and will produce the given id if one is specified in the *.aspx page.

<div id="<%=this.ClientID
    %>" class="Wuerfel" unselectable="on">click</div>
<script defer="defer" type="text/javascript">
  jcl.LoadBehaviour("<%=this.ClientID %>", WuerfelBehaviour);
</script>

Now it is easy to include the new control into the page by dragging the wuerfel.ascx file into a blank page while using the Design mode. The code will look like this:

<uc1:Wuerfel ID="Wuerfel1" runat="server" />

and a reference to the used control will also be generated:

<%@ Register Src="Wuerfel.ascx" TagName="Wuerfel" TagPrefix="uc1" %>

Open this file by using the browser and have a look to the source code that is delivered to the client - it will look very similar to what you had before. Again you can check whether everything is fine by pasting the <uc1:Wuerfel...> element several times. Visual Studio will automatically generate different ids so all elements work independent.

6. using the script including mechanism

You still have to take care of including the right JavaScript include in the <head> of your page. Now we also get this work done automatically. The advantage is that you do not have to take care of using the right include files and you will never forget to remove them when a control is removed from the page.

In the *.aspx page the <head> element must be marked with runat="server"

In the *.ascx file some server side programming is needed inside a <script runat="server"> tag:

protected override void OnPreRender(EventArgs e) {
  base.OnPreRender(e);

  if (Page.Header == null)
    throw new Exception("The <head> element of this page is not marked with
      runat='server'.");

  // register the JavaScripts includes without need for
    a Form.
  if (!Page.ClientScript.IsClientScriptBlockRegistered(Page.GetType(), "CommonBehaviour")) {
    Page.ClientScript.RegisterClientScriptBlock(Page.GetType(), "CommonBehaviour", String.Empty);
    ((HtmlHead)Page.Header).Controls.Add(new LiteralControl("<script type='text/javascript' src='"
      + Page.ResolveUrl("jcl.js")
      + "'><" + "/script>\n"));
  } // if

  if (!Page.ClientScript.IsClientScriptBlockRegistered(this.GetType(), "MyBehaviour")) {
    Page.ClientScript.RegisterClientScriptBlock(this.GetType(), "MyBehaviour", String.Empty);
    ((HtmlHead)Page.Header).Controls.Add(new LiteralControl("<script type='text/javascript' src='"
      + Page.ResolveUrl("Wuerfel.js")
      + "'><" + "/script>\n"));
  } // if
} // OnPreRender

Have a look at the files wuerfel_04.aspx and wuerfel.ascx.

7. using a global registration for the control

When dragging a User Control onto a page the UserControl is registered for this page by using a server site Register tag.

<%@ Register Src="Wuerfel.ascx" TagName="Wuerfel" TagPrefix="uc1" %>

There is no real problem with that automatic stuff but if you copy HTML code around from one page to another you always have to take care of copying these Register tags as well.

Fortunately there is another solution that registers User Contols globally in the web.config file and needs no Register tags.

Open the web.config file you can find in the root of your web application and locate the <configuration><system.web><pages><controls> region. Here you can add a add element:

<add src="~/controls/LightBox.ascx" tagName="LightBox" tagPrefix="ve"/>

You can find many samples in the web.config file of the AJAXEngine demo web site project and there is a good post on this topic in Scott Guthrie's blog too at: http://weblogs.asp.net/scottgu/archive/2006/11/26/tip-trick-how-to-register-user-controls-and-custom-controls-in-web-config.aspx

8. converting to a ASP.NET Web Control (*.cs) implementation

When writing simple controls without nested other controls there is no need to convert a UserControl into a WebControl. You need this step only when the control will be used as a wrapper to more HTML code that is declared on the web page and not within the control itself. If you download the complete source code of the AJAX Engine project you can find some advanced implementations using ASP.NET Web Controls in the APP_Code folder. Writing WebControls and designers for Web Controls is not covered here.

Update on the JavaScript client for SOAP based WebServices

2006-11-19T19:30:00.000+01:00

A core element of the AJAX Engine is a JavaScript based SOAP client that is used by the browser to call methods on the server implmented by regular webservices.

Up to now only document encoding was supported by the WSDL to JavaScript transformation implemented by wsdl.xslt. I prefer using the document-literal encoding style but while working with some older JAVA implementations I decided to implement the RPC model too.

The only file that I needed to change is the wsdl.xslt file that you can download at http://www.mathertel.de/AJAXEngine/ajaxcore/wsdl.xslt.

The documentation of the SOAP client and the proxy generator can be found in the book at http://www.mathertel.de/Ajax/AJAXeBook.aspx

It's also integrated into the new downloads.

Read about the SOAP Basic Profile at http://www.ws-i.org/Profiles/BasicProfile-1.1.html

Read some arguments against the SOAP encoding at http://msdn.microsoft.com/library/en-us/dnsoap/html/argsoape.asp

Searching the AJAXEngine Code

2006-10-05T21:31:00.000+02:00

Google released a new search tool named codesearch specially for coders. They support also Zip files that contain code and you can find the sources for the Ajax engine by using the link:

http://www.google.com/codesearch?hl=en&lr=&q=ajaxengine+mathertel

When you open on of the *.js files you also have a navigation through the zip file. on the top there is the path to the current opened folder and on the left side you can see al the files within that folder.

Nice feature !

Google caches the zip file so be sure to get the actual zip file from http://www.mathertel.de/AJAXEngine.

Help on this - Scope in JavaScript

2006-09-16T22:21:00.000+02:00

I really do not often link up to other postings on the web but in this case I have to!

Thanks to Mike West and his article "Scope in JavaScript" published at http://digital-web.com/articles/scope_in_javascript/.

I really like this article and I learned from it. It's the same story all the time: When you understand, things get easier and seems to be simpler.

If you've read my book you have noticed that I fell over the context problem when attaching JavaScript function to events. The solution I suggested was to implement a inner method that gets a usable context and there are some tricks implemented to find the right context by analyzing the target of the event.

Now, with the bind function I can reduce this overhead and we have right context right from the start.

It's not as easy as it seems

My first idea was to include the bind functionality into jcl.AttachEvent the cross browser compatible helper around attachEvent() or addEventListener() to register events but I had a lot of problems until I found that the DetachEvent is not working any more as expected.

The problem is that when using the bind() function you get a reference to a new, not the original passed function. Because you have no reference to this new function you can not use it when calling jcl.DetachEvent. If you want to detach the handler from the event you have to pass the same reference. Calling obj.detachEvent("onclick", handler.bind(obj)) will never work as expected.

... but don't give up

After some analyzing I found that most of the events are using functions that never get detached. The "on___" functions of the behavior object are automatically attached to the corresponding events but will never get detached until the page gets reloaded. These functions are now executed in the context of the bound object and it gets really access other members of the behavior.

The other situations that benefits a lot from the .bind function is when registering a timer event. Here a detach will never happen because the timer event gets canceled by using clearTimeout and you have to pass the timer, not the function reference. In many cases we need to call a method of a specific element like:

this._scrollTimer = window.setTimeout("document.getElementById('"
  + this.id + "').scrollend()", 100);

By using the bind function it looks like this:

this._scrollTimer = window.setTimeout(this.scrollend.bind(this), 100);

The other advantage you can see here is that a function reference can be passed to setTimeout which is faster than a string that gets evaluated.

New version is online

The web site was updated to this new version including a lot of new visual controls and some housekeeping bug fixes. - Get a copy from http://www.mathertel.de/Downloads/Start_AJAX.aspx or from the download area.

The Lightbox Visual effect

2006-08-20T19:48:00.000+02:00

The Lightbox is another visual effect that uses the semi transparent feature available in the modern browsers.

Here is is used to simulate another layer of user interaction by hiding the existing elements of the page and bringing up new elements in front of them.

modal user interaction

This effect was found to be useful for implementing modal windows or modal dialogs.

Modal user interaction is very helpful when implementing some functionality that sometimes needs to ask the user in the middle of the implementation without breaking the usual program flow.

I'm sure that you are using this feature as well by using the alert() or prompt() methods. The JavaScript interpreter will stop executing until the opened window is closed by the user by choosing one of the available options.

There have been some discussions in the past whether modal user interactions are good or bad and especially in the apple era modal windows and dialogs where found to restrict the user's freedom.

Now with HTML pages true modal dialogs cannot be implemented any more. The Microsoft Internet Explorer offers a showModalDialog method that allows opening true modal windows. There are some tricks necessary to use this feature with dynamic build content, see http://weblogs.asp.net/datagridgirl/archive/2005/08/11/422309.aspx.

The Mozilla/Firefox offers a similar feature by using a special parameter in window.open, but you need some special privileges that are not available on the Internet to make it work.

Anyway it is all non-standard.

Lightbox implementations

You can find some implementations on the web:

http://www.blakems.com/archives/000075.html http://www.huddletogether.com/projects/lightbox/ http://particletree.com/features/lightbox-gone-wild/

or just search the word "lightbox".

I implemented a ASP.NET User Control together with a client side JavaScript Behavior that implements the lightbox effect that can be used with embedded dialog elements.

The implementation has a extensibility model implemented so you can effectively show any kind of resource that is available. Pictures for example normally have no buttons or links but you need some elements in your dialog to close the dialog, show the next element or ...

All you need to use this visual effect is to include the lightbox user control:

<ve:LightBox ID="LightBox1" runat="server" />

There can only be one lightbox element on a page. The methods coming with the behavior are all usable by calling them directly on the LightBoxBehavior.

Elements that should be displayed on top of the page can be implemented very easily using a simple div-element with a given width and height:

<div id="HelloWorld" style="display:none;width:180px;height:140px">
  <p>Hello world.</p>
  <button onclick="LightBoxBehavior.hide()">close</button>
</div>

It's a good idea to add some more style attributes to the outer <div> element to make it more look like a small dialog:

style="background-color:white;border: solid 2px #203050; padding: 2px;"

A small Image Slide Show

I've also implemented a more complex sample, a Image Slide Show. You can find the code in the implementation of this page by using the "View Source" link in the upper right corner of the page.

It is also implemented by using a JavScript Behavior and handles some keys by attaching to the keydown event.

See it in action at: http://www.mathertel.de/AJAXEngine/S04_VisualEffects/LightBoxDemo.aspx

AJAX Konferenz

2006-07-15T12:01:00.000+02:00

"--> Mit AJAX bahnt sich eine Revolution im Internet an" ist der Opener der AJAX in action Konferenz vom 27. - 28. September bei Frankfurt - zu recht wie ich meine.

Es sind viele interessante Speaker und Themen dabei. Besonders interessant ist, dass viele Plattformen vorgestellt werden und letztendlich treffen sich alle wieder im Browser mit JavaScript und XMLHttpRequest Objekten.

Was AJAX-Entwickler über Web Services wissen sollten

Mein Vortrag beschäftigt sich mit WebServices und den Protokollen die in AJAX Applikationen verwendet werden. Wer mein Blog liest (insbesondere die Beiträge im letzten Jahr rund um SOAP im Juni und Juli kennt meine persönliche Vorliebe für Standard-Protokolle. Es gibt aber noch mehr aus diesem Bereich und im letzten Jahr hat sich auch einiges getan.

AJAX Book now available as PDF download

2006-07-05T21:27:00.000+02:00

As requested by some people the book "Aspects of AJAX" is now available in PDF format so you can easily take it with you. I will update it from time to time when new text on theis Blog or samples on my website are written. So come back and check for new versions.

>> AJAX book download.

It's written in English so it can reach most IT people. My native language is not English so please excuse my typos or just let me know about.

Building a AJAX enabled popup control

2006-06-16T19:15:00.000+02:00

When fetching the extra information costs a lot of resources (cpu, memory or time) on the server or is more than just a few words it is better to not include it into the page all the time but get it from the server when the user requests for it. This scenario is perfect for using the AJAX technology.

Using the AJAX engine

To get the information from the server we need a web service with one method that gets a key string as parameter and returns the popup information. We can trust this method so far that we can rely that it is returning valid html code.

The timer object that we need to delay the popup a little bit can be completely replaced by using the delay option of the AJAX engine.

The onmouseover event code only needs to start the AJAX engine after checking for a valid html object.

ajax.Start(AJAXPopUpBehaviour.action, obj);

The action that describes the AJAX mechanism for the popUp keeps all the elements of the asynchronous execution together. It prepares the server call be fetching the url of the hyperlink, calls the GetDetails method on the server and then finishes the action by showing the popUp control.

action: {
  delay: 300,
  queueMultiple: false,
  prepare: function(obj) { return (obj.href); },
  call: "proxies.ServerInfo.GetDetails",
  finish: "AJAXPopUpBehaviour.show",
  onException: proxies.alertException
}

Using a Web Control

But it still can be easier by using a web control:

<ajax:PopUp runat="server" id="ajaxpopup1" infomethod="proxies.ServerInfo.GetDetails" />

The method that returns the information to the client is made availale to the client by including the WebService and creating a JavaScript proxy:

<script type="text/javascript"
  src="../ajaxcore/GetJavaScriptProxy.aspx?service=../S03_AJAXControls/ServerInfo.asmx">
</script>

Implementing the sample web control

On the client a JavaScript Behavior is used that is included into the page by the web control that is executed on the server. Read more and see the sample live at: http://www.mathertel.de/AJAXEngine/S03_AJAXControls/AJAXPopUpDemo.aspx.

An ASP.NET popup web contol

2006-06-04T18:36:00.000+02:00

I just added a new control to the library that displays a popup on the page that can be used to show additional information on a specific topic or item.

A detailed description and the source can be found on my web site. Have a look at http://www.mathertel.de/AJAXEngine/S04_VisualEffects/PopUpDemo.aspx.

Visual Studio .NET add-in updated

2006-05-30T22:43:00.000+02:00

One of my older projects where updated today.

I missed some commands so I started developing a collection of useful tools that help developing and controlling my work and files. The result was an add-in for Visual Studio that adds commands for comparing files and folders, an explore command, and some useful reports for web projects.

Give it a try at: http://www.codeproject.com/csharp/WebReports8.asp

Update to the back-button and history implementation

2006-05-28T18:54:00.000+02:00

The last past was about implementing a back-button and local history support to the AJAX Engine.

I've added 2 attributes to the PropHistory web control that can be declared to avoid some scripting on the page:

<ajax:PropHistory runat="server" stateList="version,book,chapter" propList="vers" />

stateList specifies the page properties that together form the current state of the page. A change to the value of any of these properties will cause a new entry in the history of the browser.

propList specifies the page properties that are persisted in the hash part of the url so that hyperlinks will work.

The implementation takes care of the fact that all properties in the statList must also be part of the url but you don't have to specify them again in the propList attribute.

The download files where updated today too.

Ajax.zip contains the ASP.NET 2.0 web project that builds the side. The complete AJAX Engine and all samples are included. Use this project when you want to start building your AJAX web application.

AJAXEngine.zip This Zip-File contains the core files of the AJAX engine and the AJAX controls. You can use this if you want to update your project with the updated core files.

Another view to the Back Button Problem of AJAX applications

2006-05-12T22:47:00.000+02:00

A lot of people already wrote about this topic. Search "AJAX BACK BUTTON PROBLEM" on a search portal and you can find a lot of stuff about it!

But there are still aspects that haven't been talked about.

Let me explain that the problem is old, well known, not an AJAX specific problem and after all: technically solved.

What the back button does - and why not

Still some people think that the web is a mass of pages pointing to each other using hyperlinks. While navigating along these hyperlinks every visited page is recorded into a local list often called "history". The original idea was to support this list of pages with some functionality.

When framesets came into the browser model this simple idea got the first scratch because when you use hyperlinks that change only the content of a frame the url doesn't change. The url that you can see in the address is not the only information you need to restore a browser situation.

Up to here the back button still works in the browsers, because they also record this extra information together with the url - at least when working with the browser history functionality.

Then there are web servers that found a (not so) wonderful trick to use forms for navigating from one page to another and things get complicated. Hyperlinks can be used to submit the content of a form (including the current browser state) back to the server which then returns the next or the modified page. A problem on this approach is that the same url (main.do, main.aspx, main.jspx, main.php, ...) can be reused for the whole application.

Here the back button also has to record all the data that was posted to the server so it can be re-posted when the user wants to go one or more pages back.

This kind of request cannot in generally be distinguished by the server from clicking the same button of a form twice and often there are filters available on the server to redirect these requests to another page.

And this is why navigating back using the back button of the browser often doesn't work.

And this is why many applications start a new window at the beginning without displaying the navigation bar that includes the back button.

And this is why many users like the back button on the mouse or keyboard (ALT-LEFT).

And this is why the web doesn't work like this (too often).

The favorite problem

As with the history list a very similar problem exists with the favorites and with web urls stored in files. When you save a current page to your favorites list you might think that this helps you coming back to this page but if the server needs post information or the page is built using frames you might become disappointed because this kind of information is not stored in hyperlinks.

The IE implements a special *.url file type that is created when using the IE built in "Add to favorites..." command that contains extra information about the current urls of the frames and maybe more.

But the *.lnk file type that is created when dragging an URL from the IE address bar to the desktop as well as the url file that is created by Mozilla/Firefox doesn't hold this information.

What's the problem?

The problem with the back button existed long before AJAX applications became widely known. The core of the problem is about building a web application that works by using meaningful urls whether using frames or not and enabling the usage of the history and favorites feature of the existing browsers.

AJAX applications do have the same problem like those applications doing everything through a single url: it's meaningless and you cannot rely on any posted information because it just doesn't exist.

So what we all have to do is giving our applications meaningful urls.

Meaningful urls

Not every click should change the url and in many applications there is no clear "back" situation. If you browse your mail inbox for example a click to open a message may be a clear "navigate to" situation. When you delete the message by using a click on a button the main UI might navigate for you to the next message in the list. But where is the "back" position now - on the deleted mail?

You can also argue that moving on to the next mail is neither forward nor back but something like up and down and back will always bring you back to the list view you started.

So what I want to say is that the (forward and) back direction is often very application or problem specific. With AJAX you have the chance to model these situations the way you like and the way that is the best for your application and you are not bound to the GET and POST requests done by hyperlinks and forms.

I use the url as a textual key to the global addressable state of an Ajax application. By moving some information into the url and reading this information out of the url when a page loads or the urls changes, there is a clear interface between the Ajax page and the external world that can be used for storing browser history, favorites and links.

The back problem is technically solved

If you look for a good article on how to implement a technical solution to the problem have a look at the article "AJAX: How to Handle Bookmarks and Back Buttons" by Brad Neuberg at http://www.onjava.com/lpt/a/6293.

... by tricking IE

The Mozilla/Firefox solves this problem really straight forward and it works as expected.

When using the method window.location.replace(newHash) only the current URL is changed.

By assigning a new value to the window.location.hash property a new entry in the history list is created.

The IE is very confused about URL-hash values hat do not really point to existing anchors and does not record any history and needs a invisible iframe with a page coming from the same server. It's a little bit tricky to get all situations working and you can see the current implementation by looking into the JavaScript implementation of the PropHistory Behaviour (view source).

Implementation

The AJAXEngine already has a client side state mechanism (Page Properties or DataConnections) I introduced in September 2005 that stores key-value pairs. Instead of building a new API and leave it to the AJAX application to call a method to change the URL you only have to declare what page properties should be used in the URL. When a Page Property's value changes the URL is updated automatically and when the URL changes all connected controls will get informed about it.

When one of the properties, that define a state that should be persisted to the history changes, a new history entry is recorded.

All you need to do to make it work is to include the PropHistory control:

<ajax:PropHistory runat="server" />

and to declare what properties should be used to form the url (propList) and what subset of these properties should define the state (stateList):

<script defer="defer" type="text/javascript">
  // set default values for the Page Properties, if the value is not in the URL:
  jcl.DataConnections.Load("version", "luther1912");
  jcl.DataConnections.Load("book", "1");
  jcl.DataConnections.Load("chapter", "1");
  jcl.DataConnections.Load("vers", "1");
 
  // declare the properties that should be written to the URL:
  PropHistory.propList = {"version":"","book":"","chapter":"","vers":""};
 
  // declare the properties that are meaningful for history recording:
  PropHistory.stateList = {"version":"","book":"","chapter":""};
</script>

The sample comes from the updated Bible reader application. When you navigate through the verses of a chapter, only the URL gets changed. The navigation to a new book, version or chapter a new entry in the history stack is created.

You now also can use URLs to jump directly to some important content. Donald E. Knuth likes reading any book chapter 3 verse 16 and specially BiblePage.aspx#version=sf_kjv_strongs_rev1b&book=43&chapter=3&vers=16 and an important verse of the upcoming da vinci code movie by Dan Brown is BiblePage.aspx#version=en_gb_KJV2000_1&book=18&chapter=38&vers=11

Moving HTML objects using drag and drop around, CSS and JavaScript

2006-04-25T23:07:00.000+02:00

If you want to enable a custom page layout for the user or a drag & drop functionality in your solution you need a mechanism that enables moving html objects around. Here is a cross browser compatible solution that enables moving of HTML objects.

To make it easy to attach a moving functionality to a object I use the lightweight JavaScript Behaviour mechanism that is described in the AJAX eBook found here: http://www.mathertel.de/AJAX/AJAXeBook.aspx. Especially the cross browser event handling mechanism is used here.

Attaching the mouse events

Three events must be captured to drag objects around:

onmousedown

This event starts the moving scenario and you need to attach a method to this event.

It is sometimes necessary not to move the object that got this event but to identify a specific parent object that also contains other content elements. In this demo sample the title area of a web part is used to drag the whole part around. In the method that is attached to this event the parentNode references are searched until an html object is found that is marked with the className "VEPart".

Then current mouse offset to the left upper corner of the moving object is calculated. This is because you will not start dragging by using a exactly known single point of the object.

Now that we know that a specific object should be dragged around the 2 other events must be monitored and 2 other methods are attached to them.

onmousemove

This event will be thrown multiple times and we will move the object arround by using the new mouse coordinates given each time the event gets fired.

onmouseup

This event will be thrown at the end when the user wants to place the object at the new position by releasing the mouse button.

The first event can be caught on specific objects that enable the moving. I use the CSS class "VEMover" to mark these elements and attach a move cursor. The object that is moves is marked by using the CSS class "VEPart" that contains the VEMover.

The 2 other events should be caught on the document level because they will not be thrown always on the object that initiates the moving especially when the mouse pointer is moved very fast.

Because we need a reference to the object that is moved around the onmousedown event also saves a reference to the object by using properties of the MoverBehaviour element like a global variable so we can find the object again when onmousemove and onmouseup events are caught.

A simple moveable object

<div class="VEPart" style="width:180px;height:90px">
  <div class="VEMover">::: move me</div>
  I can be moved.
</div>

The JavaScript implementation

To make the implementation easier I use my JavaScript Control Library that enables writing compatible behaviours for HTML objects. All we need here is to include the 9 kByte jcl.js file and attach the behavior to the VEMover object.

The MoverBehaviour implements the 3 event handlers:

var MoverBehaviour = {
  mo: null, // reference to the movable obj,
  x: 0, y: 0,
  
  // ----- Events -----
  onmousedown: function (evt) {
    evt = evt || window.event;
    var src = jcl.FindBehaviourElement(evt.srcElement, MoverBehaviour);
    src.MoveStart(evt);
  }, // onmousedown


  // track mouse moves. This handler will be attached to the document level !
  _onmousemove: function (evt) {
    evt = evt || window.event;
    MoverBehaviour.MoveIt(evt);
  }, // onmousemove


  // track mouse button up. This handler will be attached to the document level !
  _onmouseup: function (evt) {
    evt = evt || window.event;
    MoverBehaviour.MoveEnd(evt);
  }, // onmouseup


  // ----- Methods -----
  MoveStart: function (evt) {
    // find the moving part (position:absolute or class="VEPart")
    var mo = this;
    while ((mo != null) && (mo.className != "VEPart"))
      mo = mo.parentNode;

    if (mo == null)
      return; // don't move
    MoverBehaviour.mo = mo;
      
    // calculate mousepointer-object distance
    mo.x = mo.y = 0;
    obj = mo;
    while (obj != null) {
      mo.x += obj.offsetLeft;
      mo.y += obj.offsetTop;
      obj = obj.offsetParent;
    } // while
    mo.x = evt.clientX - mo.x;
    mo.y = evt.clientY - mo.y;

    // make the moving object globally evailable when mouse is leaving this object.
    jcl.AttachEvent(document, "onmousemove", this._onmousemove);
    jcl.AttachEvent(document, "onmouseup", this._onmouseup);
  }, // MoveStart
  

  MoveIt: function (evt) {
    var mo = MoverBehaviour.mo;
    if (mo != null) {
      var p = (evt.clientX - mo.x) + "px";
      if (p != mo.style.left) mo.style.left = p;
      p = (evt.clientY - mo.y) + "px";
      if (p != mo.style.top) mo.style.top = p;
    } // if
    // cancel selecting anything
    evt.cancelBubble = true;
    evt.returnValue = false;
  }, // MoveIt
  

  MoveEnd: function () {
    var mo = MoverBehaviour.mo;
    if (mo != null) {
      MoverBehaviour.mo = null;
      jcl.DetachEvent(document, "onmousemove", this._onmousemove);
      jcl.DetachEvent(document, "onmouseup", this._onmouseup);
    } // if
  } // MoveEnd
    
} // MoverBehaviour

jcl.LoadBehaviour("moveme", MoverBehaviour);

The sample web page is available at http://www.mathertel.de/AJAXEngine/S04_VisualEffects/MoverDemo.aspx and a brief description of the JavaScript control library is available on web site in the eBook about my AJAX engine in the chapter "Building AJAX Controls" at: http://www.mathertel.de/AJAX/AJAXeBook.aspx.

The MoverBehaviour is also available as a separate include file if you want to follow my advice of reusing behaviours by separating them into a JavaScript include file. I will have a typical WebPart sample soon and will use the mover functionality there again.

Less waiting on AJAX

2006-04-22T21:46:00.000+02:00

It's a psychological phenomena that waiting takes less time as long as something happens.

I'm sure you have seen all these nice rotating arrows, bouncing points or bars that are commonly used for situations where a progress bar should appear to tell the user that it's time for waiting like on the windows start up screen on http://www.pageflakes.com/ or even in windows media edition. It can also be as simple as the [Loading...] text that is used by the Google-Mail user interface.

So, when I fell over http://www.ajaxload.info last week where you can easily generate "AJAX-" animated gif files I thought it is time to implement a few lines into the AJAX Engine.

The right place to start displaying a progress indicator is just before starting the webservice call to the server. Here I call StartProgress().

But it also has to be hidden after anything happens that ends the action like when the return value is there, an exception happens or when the timeout timer strikes. To identify these places I searched the code for the ajax.current gets cleared. There I call EndProgress();

The first implementation was straight forward creating and removing a html element. After some testing I found that this costs me more time than the real call over the internet and in many situations immediate responses got slower and that's definitively not that what I wanted to achieve.

In the end I came to the following solution:

The StartProgress function only sets a flag (ajax.progress) to true and starts a timer (ajax.progressTimer) with a timeout of 220 msec.
This time was chosen by some testing and many server calls do not last so long and therefore need no progress indicator.
When the timer strikes it calls the ajax.ShowProgress function. Here I implement the real code that creates the HTML element or just shows an existing one again.
The EndProgress function clears the flag and also starts the timer but with some less waiting.
When the timer strikes after a call has finished the existing object is just hidden.

This architecture has some advantages. First the progress indicator is not shown when short calls are made and when multiple calls are made one after the other it is not hidden. This can save a lot of flickering.

Here are the specific new functions:

// ----- show or hide a progress indicator -----

// show a progress indicator if it takes longer...
ajax.StartProgress = function() {
  ajax.progress = true;
  if (ajax.progressTimer != null)
    window.clearTimeout(ajax.progressTimer);
  ajax.progressTimer = window.setTimeout(ajax.ShowProgress, 220);
} // ajax.StartProgress


// hide any progress indicator soon.
ajax.EndProgress = function () {
  ajax.progress = false;
  if (ajax.progressTimer != null)
    window.clearTimeout(ajax.progressTimer);
  ajax.progressTimer = window.setTimeout(ajax.ShowProgress, 20);
} // ajax.EndProgress


// this function is called by a timer to show or hide a progress indicator
ajax.ShowProgress = function() {
  ajax.progressTimer = null;
  var a = document.getElementById("AjaxProgressIndicator");
 
  if (ajax.progress && (a != null)) {
    // just display the existing object
    a.style.top = document.documentElement.scrollTop + 2 + "px";
    a.style.display = "";
   
  } else if (ajax.progress) {
    // find a relative link to the ajaxcore folder containing ajax.js
    var path = "../ajaxcore/"
    for (var n in document.scripts) {
      s = document.scripts[n].src;
      if ((s != null) && (s.length >= 7) && (s.substr(s.length -7).toLowerCase() == "ajax.js"))
        path = s.substr(0,s.length -7);
    } // for
   
    // create new standard progress object
    a = document.createElement("div");
    a.id = "AjaxProgressIndicator";
    a.style.position = "absolute";
    a.style.right = "2px";
    a.style.top = document.documentElement.scrollTop + 2 + "px";
    a.style.width = "98px";
    a.style.height = "16px"
    a.style.padding = "2px";
    a.style.verticalAlign = "bottom";
    a.style.backgroundColor="#51c77d";

    a.innerHTML = "<img style='VERTICAL-ALIGN:bottom' src='" + path + "ajax-loader.gif'> please wait...";
    document.body.appendChild(a);

  } else if (a) {
    a.style.display = "none";
  } // if
} // ajax.ShowProgress

You can find the full source here and I will also include it into the next ajax.zip.

If you want to see how it looks like you can use the old prime factor sample. Try some long the numbers like: 98798798789878987. You might see it only if someone else is stressing the server too - It seems to be a powerful machine :-) and prime factors get calculated fast even with my stupid algorithm :-).

Simple sliding sample to move HTML elements around

2006-04-20T21:32:00.000+02:00

Moving HTML objects to new positions is not hard to implement. You can use absolute positioning and just set the style attributes left and top to the new values but it doesn't look cool if the objects use this kind of hyper speed: the eyes cannot follow and there may be a confusing effect of a sudden rearrangement.

Moving objects more slowly can be simulated by moving them using several steps and only a small distance at once. All we need is a timer to start the next step after the current position is rendered, a little bit of algebra and a heuristic to find the right distance for one step.

Because no local variables can be used when executing timer scripts we declare 4 global variables that hold all the information we need when the next step is to be started:

var slidingTimer = null; // the current running timer object
var slidingTarget = null; // the moving object
var slidingLeft = null; // the target left position
var slidingTop = null; // the target top position

Starting a sliding movement can be done by calling the startSlidePos function with 3 parameters: the object that should be moved, the new left and the new top coordinate. You can also refer the object by using the unique id.

onclick="startSlidePos('i', 10, 270)"

Every timer event now calculates the remaining vector but takes no more than 20 pixel length or a third of it whatever is shorter. Only if the target is very close the object will be positioned exactly:

// calc the remaining vector
dx = slidingLeft - left;
dy = slidingTop - top;

// calc the movement length along the vector
len = Math.sqrt(dx * dx + dy * dy);
delta = Math.min(20, len/3);

if (len <= 2) {
  // snap exactly
  left = slidingLeft;
  top = slidingTop;

} else {
  left += Math.round(dx * delta / len);
  top += Math.round(dy * delta / len);
} // if

Using this calculation the movement gets slower at the end when the target is almost reached.

You can see the full source code by using the view source functionality of your browser or in the right upper corner of the page.

You can find the sample live at: http://www.mathertel.de/AJAXEngine/S04_VisualEffects/SlidingDemo.aspx

HTML elements with rounded corners

2006-04-17T21:20:00.000+02:00

HTML elements up to now have always a rectangle shape. In the upcoming CSS3 standard (still a proposal) there might be also other border shapes available including rounded corners by specifying a border radius. But we do not have to wait to get this visual effect shown up.

The trick that is shown here to get the usual rectangle corners into a round shape is to use a collection of thin HTML elements to build a non rectangle border.

The simplest solution to this is to use <div> at the top and bottom and arrange them like this:

Why not using a client side solution

The Rico framework for example is offering a client-side method to round the elements:

<div id='roundDemo' style='width:300px'>Insert content here.</div>
<script>Rico.Corner.round('roundDemo', {corners:'tl br',bgColor:'#adba8c'});</script>

By using a JavaScript solution on the client to generate these elements every div element can be transformed to a rounded corner look. The disadvantage of this approach is that there is always a delay and maybe a light flickering because the page will get rendered twice because the borders will be expanded by adding the additional elements.

Why not using graphic elements

I've also seen solutions that use 4 specific corner graphics. The drawback about this approach is that the colors of these images must correspond exactly to the colors of the other html elements. If you want to change your style then you must change the images too. Again here will be a light flickering because images are often loaded after displaying the page for the first time so it doesn't look very perfect.

A server-side solution

It is also possible to generate all the additional html elements on the server. This adds some html tags and some more data to the http response when the page gets loaded but also eliminates a lot of JavaScript or images.

For ASP.NET I've written a web control that derives from asp:Panel that does the same and avoids the flickering:

<ajax:RoundedArea runat='server' id='any' width='300'>Insert content here.</ajax:RoundedArea>

You can see a live sample of it at http://www.mathertel.de/AJAXEngine/S04_VisualEffects/RoundedDemo.aspx.

HTML + CSS Shadow Effect with real transparency

2006-04-08T15:43:00.000+02:00

If you want to give your objects a kind of 3D feeling then you might want to use shadows for those objects that are placed upon the web page.

Using special graphics

A often solution for a shadow effect is to use table layout around the main content and arrange a set of graphics around the right and bottom border. You can get really wonderful shadow dropping effects using this approach but because semi transparent images are not very well supported on IE you will have to pay attention to the background color you use on the page and have to mix it into your shadow images.

Using a Microsoft IE specific CSS filter attribute

When using the IE only you can also us one of the wonderful filter effects that are available in this browser. Just add a CSS filter attribute like that:

filter: progid:DXImageTransform.Microsoft.dropShadow(Color=AAAAAA,offX=8,offY=8,positive= true);

If you use IE that you can see these shadows on the entry page for the visual effects library. These shadows are also drawn by using solid colors.

Using CSS opacity

Here is a better solution that really resembles a kind of shadow because the text and graphics in the shadow are really displayed in dimmed light. The clue to this effect is a built-in opacity CSS graphics effect that is available IE, Mozilla, Firefox - but in different way.

In Internet Explorer: style="filter: alpha(opacity= 50)"

The IE notation of the opacity effect is using a proprietary CSS attribute named filter that can be used to add various effects to a HTML element. Here we use the alpha filter.

In Mozilla/Firefox: style= "-moz-opacity:0.5"

The Mozilla / Firefox provides a proprietary css attribute named -moz-opacity that allows specifying a opacity value.

In Opera: style= "opacity:0.5"

The Opera browser also has a proprietary css attribute named opacity that allows specifying an opacity value.

These 3 CSS attributes can be combined together and every browser ignores all the attributes that are unknown:

style="filter: alpha(opacity= 50); -moz-opacity:0.5; opacity: 0.5"

The HTML shadow object

This effect must be applied to rectangle region with a fixed width and height that is over the main content by using an absolute position by using the same size as the html part that is dropping this shadow.

Here is a simple sample that uses this trick. You can see it live at ShadowDemo.aspx.

The good about this solution is, that no graphics are used and that the shadow does not hide the text below but only seems to dim the available light.

The outer div element is used to do the absolute positioning of the whole group.
The first inner <div> element is the object that has the opacity effect applied. It is positioned some pixel to the right and down by using an absolute positioning (relative to the containing <div>) too.
The Content is placed inside the second inner <div> element that must have a relative position without any offset to be displayed above the shadow object.

Here is the plain HTML code:

<div class="VEPart" style="position: relative; width: 120px; top:-90px; left: 40px;">
  <div class="VEShadow" style="position: absolute; left: 10px; top: 10px;
    width: 120px; height: 84px; background-color: black;
    filter: alpha(opacity=30); -moz-opacity: 0.3; opacity: 0.3;"> </div>
  <div class="VEContent" style="position: relative; height: 80px;
    background-color: #FFFFDD;"> I am flying above the text and dropping a shadow.</div>
</div>

You can see how it looks like on the demo website at http://www.mathertel.de/AJAXEngine/S04_VisualEffects/ShadowDemo.aspx

Why AJAX needs visual effects

2006-04-03T20:59:00.000+02:00

Implementing a web based application by using AJAX techniques is about improving the backside, will elable the right user experience and will make your application work the way it should.

If you want that your application really looks like AJAX you also have to give your application a modern design together with all kinds of visual effects. That will really impress!

Don't you think that this is nonsense ? - I did for some time last year but I had to change my mind - at least a little bit.

If you travel across the web sides of the commercial AJAX frameworks you will find on almost every site a bunch of visual effect libraries that are technically not bound to asyncronous JavaScript and XML nor xmlhttp.
Commercial frameworks like backbase or frameworks like script.aculo.us do offer visual effects side by side with AJAX functionality.
Some of the effects shown here are really stupid eye-catcher effects.
Web applications that do not use xmlhttp but do asynchronous image loading are seen as AJAX applications.
Articles about AJAX do mix up client-server communications with visual effects. A sample on that: http://www.maxkiesler.com/index.php/weblog/comments/451/
Another article: AJAX Rounded Corner Tutorials at http://encytemedia.com/blog/articles/2005/12/01/rico-rounded-corners-without-all-of-rico
Another article: Ajax Workshop 2 - Building Tabbed Content at http://www.ajaxlessons.com/2006/02/18/ajax-workshop-2-building-tabbed-content/
... and you can find a lot more of them

Visual effects are definitvely an important aspect for AJAX applications today. Maybe the "market" will learn the technical difference in some near future. Maybe a "get-it-all-together" solution is the right approach for the "market".

So here is a list of visual effects and other "cool" looking stuff. Some of these effects can also be used in any other html based application, some of them will use AJAX. I'll explain the HTML+CSS+JavaScript that makes the effect but I will also bring the higher level approach using ASP.NET web controls that makes using them really easy.

AJAX applications look great! :-)

So here comes a library of visual effects. From time to time I will add another one and you will find them also on the demo side at http://www.mathertel.de/AJAXEngine/ see Examples -> Visual Effects .

The documentation you will find here on my blog and (with a little delay) in the AJAX eBook at http://www.mathertel.de/ajax/eBook.aspx. You will not find only a working solution but also a brief description on how it works so you can also use it in any of your projects too.

SOAP was made for AJAX

2006-03-04T14:03:00.000+01:00

I recently ran over the blog of Dave Winer and his post from Sun, Sep 12, 1999 titled "An end to the Über-Operating System". see: http://davenet.scripting.com/1999/09/12/anEndToTheUberoperatingSystem

... The purpose of both specs [SOAP and XML-RPC] is to enable scripted web applications to cross operating system boundaries.

Of course the term AJAX was not known then but I thing that "scripted web applications that cross operating system boundaries" is a good definition of AJAX. By using SOAP there even is more XML on the wire than with AJAX applications using a JSON or plain text transport protocol.

Ask yourself: what is or should be the standard protocol for AJAX applications when retrieving data from the server? - By using SOAP many aspects of a transport layer have been discussed (data types, attachments ...) and there are even more upcoming standard extensions for it (security, routing ...).

The only thing that I really miss is a built-in native SOAP client in browsers.

The (deprecated) SOAP spec from 1999: http://www.oasis-open.org/cover/draft-box-http-soap-00.txt. I think that this doc is one of the most influencing documents I've read. It disappeared from the Microsoft site and http://www.ietf.org. Does anybody know who feels responsible for achieving historical documents from the internet?

Thanks to Don Box, Dave Winer and all the other founders of SOAP.

Use web services with multiple parameters in the AJAX Engine

2006-02-19T15:41:00.000+01:00

In the past moths I've got mails that all request for more functionality in the javascript webservice proxies and the AJAX engine so I've added more support for datatypes and arrays in december last year and got some more compatibility with other SOAP implementations then ASP.NET.

I've also got some requests that describe to reuse existing web services that have multiple parameters on a AJAX page and I think this is a valid request.

While it is possible to use web methods with multiple parameters when using the web service proxies layer directly, the AJAX engine level is only supporting one parameter - but there is a small trick that help you out of this situation.

The AJAX engine knows about all the asynchronous steps that have to be done to complete the whole functionality through the declaration of an action object. The details about that can be found in the documentation at http://www.mathertel.de/ajax/Aspects%20of%20AJAX_index.htm. See the chapter about the "AJAX Actions".

Now have a look how this mechanism can be used with multiple webservice parameters. You can find a sample that simply adds 2 integers at http://www.mathertel.de/AJAXEngine/S02_AJAXCoreSamples/CalcAJAX.aspx

The prepare function is normally used for retrieveing the client-side parameter from the html objects. Because we need more than one parameter we just do nothing here except returning the context object.

The call function, that is called next is not just pointing to the proxy function of the method of the web service but needs some more code. It retrieves all the parameters itself and then calls the proxy method webservice. The trick is, that the mechanism that handles asynchronous result messages is not hooked up correctly and must be patched by using 2 lines of code for the regular and the exception case:

proxies.CalcService.AddInteger.func = this.call.func;
proxies.CalcService.AddInteger.onException = this.call.onException;

Now the call will be processed asynchronously and the result value will be passed to the finish function as usual.

Here the complete code that declares the AJAX action:

// declare an AJAX action
var action1 = {
  delay: 200, // wait for multiple keystrokes from fast typing people
 
  // the prepare function just returns the context object (if any)
  // and makes it available to the call function.
  prepare: function(obj) { return (obj); },

  // the call is not pointing to the webservice proxy directly but calls it using several parameters.
  call: function (obj) {
    var n1 = document.getElementById("n1").value;
    var n2 = document.getElementById("n2").value;
    proxies.CalcService.AddInteger.func = this.call.func; // patch
    proxies.CalcService.AddInteger.onException = this.call.onException; // patch
    proxies.CalcService.AddInteger(n1, n2); // and call
  },
 
  // the result will now be processed as usual.
  finish: function (p) { document.getElementById("outputField").value = p; },
 
  onException: proxies.alertException
} // action1

Comparisation of AJAX frameworks

2006-02-04T20:26:00.000+01:00

Daniel Zeiss, who is the man behind the ComfortASP.NET framework see http://www.comfortasp.de/ has published a very interesting comparison on his web site (http://www.daniel-zeiss.de/AJAXComparison/Results.htm) and his blog (http://www.geekswithblogs.com/danielz).

(Have you noticed that there are many German developers involved in AJAX engines and frameworks?)

I have also implemented the simple sample he uses for the comparison at http://www.mathertel.de/AJAXEngine/S02_AJAXCoreSamples/AJAXComparison.htm.

My annotations on these results

The Aspects of AJAX Engine is consuming less bytes on the network that most of the other machines in this comparison.

The size of the transferred bytes is indeed a very interesting aspect. I have not spent any time in reducing this value and I also have no chance to reduce the bytes of a standard SOAP call without leaving this standard and adding the need to implement server specific code.

The initial transfer of the page is smaller than the original ASP.NET version mainly because I do not need any ASP.NET functionality for deploying a working page.

The biggest part of the Engine is the ajax.js file with 21876 bytes because it contains a lot of comments and additional information. I could reduce this page in a view minutes by stripping off all the comments and blank lines down to 12000 bytes and it can be reduced even more. Thats the size that should be used in the comparison because the other frameworks also only send optimized include files.

The other AJAX implementations are very strong bound to the ASP.NET programming model and therefore have to solve many content-update topics - That's what Daniel Zei calls "indirect AJAX programming". The Aspects of AJAX Engine only transfers data on the network and must right now implement content changes on the client using JavaScript. This is also true for many other "direct AJAX programming" environments. By using AJAX enabled controls, even this work is not necessary because the controls can handle themselves and only the developer of the control itself has to think about it.

Aspects of AJAX: An Engine for Java

2006-02-03T21:31:00.000+01:00

This AJAX Engine was originating published in 2005 for the ASP.NET 2.0 Platform and is now partly also available in JAVA. This Engine can be ported very easily because it relies on web standards that are available on many platforms and in many languages:

JavaScript / ajax.js

A huge part of the coding is done using JavaScript on the client. This code needs shared by both projects and is always exchangeable.

WebServices

The asynchronous calls from the page in the browser to the server are implemented using the SOAP standard. On the server we only need Standard WebServices. Both platforms, ASP.NET and Java support the bottom up implementation of WebServices and we just need to write simple methods that get called from the client.

XSLT / WebService Proxies

To enable a communication from the client side, the server uses the WSDL definitions that can be generated from WebServices on both platforms and transforms them to proxy objects using JavaScript.

The retrieval of the WSDL and for the transformation is ported and needs only about 30 lines of code that you can find in ~/ajaxcore/GetJavaScriptProxy.aspx or ~/ajaxcore/GetJavaScriptProxy.jsp.

The definition of the translation itself is coded using an xslt definition in the file ~/ajaxcore/wsdl.xslt that is also identical on both platforms.

The AJAX Engine needs nothing else than these 3 building blocks.

Download

The download is available on my web side: http://www.mathertel.de/AJAXEngine/ in the download section containing a eclipse project. I use right now: Eclispe 3.1.2 with the Webtools plug-in 1.0, Java 1.4.2.x, Tomcat 5.5 incl. the compatibility jar and Axis 1.2.1

Documentation

If you search for more documentation use the following links that are part of the ASP.NET version written in C#. Java programmers should understand the code very easily and there are also many JavaScript hints and tricks documented in there.

http://www.codeproject.com/soap/JavaScriptProxy_01.asp A early available documentation about how the JavaScript proxies are generated and how they work.

http://ajaxaspects.blogspot.com/ The blog where all you can find all the documentation that was written while the project was growing.

http://www.mathertel.de/AJAXEngine/ The ASP.NET based demo WebSide containing all the samples I talked about in my blog.

http://www.mathertel.de/ajax/Aspects of AJAX_index.htm An eBook about the AJAX Engine. Here you can find most of the content of the blog and some more hints.

Please contact me via my blog and let me know how you find this work - and what you miss.

AJAX for ASP.NET

2006-01-31T20:34:00.000+01:00

I've got several questions about what .NET version the AJAX Engine is supporting.

The answer is: .NET 2.0

BUT, most of the AJAX programming is done using JavaScript that runs on the client side and the AJAX part on the server is implemented by standard webservices and some people started porting the code to JAVA...

If you know about ASP.NET 1.1 it should be possible for you to port the sources back to ASP.NET 1.1 and I've written a some text about the concepts behind my ideas that may help.

An AJAX based Tree View for the Bible

2006-01-07T23:17:00.000+01:00

I just published another Page displaying a English Bible using an AJAX Tree View Control. It just took me half an hour, including some other housekeepings.

Have a Look at http://www.mathertel.de/AJAXEngine/S03_AJAXControls/BibleTreeView.aspx.

TreeView sample did not run with FireFox - Bug fixed!

2006-01-04T22:28:00.000+01:00

The TreeView sample I posted yesterday did not run with FireFox. - I just did not test it and did not find it in time.

I fixed the bug today and it works now. Changes are in ~/controls/TreeView.js.

Tree View AJAX Control

2006-01-03T22:24:00.000+01:00

The sample page is available at: http://www.mathertel.de/AjaxEngine/S03_AJAXControls/TreeView.aspx.

Hierarchically structured data can be found in various places on this world. File systems, network structures, dependencies, organisation charts, bill of materials etc. are hierarchical by nature or by design or can be viewed to be so.

(I personally think that the reason behind the fact that so many structures are hierarchically organized is that more complex structures are too chaotic to be understood easily.)

Displaying hierarchical data as trees is relatively easy to be implemented and you can find many implementations with ASP.NET Controls on the web. But when it comes to mass data situations (like the content of a file system) it is almost impossible to load the complete tree at. A simple paging approach, that is known from huge table-data doesn't fit for structured data.

Displaying this kind of data of a good place for using the AJAX technology and the architecture of my AJAX controls is also used here. The best solution is to load and open only the root level of the tree when loading the page and to load all sub-levels when the user wants to dig down by clicking a folder. Already loaded sub-levels can stay at the client until the page gets reloaded.

The AJAX engine can be used to solve the server call in the background very easily by using a WebService that can be queried for sub-level data. With JavaScript and the XMLhttp object this data can be requested from the server an transformed into html code to display all the nested items.

1. Defining a contract

The AJAX control, after beeing loaded will use a WebService for retrieving the list of sub-nodes (folders and files) from a given node (the user clicks). A WebService that can be used for this purpose has a very simple interface with only a single method. The parameter is used with a key that uniquely defines a already known folder node and the return value is a structure with the folders and files under that node.

The unique key of a node can be described by a path string and the return value is typed as a XML document:

[WebMethod]
public XmlDocument GetSubNodes(string path);

Every folder and every file must have a name that must be unique among the subnodes of a folder ans we can concatinate these names as we usually do for filesystems to get a overall unique identifying string.

The returned XML has the form:

<folder>
  <folder name="[name of the folder]" title="[some more text]" />
  <file name="[name of a file]" title="[some more text]" />
</folder>

There can be as multiple files and folders in any order.

2. Implementing a WebService

The WebService implementation we need is very simple. I've published a version that loads a XML file and uses this data source.

3. Javascript and HTML: building a tree layout

There are many <table> - based sample implementations for tree structures on the web. I use a very simple approach here that works fine but supports the indenting of subnodes, but no lines in front of the icons that uses <div>-elements. Here is the basic structure of a folder with the container of the subnodes:

<div class="du" name="foldername"><span class="ft">foldertitle</span></div>
<div class="subframe"></div>

The click event is captured at the root level and has to do the following things:

identify the clicked folder object (<div> with class=[do|dc|de|du])
hiding (do) or showing (dc) the container with the subnodes
or starting an AJAX action (du) that loads the subnodes

4. the AJAX action

The context parameter of the only ajax action we need is the node of the folder with the still unkown subnodes.

The prepare function builds the path string for this folder.

The asynchronous call will return the xml document that is passed to the finish method.

In the finish method we transform the returned xml document into the html wee need by using a simple xslt transformation that can be found inline in the file of the page.

All we have to code for that is an AJAX Action:

  // Retrieve the sub-nodes of a given folder.
  ExploreAction: {
    delay: 10,
    queueMultiple: true,

    prepare:
      function(src) { 
        var path = "";
        var root = jcl.FindBehaviourElement(src, TreeViewBehaviour);
        while ((src != null) && (src != root)) {
          if (src.className == "subframe") {
            src = src.previousSibling;
          } else if (src.className == "do") {
            path = "/" + src.name + path;
            src = src.parentNode;
          }
        }
        while (path.substr(0,2) == "//")
          path = path.substr(1);
        return (path);
      },

    call: "proxies.TreeView.GetSubNodes",

    finish:
     function(data, src) {
       jcl.FindBehaviourElement(src, TreeViewBehaviour).ExtendTree(src, data);
     },
    
    onException: proxies.alertException
  }, // FetchAction

That's still a lot of code, so we build a Control to get that coding off from our daily work by implementing a control.

5. the AJAX control

All the coding up to here should be covered by the AJAX Control so the developer only adds this control with the following attributes:

<ajax:TreeView runat="server" title="Cities of USA" service="WebServiceAlias" />

The title attribute is the label shown on the root folder.

The service attribute is the alias name of the web service that serves the data of the tree

The complete implementation can be found in the 2 files that build the AJAX Control and the JavaScript behaviour: TreeView.ascx and TreeView.js that can be found in the controls folder.

An AJAX enabled bible reader

2005-12-29T22:38:00.000+01:00

Handbook

This is a small documentation for the online available Bible Reader at http://www.mathertel.de/AJAXEngine/S03_AJAXControls/BiblePage.aspx.

The reader can be started just by opening a window with the given URL. The page loads completely and starts with one of the available versions (of course) on the first book, first chapter, first verse: "In the beginning...".

You can select one of the server-side installed bibles by using the first select box:

sf_kjv_strongs_rev1b:	A English version of the bible.
en_gb_KJV2000_1:	A more modern English version of the bible.
luther1912:	A German version of the bible.
biblehebr:	a Hebrew version of the bible.

Yes, it's right to left - Does it look right?
I see some differences between FireFox and IE.
Maybe anyone can help on that topic !

In the second select box you can choose one of the available book. Some bibles provide names for the books, others don't and you have to use the given numbers. The New Testament starts with book 40.

In the third select box you can choose the chapter you want to read and in the forth select box you can finally choose the verse.

As you change the values of these select boxes you will see that the select lists will be updated automatically so that only valid entries are available. If you choose a book, the list of chapters will be updated, If you choose a chapter, the list of verses will be updated...

In the big text box below the text of the selected verse will be shown.

It is possible to change the version without changing the selected book, chapter and verse so you can easily switch between German and English or different English versions.

Below the text boxes are 2 buttons that enables the forward and backward navigation cross all book and chapter boundaries in a given version.

You navigate across multiple 5 MByte sized books. Fast !

Technology

The published web page available at http://www.mathertel.de/AJAXEngine/S03_AJAXControls/BiblePage.aspx is already a AJAX application and more than just a small technology driven demo page that shows how to use a specific control or piece of code.

I started working on this application to show how it all works together and to see where we need common functionality and what features we need within the controls.

Cascading Select Elements

The 4 select boxes at the top of the page are dynamically linked together by raising and listening to some page-level data connections. Together they form the cascading 4-level specification of the available verses.

Here, the AJAX Select box control is used together with a AJAX action and some JavaScript code. The chapter select box is defined by

<ajax:Select id="ChapterSelect" runat="server" pageproperty="chapter" style="width: 120px">
</ajax:Select>

and the JavaScript code just below it reacts on changes of the version or the book. The AJAX Action is used to fetch all the Chapters from the server by using the BibleData WebService and the ListChapters method.

<script defer="defer" type="text/javascript">
  var obj = document.getElementById("ChapterSelect");
  obj.GetValue = function(prop, value) {
    if (((prop == "version") || (prop == "book")) && (jcl.DataConnections.GetPropValue(prop) != value)) {
      ajax.Start(this.ChapterAction, this);
    }
  }; // GetValue
  jcl.DataConnections.RegisterConsumer(obj, "*");

  obj.ChapterAction = {
    delay: 10,
    prepare: function(obj) {
      key = jcl.DataConnections.GetPropValue("version")
       + ";" + jcl.DataConnections.GetPropValue("book");
       return (key); },
    call: proxies.BibleData.ListChapters,
    finish: function (value, obj) {
      obj.CreateOptions(value);
      if (obj.selLast == true)
        obj.options[obj.options.length-1].selected = true; 
      obj.selLast = false;
    },
    onException: proxies.alertException
  }; // ChapterAction
</script>

Very similar scripts can be found for the other 2 cascaded select boxes.

Retrieving the Vers Text

To fetch the vers text, another AJAX action, named VersTextAction is used. The 4 properties version, book, chapter and vers are retrieved and passed to the BibleData WebService and the GetVers function. The returned text is then written into the text area.

obj.VersTextAction = {
  delay: 10,
  prepare:
    function(obj) {
      key = jcl.DataConnections.GetPropValue("version")
       + ";" + jcl.DataConnections.GetPropValue("book")
       + ";" + jcl.DataConnections.GetPropValue("chapter")
       + ";" + jcl.DataConnections.GetPropValue("vers");
      return (key);
    }, // prepare
  call:
    proxies.BibleData.GetVers,
  finish:
    function (value, obj) {
      obj.style.direction = ((jcl.DataConnections.GetPropValue("version") == "biblehebr") ? "rtl" : "ltr");
      obj.innerHTML = value;
    },
  onException:
    proxies.alertException
}; // VersTextAction

A very similar AJAX Action is used to look for a Prolog Text that might be describing the current book. The rest of JavaScript programming is for the sequential navigation through the verses, chapters and books.

On the Server a ASP.NET WebService, written in C# with 5 methods is used to deliver all the data that is needed by the Bible Reader Web page. see: http://www.mathertel.de/AJAXEngine/S03_AJAXControls/BibleData.asmx

That's all. All the source you need for this application has only about 15 kByte of text. You might not get any application of this functionality with less coding.

Programming AJAX Web Applications can be easy and without a lot of source code if you choose the right technology and level of programming.

Powerpoint Slides on AJAX

2005-12-20T21:56:00.000+01:00

I had to give a speech at the Karlsruher Software Council about AJAX some days ago.

Now I've posted the Powerpoint slides titled "AJAX – Hype and Reality" on my site at PowerPoint Slides on AJAX

There are really a lot of low level articles on AJAX that explain how to use te xmlhttp object. My summary on that: Have a look at the productiviy of yourself or your programmers and find a useful level of abstraction above the native xmlhttp objects.

Maybe you find the slides useful.

JavaScript Proxies for WebServices extended

2005-12-15T22:12:00.000+01:00

I updated the bits on the AJAX Engine site some days ago. There are some new features I want to let you know:

WebServices with arrays of primitive types (strings, numbers etc) are now supported by the generator of the JavaScript Proxy objects and the client side runtime in ajax.js. Have a look into the inline comments.
There is now a new sitemap available for the whole site. You can find the link on the home page at http://www.mathertel.de on the left side. It's very easy now to discover all the posted source code files.

Moving the server

2005-11-16T00:03:00.000+01:00

Update you favorites ! (and I hope that my AJAX project is part of them)

Thanks to http://www.centron.de I could host the samples live on a beta web site for ASP.NET 2.0 for free, but that time is over soon.

I decided to move my personal domain http://www.mathertel.de/AJAXEnginethat moved to a ASP.NET 2.0 enabled host so I can put both sides together.

If you have saved a link to the AJAX Demo WebSite you should update this link.

You can find the new samples at http://www.mathertel.de/AJAXEngine and the documentations at http://www.mathertel.de/AJAX.

This blog and the rss url will stay here, but I plan to bring the valuable content into a eBook that I started some time ago.

Stay tuned.

Tuning TableData

2005-11-13T20:53:00.000+01:00

After realizing the first working version of TableData I found several things that did not work as expected so I published a better version with some enhancements.

Speed

The first version (still available here) retrieved the row from the WebService one row each time. The time that is needed to update a page full of visible rows was only a second or two when developing on my local system but is about 4-6 second on the real internet. The reason for this slow down is the time a package needs to be transferred from the client to the server and back. You can use the tracert command (tracert www.mathertel.de) line tool to verify this timing. You can see how long an almost empty package needs to be transferred and that is extremely longer than a package that doesn't leave a development machine. Reducing the number of packages is the key and I decided to bundle the Fetch call for all newly visible rows together into a singe call to the server.

FireFox compatibility

After some months of working with both browsers (IE and FireFox) I've got some experience in implementing one source for both browsers - but forgot to test.

I fixed some minor things:

The parentElement attribute of the html dom should not be used. Use parentNode instead.
The firstChild attribute might get a text node in FireFox that is skipped or not existing in IE. Whitespace should not be used between a parent node and the fist child node.
The onscroll event it is not documented but works as expected in FireFox. Great !

Reusability

When trying to reuse the controls on a different project I found that I need more parameters to make them portable. The name (alias) of the service that is used for selecting and fetching the data is now configurable.

Displaying huge tables using AJAX

2005-11-11T22:49:00.000+01:00

There are many implementations available in the ASP.NET framework to display tabular data. Most of them send the content of the table to the client as a part of the page including all the other parts of the page. If it comes to mass data situations the implementations offer a mechanism to navigate through pages containing a smaller set of the records and sending the whole page again and again.

Here comes another approach that offers paging and scrolling even with huge datasets without refreshing the page that uses AJAX calls to a WebService to fetch the data.

If you have followed by posts in this blog or the documentation on the sample web site you can easily identify the AJAX part of the sample. Most of the JavaScript you can see on the client is written to handle all the events and the HTML DOM operations.

In fact it's a 3 steps approach:

When the page loads an empty table that acts as the template is downloaded to the client. No data integration is needed for this pahse to finish.
Then a query is started by passing some parameters to the WebService that selects all the rows that should be displayed and returns a unique ID for each row.
Then every row that is visible is fetched from the server using another WebService call that returns a XML document for each row.

The amount of data that is transferred has some overhead in the case of the first page that is displayed but if you scroll down to the next page by using the scrollbars or the page navigation buttons, only the new row data is fetched from the server - far less than a whole page refresh. It gets better when you scroll back to a region or page that was already displayed because the data is already on the client and can be displayed without requesting the server at all.

Also when you request another set of records by using another sort criteria all the rows that are already known on the client can they can be displayed without fetching them again from the server.

As you can imagine, using this approach it is possible to send huge tables to a client without the need to send all record data immediately.

Give it a try and check out the sample implementation at: http://www.mathertel.de/AjaxEngine/S03_AJAXControls/TableData.aspx.

First select some data using one of the 3 Select buttons. You can now page through the recordset or (by favorite) press the all-button and scroll through the table. You can see the deferred loading of the table rows.

The implementation consists of a WebService, 2 Web Controls and the AJAX Engine that does the asynchronous communication and the caching.

DataTablePager Control

The DataTablePager is the client side controller of the MVC pattern and is an AJAX Control that implements the AJAX action for retrieving the dataset on the client side.

There are some methods available that can be used by additional buttons to load a specific view or to clear the actual data.

Buttons can use these functions to select rows by supplying a filter and a sorting criteria.

The events that are triggered by scrolling the table also use methods of this control to fetch data from the server.

DataTable Control

The DataTablePager is the client side view of the MVC pattern and is responsible for dynamically building up the table that displays the record data fetched from the server formatted by the format given by the template row.

When the page load the template gets saved and when new row data must be shown this template is copied for every row that should be displayed.

Right now there is only a very simple template processing functionality implemented that can only display columns as simple text and the template is constructed on the server by interpreting the cols attribute of the datatable tag.

Every time a row gets visible a fetching the data is initiated by calling the DataTablePager Control's FetchRow Method.

When data comes back from the server the AJAX Action will call the DataTable Control's FillRow method to fill up the corresponding row with the record data.

The TableData WebService

The WebService that is used by the AJAX Actions of the DataTablePager Control is the server side model of the implementation. This WebService must implement the methods defined by the ITableData interface.

To bind all 3 elements together only some lines of coding are needed and the sample page itself, containing the controls and the WebService’s proxy, has only some specific attributes that must be set. – Have a look.

I see still some optimization potential in reducing the number of call to the server by bundling the records that got visible together into a single WebService call. – Stay connected.

CustomValidation AJAX Control Sample

2005-10-13T20:41:00.000+02:00

The ASP.NET Web Forms offer a collection of validation controls out of the box to check the values in the fields of a form. The validation process takes place in 2 situations:

When the form data is sent back to the server a specific server-side functionality of the control or the page is called.
When the user changes the value of a field and leaves the field a specific client-side function is called.

Now, with the help of AJAX and the possibility of asynchronous calls to the server in the background a third kind of validation can be implemented without great effort and combines the power of the server side processing with the good user experience of the immediate verification in the client.

When the user changes the value of a field and leaves the field a specific WebService can check the value.

The implementation is obvious.

1. We use the built-in CustomValidator control to attach a client side function:

<input autocomplete="off" id="EMAIL_IN" runat="server" name="EMAIL" />
<asp:CustomValidator ID="CustomValidator1" runat="server"
  ControlToValidate="EMAIL_IN"
  ErrorMessage="Please enter a valid e-mail address." 
  ClientValidationFunction="validateEMail">*</asp:CustomValidator>

2. The client-side validation function that is used by the control as specified by the ClientValidationFunction attribute always leaves the arguments.isvalid flag set on true (default) to hide any shown error and then start the Ajax action with the source object as parameter.

function validateEMail(source, arguments) {
  ajax.Start(validateAction, source);
} // validateEMail

3. The AJAX action needs to be declared and is based on some implementation details of the client-side validation mechanism:

var validateAction = {
  delay: 0,
  prepare: function (source) {
    // from the Validator Common JavaScript
    return(ValidatorGetValue(source.controltovalidate));
  },
  call: proxies.ValidatorDemo.ValidateEMail,

  finish: function (val, source) {
    // from the Validator Common JavaScript
    source.isvalid = val;
    if (! val)
      Page_IsValid = false;
    ValidatorUpdateDisplay(source);
    ValidationSummaryOnSubmit(null);
    },
  onException: proxies.alertException
} // validateAction

There is nothing data-verification specific here except the link to the WebService we use to validate e-mail addresses so the declaration can be reused for different purpose.

The integration of the Ajax action is a little bit tricky as you can see because the validation process of the built-in validation controls of ASP.NET do not expect any asynchronous processing but wants an immediate decision to be taken and the Validation Summary sometimes does not update correctly.

The WebService itself can do what ever it wants to do. In my sample I use the Dns class to resolve the domain name and check if it exists. That cannot be done by the client and is a sample for the power you have on the server available, but not on the client on its own.

The sample can be found at http://www.mathertel.de/AjaxEngine/S03_AJAXControls/ValidatorDemo.aspx

Using AJAX enabled controls in ASP.NET Forms

2005-10-03T15:54:00.000+02:00

The use of web forms is for many web applications the most important functionality. They rely very much on it because it was implemented by all old browsers they also the modern ones still provide this functionality.

Using AJAX functionalities in your web applications doesn't mean that everything needs to be re-implemented. With the AJAX functionality these applications can easily be extended with controls using asynchronous functionalities in the background without breaking up the existing applications structure:

Validate values immediately on the server after the user exits the field without reloading the form.
Help the user to find the right value by extending a field with a specific lookup function.
Show or hide a field, depending of already entered values.
Fill fields in the form, depending of already entered values.
Fill the OPTIONS of HTML SELECT elements depending of already entered values.

Common to these scenarios is that a pure client-side implementation is often hard to do or impossible because some data is required and this data is not available on the client directly. On the server in contrary, the information is available and is in classical Web Forms used to validate the input of the user before accepting and executing the functionality.

If you integrate AJAX controls into your existing web applications it is possible to make your forms more responsive and give faster feedback and help to the user. The processing of the Web Form can stay as it is by submitting the data of the form to the server and reloading or redirecting the page after the server side processing is done.

On the sample website to this Blog at http://www.mathertel.de/AjaxEngine/Default.aspx you can find some samples that show the usage of AJAX based functionality in regular Web Form applications:

Validator Demo

http://www.mathertel.de/AJAXEngine/S03_AJAXControls/ValidatorDemo.aspx shows how to use a server-side DNS lookup to check if the host part of an email address is known on the web without reloading the whole form.

Bible Reader

http://www.mathertel.de/AJAXEngine/S03_AJAXControls/BiblePage.aspx here you can see beside other things how to populate OPTIONS of a HTML SELECT element dependent of other values without reloading the whole form.

Connecting Controls

2005-09-19T20:55:00.000+02:00

Separating and encapsulating the functionality into components helps to build a reusable framework. But most components do not exist alone but must be linked to other elements.

The classical approach

When using the standard built-in controls of ASP.NET you will use the events that are exposed on buttons, fields and the page and write small methods that response to these events. Inside these event handlers you reference to other objects directly because they are part of the page or control class or by using their id or at runtime unsing a search method.

These handlers are executed by using a submit() of the HTML form element - a post-back situation that should not happen in AJAX applications. We need a solution on the client side of the application in JavaScript.

You can also follow this approach on the client by writing event handlers and attaching them to the native HTML events of the HTML objects.

The drawback of these architectur is that when using complex controls the object that exposes this event might be an inner part of the control without an id or maybe not existing while the page is still loading.

If you want to follow this approach you can use jcl.AttachEvent. This is a method from jcl.js include file that you can use for this purpose and that works across the browser platforms and that allows multiple event registrations..

Even when you know all inner details of the actual control you might not want to use that knowledge because you will give away the chance to extend or re-implement a control without also changing all the implementations on the pages.

The WebPart approach

With Sharepoint and the ASP.NET 2.0 WebPart Framework came another mechanism of connecting components by using a provider-subscription pattern. Components can register themselves for publishing (provider) or consuming (subscription) a specific property-value. Every time when the value of a property changes in a provider all controls that registered a subscription for this property are informed about that.

There are some advantages for this approach:

It works even if the controls that build up a page are not known at compile-time. (Sharepoint)
Multiple controls can easily publish the same property.
Multiple controls can easily consume the same property.
We do not need any browser- or object-specific events.
The IDs of the objects must not be known.

You see that this is a higher level approach that fits better into the problem space of component based pages and portals and it can in addition be combined with the eventing model of the native HTML objects.

The Connection Test Sample

This sample uses 3 kinds of controls implemented with JavaScript Behaviours to show (and test) the implementation and usage of the client side controls connections. There are 3 properties used in this sample (x, y and z) that can be modified by 2 different Controls and that are visualized by a simple bar chart.

See: http://www.mathertel.de/AJAXEngine/S03_AJAXControls/ConnectionsTestPage.aspx

PropInput Control

This control renders a HTML input element that is extended by a JavaScript Behaviour to raises a change of its value to the property that is specified by the "name" attribute.

This control also registers itself as a consumer to display the actual value when changed by another control.

PropHSlider

This control implements is a horizontal moveable rectangle that acts as a slider. It can be used to change a property value that is specified by the "name" attribute in the range from 0 to 100.

This control also registers itself as a consumer to display the actual value when changed by another control.

PropBarChart

This control implements a simple bar chart to display multiple values. The names of the properties are displayed below the bars.

The names of the values can be specified by the "properties" attribute by using a semicolon separated list of names.

The max displayable number can be specified by the "maxvalue" attribute. This value is used as a scale factor for the display.

PropEventLog

This control logs every change of any property and lists the new value on the page.

DataConnections Reference

The names of the properties are always converted to lowercase characters so they should only be compared by after a toLowercase conversion.

DataConnections.RegisterProvider(obj, propName)

An object that provides a property must register itself using this function.

The name of the property set to a '*'-character to register for all existing properties.

DataConnections.RegisterConsumer(obj, propName)

An object that wants to be informed about the values of a property must register itself using this function.

The name of the property can be specified by a star-character to register for any properties that exist on the page.

DataConnections.Raise(propName, propValue)

This function must be called to raise the change of a property. All registered objects for this property get their GetValue method are called immediately.

DataConnections.GetPropValue(propName)

This function can be used to poll the actual value of a property. This eliminates the need for implementing a array of the current values of the properties an multiple controls.

DataConnections.PersistPropValue(propName)

Using this function a property can be persisted into a cookie value and will be raised when the page loads again. This help a lot for surviving page reloads.

The used cookie is not a permanent cookie so the content will be not available after the browser was closed.

control.GetValue(propName, propValue)

This function must be implemented by a control to receive the notification changes.

Anatomy of an AJAX Control

2005-09-16T09:03:00.000+02:00

Writing an AJAX enabled control (here AJAX Control) is as easy as writing another AJAX enabled web applications. The only difference lies in the kind of separating HTML, JavaScript and the clueing stuff like AJAX Actions and Server calls into the right places so that the control can be reused in other places.

If you just want to separate a part of your application so that other members of the team can work on it separately then you can place all the code of the control into the User Control’s *.ascx file.

You should be familiar with the technique of the <ajax:Lookup ... LookUpService="OrteLookup" ... />

What you see here is NOT HTML code but a descriptive declaration of rendering some HTML code here. When using ASP.NET User Controls these attributes do not get automatically rendered as HTML attributes. Instead the ASP.NET framework matches them to properties of the class that builds the control on the server. So any attribute that is used as a parameter must also be defined as a field or property of the control’s class to make the value available on the server.

<%@ Control Language="C#" ... %>
<script runat="server">
  public string lookupservice = "DefaultService.asmx";
  ...
</script>

To make it available on the client the values of these members must then be written out in the HTML code that is generated by this control:

<input ... lookupservice="<%=this.lookupservice %>" ... />

The consequence of this is that the default-values for parameters that are not specified in the source code must be specified in the initialization of the class members and that values assigned to in the JavaScript prototype objects are always overridden.

Writing specific HTML code for a User Control is simply done by writing it down at the end of the *.ascx file. It can be as complex as you like it to be.

Be sure to also add the unique id of the control into the generated HTML code:

id="<%=this.UniqueID %>"

An ASP.NET User control doesn’t automatically create an outer HTML object. It is also possible to generate multiple objects in a row. In this case the JavaScript behaviour is attached to the object that is assigned the unique id.

If you need a reference to another web resource you can use the ResolveUrl method of the Page object:

src="<%=Page.ResolveUrl("~/controls/images/drop.gif") %>"

Programming the Behaviour

The specific JavaScript behaviour that should be used to implement the client-side functionality for a User Control should be implemented in a separate JavaScript include file. This is not strictly necessary but is good for the overall performance because it can be cached in the browser.

I use the same name as the *.ascx file for this control specific include file and place them all into the ~/controls folder.

To attach the behaviour to the html object a small JavaScript fragment is also part of the rendered HTML code:

< script defer="defer" type="text/javascript">
  jcl.LoadBehaviour("<%=this.UniqueID %>", LookUpBehaviour);
</script >

AJAX Actions

The AJAX Action that is used by the Control can be declared as a part of the Behaviour’s prototype object. In the LookUp Control you can find the _fillAction property that is the declaration object of the AJAX Action.

// declare an AJAX action to the lookup service
_fillAction: {
  delay: 100,
  prepare: function(fld) { fld.savevalue = fld.value; return (fld.value); },
  call: null, // is assigned later
  finish: function (val, fld) {
    if (fld.savevalue != fld.value) {
      ajax.Start(fld._fillAction, fld); // again
    } else {
      var dd = fld.CreateDropdown(fld);
      fld.FillDropdown(dd, val);
    } // if
  }, // finish
  onException: proxies.alertException
}, // _fillAction

If you only have one single instance of the Control on the page you will not get into trouble. If there are multiple instances of the Control on the same page these actions definitions will be shared by all controls so you better make a copy of it using the jcl.CloneObject function because they will use different WebServices.

The reference to the WebService should also be set in the init function after the page was loaded because it is not guaranteed whether the WebService proxies are already setup correctly when the behaviour is attached.

this._fillAction = jcl.CloneObject(this._fillAction);
this._fillAction.call = proxies[this.lookupservice].GetPrefixedEntries;

Registering the script includes

Before the HTML text is send to the client all the JavaScript include files that are needed by the control must be registered on the page. This can be done in the OnPreRender method:

protected override void OnPreRender(EventArgs e) {
  base.OnPreRender(e);

  ...

  // register the JavaScripts includes without need for a Form.
  if (!Page.ClientScript.IsClientScriptBlockRegistered(Page.GetType(), "CommonBehaviour")) {
    Page.ClientScript.RegisterClientScriptBlock(Page.GetType(), "CommonBehaviour", String.Empty);
    ((HtmlHead)Page.Header).Controls.Add(new LiteralControl("<script type='text/javascript' src='"
      + Page.ResolveUrl("~/controls/jcl.js")
      + "'><" + "/script>\n"));
  } // if

  if (!Page.ClientScript.IsClientScriptBlockRegistered(this.GetType(), "MyBehaviour")) {
    Page.ClientScript.RegisterClientScriptBlock(this.GetType(), "MyBehaviour", String.Empty);
    ((HtmlHead)Page.Header).Controls.Add(new LiteralControl("<script type='text/javascript' src='"
      + Page.ResolveUrl("~/controls/LookUp.js")
      + "'><" + "/script>\n"));
  } // if
} // OnPreRender

p>All the code fragments can be found in the third part of the samples:

OrteLookUp.aspx is the implementation of the page,

~/controls/LookUp.ascx is the first visible control and

~/controls/LookUp.js is the corresponding JavaScript Behaviour.

AJAX Engine documentation update

2005-09-14T21:30:00.000+02:00

Today I updated the documentation of the AJAX Engine.

See http://www.mathertel.de/AJAX/Aspects%20of%20AJAX_index.htm.

It’s not necessary any more to read the articles from the end to the beginning because they layer upon each other partially.

ATLAS

The AJAX Framework from Microsoft called ATLAS was published yesterday. I am glad to see that Microsoft follows my idea of generating proxies for WebServices.

They use a JSON syntax and not SOAP or WSDL for the communications so it’s not very portable to other server-side platforms.

Using ASP.NET

2005-09-13T21:20:00.000+02:00

When using ASP.NET on the web server some things become easier because it brings a built-in framework for reusing HTML code fragments, building controls and components and managing some useful things around it. I will use some features of the page model, ASP.Net user controls and Web Controls here to make it easy building AJAX Controls.

Together with the JavaScript Behaviours I wrote about some days ago and that are used to build the client side the ASP.NET Controls on the server are a solid basis for building AJAX Controls.

There are good articles on the web that explain how to build this kind of controls and there are a lot of samples too. But there are some tricky things around too to reuse this for building AJAX controls.

User Controls

The very useful functionality of ASP.NET User Controls is the possibility of writing often needed HTML code only once in an *.ascx file and reuse it as often as needed by writing only referencing tags into the ASP.NET pages.

Web Controls

Some things are hard to be done when using User Controls. Especially when the Control is only a framing element for more inner HTML objects User Controls cannot be used. Here some Web Controls, that have to be implemented as special classes, are easier to be implemented so you can find both technologies in the samples.

No Form element

AJAX controls are built for NOT posting back, submitting the changes the user did to the server by using the HTML form element and reloading the whole page. That’s why we want AJAX in our web applications. In contrary, ASP.NET controls are made for exact this kind of client-server interaction and therefore are most of the time placed inside a HTML form element. Because we do not use autopostback functionalities nor do we directly implement some script to call form.submit() we do not get problems with a possible existing HTML form element.

If you plan to extend your existing ASP.NET Web Forms with AJAX Controls – which is one of the scenarios I want to support – you will need this HTML form element. If you build new web pages without using the server side functionality of ASP.NET web forms you can eliminate this HTML form element completely.

The Return key

One thing will disturb users when a form element is present: pressing the or key in an input field is (like F5) reloading the page. All information that came to the page since the time it was loaded and displayed by using some asynchronous communications will be lost too.

Pressing return on input-fields outside a HTML form element normally has no visible effect because the return character will not be added to the value of the HTML input element.

There is a simple trick built into the jcl.js file that can help you to get around this situation. By capturing all keypress events and test if return was pressed, it is possible to cancel the keypress event early and prevent the automatic call of the submit functionality.

To enable this trick for the input fields they just must have an attribute "nosubmit" set to "true". You can add this attribute to the HTML code or add it to the JavaScript behaviour bound element too.

Common JavaScript

The AJAX Controls are using the JavaScript behaviours and therefore need all the common include file "~/controls/jcl.js " and most of them also need a specific include file containing the specific JavaScript behaviour prototype.

Registering Script includes

A very useful server-side functionality of ASP.NET Web Forms is the way how controls can control that a JavaScript include file is needed for a control to work sucessfully. The function "RegisterClientScriptBlock" that is available on the Page object as well as on the new Page.ClientScriptManager object in ASP.NET 2.0 can be used to specify some html code that will be included inside a HTML form element before all other HTML content.

With "IsClientScriptBlockRegistered" it is possible to check if a include file is already registered.

Using such a mechanism is perfect for building AJAX Controls because the web programmer needs not to know about the control specific JavaScript include files that must be included for a Control to work properly. He can just include the AJAX controls at the right place and everything else gets magically done.

Page.RegisterClientScriptBlock("CommonBehaviour",
  "<script type='text/javascript' src='"
  + Page.ResolveUrl("~/controls/jcl.js 
  + "'><" + "/script>\n"));

When having a HTML form element on the page the form element will automatically include all the submitted scripts before all other contained HTML content.

If you want to use ASP.NET version 1.1 you need only include a HTML form element before all other HTML code to get the includes into the page. This doesn't mean that the AJAX Controls must be inside the form element, they also may be positioned after an empty form element.

Registering Script includes without a form element

When using ASP.NET 2.0 you can use a little trick to get the HTML script tags for the include files added to the end of the HTML head element that should be marked with "runat=server".

// register the JavaScripts includes without need for a HTML form.
if (!Page.ClientScript.IsClientScriptBlockRegistered(Page.GetType(), "CommonBehaviour")) {
  Page.ClientScript.RegisterClientScriptBlock(Page.GetType(), "CommonBehaviour", String.Empty);
  Page.Header.Controls.Add(new LiteralControl("<script type='text/javascript' src='"
    + Page.ResolveUrl("~/controls/jcl.js ")
    + "'><" + "/script>\n"));
} // if

Using this trick, it makes no difference whether a HTML form element exists in the page or not.

Samples and Downloads

There are already some samples for AJAX controls posted on the Samples Web Site. I have added a portal page for the project. Just open the [Samples] tab and look into the third part of the samples collections.

You can also download the whole project - as it is. It’s made for ASP.NET 2.0 Beta 2 build but it also works with the August drop.

Caching with AJAX applications

2005-09-06T11:44:00.000+02:00

AJAX applications offer better response times and are faster (or at least seems to be faster) that traditional web applications.

The main reason behind this is the separation of the initial page loading from the loading of additional data and the absence of reloading this page again and again when the data of the page changes.

Building up a page works by using conventional call of a URL using the http-get mechanisms. Calling the server in the background by using asynchronous XMLHttpRequests is the second and often repeated part.

Caching can help to speed up both kinds of server requests and the best results can be bought out by preventing calls to the server.

Caching the initial page download

The page that is downloaded by navigating to the URL can be improved most effectively using the client-side cache features of the web browser. After adding the right http headers the browser will not ask the server for the specified time for new versions of the url-resource and will rely on the bytes that can be found in the client-side cache. Some things must be taken care of to make this working properly.

There is a very useful tool for windows from Eric Lawrence called fiddler available at http://www.fiddlertool.com/. He also wrote a good article on tuning and the http protocol: http://www.fiddlertool.com/Fiddler/help/http/HTTPPerf.mht.

Also http://msdn.microsoft.com/library/default.asp?url=/workshop/author/perf/perftips.asp is worth reading.

The initial page download MUST NOT contain any data or information that changes frequently or must be available to the client very soon after it changes. If any change of this data is initiated by a click or any other action on the client it is possible to force a request in this case even if the cache period has not ended yet. In this case you can live with a long caching period and an immediate change of the page.
The page MUST be designed to be a (almost) static resource from the view of the client.
It however can vary for different users. When delivering personalized versions, the caching proxy servers as well as the caching features of the server must be turned off.
The smaller, the faster.
I do not recommend using huge graphics and many inline style attributes. The Google applications show, that building fast web applications without many graphics is possible.
Use include files for JavaScript and CSS-files.
Include files can be cached too on the client and can also be shared among different pages. It is good to use include files with common functionality or styles. Rarely ore once-only include files slow down the application.
Use only lowercase character in URLs.
It is not obvious to windows users that page.aspx and Page.aspx are two different resources on the web. Even if the server (IIS and ASP.NET) treats these resources as equal, the client will retrieve and store them twice. The fact that makes them different is the kind of writing in the references in HTML tags "src" and "href" attributes. Because I am never sure how a reference is written in other places I prefer using lowercase character only.
Use the right http headers.
For the IE there are the 2 special cache specific attributes pre-check and post-check that should be set correctly so that the IE does NOT even ask for a version but silently uses the version of the resources found in the client cache.

Caching the asynchronous requests

After the page is loaded there are more requests to the server now by using asynchronous calls in the background using the XmlHttpRequest objects.

When calling long running methods on the server for example complex SQL retrievals or expensive calculations is possible to instruct the server to cache the results and returning them without executing the same methods multiple times.

In ASP.NET you can use the CacheDuration property on the WebMethod attribute to specify the number of seconds the result may stay in the web server cache.

[WebMethod(CacheDuration=60)]

A simple sample on this can be found in the article at: http://support.microsoft.com/default.aspx?scid=kb;en-us;318299

The advantage in this approach is that all clients share the same cache and if there are multiple clients requesting the same service you might get very good response times.

It’s also possible to cache on the client. An approach that leads to less traffic on the net because repeating the same calls can be prevented. Http headers do not help in these situations because the request is not an http-get request and there is always a payload in the http body. Caching must therefore be done by some scripting on the client.

The caching feature in the JavaScript WebService proxy implementation can be enabled by calling the proxies.EnableCache method and passing the function that should further use caching. I added a button to the CalcFactorsAJAX.htm sample to how to enable show this:

proxies.EnableCache(proxies.CalcService.CalcPrimeFactors)

Also the TableData.aspx sample uses caching to prevent retrieving the same records multiple times.

By calling this method a JavaScript object is added that stored all results and is used to prevent a call to the server if an entry for the parameter already exists inside this object.

This is not a perfect solution, but it works under the following circumstances:

The parameter must be a string or number that can be used for indexing the properties of a JavaScript object.
The cache doesn’t clear itself. It can be cleared by calling EnableCache once again.
Only methods with a single parameter are supported.

Caching works good into AJAX applications and speeds up by preventing calculations, downloads and webserver calls.

Project Site Update

2005-09-01T18:49:00.000+02:00

This was a long week, not writing text but code. I updated the AJAX Aspects project side http://www.mathertel.de/AJAXEngine/ and I hope you find it more useful. It got more structure and there is now a good place to start the next steps.

I decided to clarify the conditions for using this work and added a statement and link to the Creative Commons Attribution 2.0 Germany License. Now it’s clear hat anyone can use it also for commercial projects. Please list my name in your license conditions.
I separated the pre-AJAX samples (part 1) from the AJAX samples (part 2). Old links might not work any more.
The third part of the project is building reusable AJAX components – AJAX Controls. Some samples are already on the side so if you are curious go and find them.
I added a "Impressum" and you can find my E-Mail address in there more easily. It’s a gif file so spiders do not reach me too easily.

I hope you like it :-)

JavaScript Behaviours

2005-08-22T23:42:00.000+02:00

This technique has nothing (not yet) to do with AJAX because it is a general usable implementation for reusing JavaScript code for components. Also, this technique has also nothing to do with ASP.NET because it only uses the client-side (browser) available HTML objects and JavaScript. It will be the client side functionality for the upcoming AJAX controls and it fits perfectly into a server-side HTML controls framework that enables also the reusing of HTML code fragments.

General

HTML pages without any more than HTML offer only a limited functionality and allow only displaying information and filling out forms. As a result HTML pages are often extended by using JavaScript for handling input validation, reacting on clicks or bringing optical effects.

But when it comes to reuse once-written functionalities there is no built-in concept to HTML and JavaScript except the flat programming model of include files. Copying sourcecode around is the often used response to this weakness and leads to unsupportable huge web sites often too.

Proprietary behaviours

Both most used browsers, Internet Explorer from Microsoft and the Mozilla/Firefox from the Mozilla foundation, have both their own incompatible way to allow reusing JavaScript functions and HTML on a component level.

Common to both solutions is the big advantage over global script include files that the functionality is bound and accessible through a specific HTML object, can be bound to multiple objects and support specific methods, attributes and event handlers.

Lightweight, compatible behaviours

Building a cross-browser functionality that is very similar to the built-in behaviours of the browsers is not very hard to do.

It basically consists of defining new properties, specific methods and event handlers by building a JavaScript prototype object for each behaviour. Also a common binding functionality is needed that attaches these definitions to a HTML object after the page is loaded. Script include files can be used to bring the prototype objects into the pages.

A simple example

This is the HTML object

<div id="TimerSample" style="...">click here</div>

Here is a simple behaviour that is handling the onclick event and brings in a new update method that is changing the content of the bound HTML object:

var TimerSampleBehaviour = {
  onclick: function (evt) {
    evt = evt ||window.event; // get a compatible event object
    evt.srcElement.update();
  }, // onclick

  update: function() {
    var d = new Date();
    this.innerText = d.getHours() + ':' + d.getMinutes() + ':' + d.getSeconds();
  } // update

} // TimerSampleBehaviour

The behaviour functionality must be bound to the HTML object by calling one method only:

LoadBehaviour(document.getElementById("TimerSample"), TimerSampleBehaviour);

The "magic" work behind the LoadBehaviour() method is to loop though all elements of the given JavaScript object and assigning each of them to the HTML object.:

Methods. Starting with "on" are assumed to be event handlers and are attached using the browser specific methods for attaching events. Only the bubbling phase of the event is used because it is implemented by both browsers.
Other methods are just bound to the HTML object as function objects.
All the other objects are assigned if there is not already an assigned property existing on the HTML object. These objects are shared for all HTML objects that are bound to the same behaviour.

We might expect more functionality from behaviours but this is a set of functionalities that are available in all the supported browsers.

This simple sample can be found on the sample website:

http://www.mathertel.de/AJAXEngine/ in Samples Part 2.

The relevant code can be found in the html page itself and in the include file cb.js.

Writing event handlers

Event handlers use a naming convention to be distinguished from object specific methods by starting with "on". The name of the function should always be lowercase and the function must have a single parameter holding the event object.

Because the IE is not passing the event object through the parameter of an event method we always need a first line to get a compatible event object:

evt = evt || window.event; // get a compatible event object

The clicked HTML object is available by using the srcElement property of the event object.

This is not a native property of Mozilla/Firefox but is made available using a specific patch that is also included – beside other patches – in the common include file cb.js.

I think that it’s a good idea not to implement much in these handlers but to call another method soon because the event handlers always expect an event object and therefore are not reusable for being called from other events or methods.

Writing methods

Writing a method for a behaviour is as simple as writing compatible JavaScript.

Properties or attributes as well as other methods of the bound HTML object are accessible by using the "this" object reference to the HTML object. Never call any method of the prototype object directly, they all are also available through "this".

To make it easy to write compatible JavaScript methods there are some extensions implemented in the common include file cb.js. Mozilla/Firefox has a very powerful extensibility concept that allows easily to define new properties to built-in objects and to control their usage. IE is far behind this point so I use this extensibility to bring IE specific properties to the Mozilla/Firefox platform. Details can be found in the common include file cb.js inline comments.

Defining default values

New properties on the behaviour objects need not to be defined; they just can be used – but always through "this". The properties that are used as parameters to define a aspect of the functionality can be assigned default values in 2 ways:

An attribute can be set on the HTML object
A property on the JavaScript prototype can be set to an initial value and is used if no attribute is already defined on the HTML object.

When defining complex objects (arrays, structures) inside the JavaScript prototype you have to pay attention to the fact that these objects are shared among all HTML objects using this prototype. If individual complex objects are needed it is better to create and assign them in the "init" method.

The init method

A method named "init" can be defined in the JavaScript prototypes to implement special needs after the methods, event handlers and properties are bound to the HTML object. This method is automatically called by the LoadBehaviour method.

When the "init" method is called it is not guaranteed that the whole page is already loaded and that all other behaviours are bound to their HTML objects. If you need this point in time you have to attach a special handler to the onload event of the page.

Links

The Mozilla/Firefox behaviours: http://www.mozilla.org/projects/xbl/xbl.html

The IE behaviours: http://msdn.microsoft.com/workshop/components/htc/reference/htcref.asp

Search for behaviours using Google: http://www.google.com/search?q=htc+filetype%3Ahtc

Application Aspects

2005-08-21T13:46:00.000+02:00

The examples on AJAX I’ve published up to now, had to point out special aspects of the technical design and the implementation. They correspond to the "Bottom UP" method and are about the base components Javascript, XMLHTTP, XML and the asynchronous processing - the aspects That giva AJAX its name.

However, it is not the goal to play some technological games but to realize, improved or modernized a complete application with the assistance of the AJAX engine. The use of AJAX technologies fortunately does not need any principle proceeding at the level of the application but starts at the level of components.

Integration of AJAX components

In some cases we can integrated a functionality which is based on AJAX into an existing web application to better solve the problem of a component.

The LookUp example can be used e.g. in conventional web form and the background validating of the content of a HTML form can be guide the user before a regular positing of the form data.

The amount of JavaScript code that has to be loaded on the client is only about 18 kByte for the AJAX engine and the additional code for handling the selection list not very large.

It helps however to save a multiple this size since the data portion does not have to be sent completely to the client and the multiple reloading of the pages saves several times. AJAX based components particularly develop their largest advantages and it is importantly to have easy integrable components.

AJAX controls

When building new pages it is again a big advantage if the realization does not have to be made on each individual page on a very much detailed level. Here we prefer pre-fabricated components side by side with regular HTML objects to build up the final page.

To reach a high percentage of reusability those components are realized outside of the individual pages and are parameterized for their concrete usage.

HTML is used for the description of the appearance of the controls and JavaScript for the implementation of the behaviour. The binding of Javascript methods to the HTML objects is offerend by the Internet Explorer (*.htc) and by the Mozilla/Firefox (*.xbl) however in very different implementations that would lead into a double implementation. I use therefore a simple but compatible binding.

ASP.NET and AJAX controls

My choice to realize a collection of AJAX capable control falls on ASP.NET and the built-in user controls. These components are easy to implement and adapt. They offer already enough possibilities compared with Web Controls that must be implemented as classes. In addition to ASP.NET 1.1 they can also be compiled completely with ASP.NET 2,0

Building a complete new framework is not my intention because there are already some very useful frameworks that permit building component-based web applications.

Because the controls to be implemented are substantially based in HTML and JavaScript they do not really use the ASP.NET functionalities available on the server. Only building up the HTML code of a page from components will needed and this can also to be done by other tag libraries of other environments.

The advantage of ASP.NET is beside that is the simple realization of Web services.

Model View Controller (MVC) Pattern

2005-08-11T22:10:00.000+02:00

Thinking about the structure and the layering of the components of solutions is important for software architects. It’s about getting the right distance to a concrete implementation, detecting the principles and unnecessary deviations.

Sometimes those thoughts exceed this range and lead into almost religious discussions about holy principles.

Discussing the Model-View Controller (MVC) is one of those topics that describes the distribution of objects and functionalities of a application with a user interface on a high level. There are books about I and a also the material on the web is very detailed.

Because AJAX style applications is for many developers a new kind of modeling web applications I have collected some of my thought on this topic.

Here I want to look and analyze the existing AJAX Engine and not build a ideal optimal AJAX architecture.

Definition of MVC

There are many different definitions for the Model-View-Controller Pattern (google it). I stay with the short one that can actually be found at Wikipedia: http://en.wikipedia.org/wiki/Model-view-controller

Model: This is the domain-specific representation of the information (data and methods) on which the application operates.
View: This renders the model into a form suitable for interaction, typically a user interface element.
Controller: This responds to events, typically user actions, and invokes changes on the model or view as appropriate.

Model

The Model part of the architecture all is relatively easy to discover in the WebServices. Here all functional aspects should be discoverable. There are of course also functional aspects in the User Interface but this code is implementing a more comfortable way of interaction and handles topics of the presentation.

Based of the role this code takes over in the whole architecture some typical aspects very similar to the SOA architecture of the model can be identified. Here some keywords:

Independent of HTML objects
No culture or language specific implementations
Manipulating and storing data
Stateless
Checking and securing of the parameters of the webmethods.
Reliable algorithms and functionalities

View

The View part can be localized in the realization of the User Interface by using HTML objects and some supplement JavaScript methods.

The base functionality of the HTML objects like editing values in input fields is covering a lot but also a lot of the Javascript implementation in the pages of my samples for example the LookUp List and displaying graphics is part of the view.

UI Events
Active elements like input fields
Layout elements and decorative additions
Converting of numbers and date formats to strings
Methods to support the working

Controller

But where is the Controller part in a AJAX application and how does it work ?

A simple answer is obvious: The AJAX Engine. Beside the WebService and the HTML there are only the script include files left to implement this part. The proxy methods for the webservices can be defined as part of the network infrastructure.

Page Controller

When comparing the traditional ASP.NET Web Forms with the MVC pattern the page-controller term is used very often. When comparing the 2 most used approaches ASP.NET and Struts you can easily detect that the server side implementation only covers the collaboration of the objects of a single page.

The transitions between the pages are not really supported with a structure by ASP.NET 1.1. Hyperlinks or Redirect statements are used on the server and some problems have to be solved for transferring information from one page to the next one. With ASP.NET 2.0 it is possible to have 2 pages in memory at once and transferring data is easier to implement but this is no solution for controlling the global flow of a web application.

Struts mixes up both aspects what may end in complex struts-config.xml files.

Both approaches for realizing web applications are described and compared regarding the MVC pattern in http://msdn.microsoft.com/library/en-us/dnaspp/html/ASPNet-ASPNet-J2EE-Struts.asp as well as in http://struts.apache.org/userGuide/building_controller.html.

When realizing an AJAX application the controller is shifted to the client and is implemented in JavaScript. Like with ASP.NET is can control only the activities of the one loaded page because all local information is lost when navigation to another page and a new UI and controller is built up. This is the reason why some AJAX applications have only one active URL using a complex page or framesets.

I have to compare this situation with the 2-tier application architecture of the 90’s. Here the controller also was implemented on the (fat) client and the server added data and methods (SQL connections and stored procedures).

Extensions to the proxy generator

2005-07-30T17:54:00.000+02:00

With Version 2.0 there is now more support for different datatypes.

Simple data types

Up to now only those methods where supported that where converting of the parameters and result values was not necessary. This applies to strings and numbers.

Now the data types defined on the server and the WSDL are passed to the client so that the data types can be converted using JavaScript at runtime.

In the generated proxy code, the listing of the names of the parameters is now extended by an optional specification of the data type. Without this the values are treated as strings.

proxies.CalcService.AddDouble.params = ["number1:float","number2:float"];
proxies.CalcService.AddDouble.rtype = ["AddDoubleResult:float"];

In the HTML object model, the JavaScript data types are not well supported. The values that is displayed inside an input field is always a string, even if it’s containing only digits. For this all the parameters when calling the proxy are also accepted as JavaScript strings and converted if possible to the right types.

XML data

Passing XML documents was implemented to make it possible to pass complex data. In the browser clients the XMLDocument Object from Microsoft or Firefox and on the server the XmlDocument class can be used.

A Method has to be is declared in C# like this:

[WebMethod()]
public XmlDocument Calc(XmlDocument xDoc) {
...
return (xDoc);
} // Calc

The proxy functions also accept the XML document as a string type. In this case, the contents of the passed string is passed directly to the server any must for this reason contain a valid XML document without the declarations any without any “XML processing Instructions" <? ... ?>.

With this data type it is possible to pass complex data from a HTML form directly to the server an there is no need to define a method with many parameters. If the form is extended with new fields it will not be necessary to give a new signature to the WebService.

The disadvantage of this approach is that the content of the XML document cannot be validated by the WebService infrastructure because there is no schema for this part of the conversation available.

Supported Datatypes
XML data type	Alias in the proxy	JavaScript data taype
string	string / null	String
int, unsignedInt, short, unsignedShort, unsignedLong,s:long	int	Number, (parseInt)
double, float	float	Number, (parseFloat)
dateTime'	date	Date
boolean	bool	Boolean
In Mozilla / Firefox: XMLDocument Im Internet Explorer: ActiveXObject("Microsoft.XMLDOM") ActiveXObject("MSXML2.DOMDocument")	x	System.Xml.XmlDocument

Sample for AJAX Forms

2005-07-28T22:24:00.000+02:00

This sample implements the processing of data of a form using the AJAX engine and the AJAX Forms.

AJAX also brings some advantages to this kind of application on the validation and calculation of formular data. Instead of "sending" the data and retrieving new to be displayed HTML an asynchronous communication only transfers the data part of the form using XML documents.

The supplementing functions necessary for the handling of AJAX Forms it is necessary to include the ajaxforms.js scripts in the HEADER of the page.

<script type="text/javascript" src="ajaxForms.js"></script>

The connection to the corresponding WebService is done by using the proxy generator:

<script type="text/javascript" src="GetJavaScriptProxy.aspx?service=_Kreditcalc.asmx"></script>

In this example the validation of the input values and the calculation of the new values are together implemented in the same method. The communication of the values between the client and the server uses the XML format defined by ajaxForms.js module. The two functions ajaxForms.getData and ajaxForms.setData that implement the transfer of the data from the XML format to the HTML of objects therefore can be used directly in the setup of the actions.

Exceptions

The function ajaxForms.processException can be used to handle and display the exceptions that occur within validating the passed data.

If a wrong or missing value is detected inside the passed form data the server should throw an ArgumentException using the name of the element as the name of the wrong parameter.

This name is then passed to the client using an exception return package.

ProcessException then recognizes that an ArgumentException was thrown and shows the error text beside the input field. To show these texts, a SPAN element is used for each field inside the form:

<span class="AJAXFORMEXCEPTION" name="LOAN"></span>

The Form

The layout of the form and the data together with the format of the XML document is specified by the HTML code of the page. The DIV element with id frm (having a green border) is used as a container for all fields of the form. Inside this object you can find the INPUT elements like:

<input id="loan" name="LOAN" value="100000">
  ...
<input name="MONTHLYREPAY" disabled="disabled">

The Actions

The first functionality on the server implements the calculation a simple credit case. On the left side of the form some values like the loan amount and the rates can be modified by the user. These values are used to calculate the monthly payment, the duration of the credit and the totals of payment that are displayed on the right side of the form.

For that purpose all the data of the form is send over the network to the server as a XML document as well as the result of the calculation.

The first action uses the functions getData und setData from ajaxForms.js and needs no further programming.

// declare an AJAX action
var action1 = {
  delay: 200,
  prepare: ajaxForms.getData,
  call: proxies.KreditCalc.Calc,
  finish: ajaxForms.setData,
  onException: ajaxForms.processException
} // action1

The second implemented method on the server gets the same XML document information as the first method but returns a XML Document containing the monthly balance of the credit.

The code on the client is the responsible for displaying the chart by using the special local implemented method displayAmortization. Here the XML document passed back from the server is transformed into a HTML document fragment by using a XSLT transformation on the client. This transformation uses a lot of small blue and red images that are sized and positioned as needed to make the chart look like it should.

Because the transformation is done on the client only about 23% of the necessary HTML code is transferred over the network. The XSTL is retrieved only once and is cached on the client.

var action2 = {
  name: "Amortization",
  delay: 800,
  prepare: ajaxForms.getData,
  call: proxies.KreditCalc.Amortization,
  finish: displayAmortization,
  onException: proxies.alertException
} // action2

Starting the actions

To start the asynchronous actions again the onkey event is used. In this sample 2 actions are started by one event. Because both actions have a delay time specified they will stay in the queue and will be removed abd started again when another key is pressed before the delay time is over.

The second parameter on starting the actions is used to reference the AJAX form.

onkeyup="ajax.Start(action1, 'frm');ajax.Start(action2, 'frm')"

A lookup example for city names

2005-07-27T20:09:00.000+02:00

In example of implementing an AJAX action you can see how to load and display data fragments from a huge dataset on the server.

On the server, there is a big list of German towns and cities in the file orte.txt. If you would include this information into the page as a list of OPTION elements for a SELECT element you would have to download about 400.000 bytes of additional HTML code – too much. Instead a simple INPUT field is combined with the possibility to search in this dataset.

The WebService that implements this lookup functionality can be found in OrteLookUp.asmx and, again, has no AJAX specific implementations. The method gets one parameter passed that contains the first characters of a possible name of a city and returns up to 12 found entries of the list back to the client.

The connection to this WebService is done by using the proxy generator:

<script type="text/javascript" src="GetJavaScriptProxy.aspx?service=OrteLookup.asmx"></script>

This lookup method must be called in several situations: The code on the client that display the list and the completion of the current entered text is somewhat complex and most of the JavaScript of this page is about that. The call ajax.Start(LookupAction) that can be found several times starts the action.

The action itself is implemented very compact in one place and you can see that a not a lot of coding is necessary because the AJAX engine handles a lot.

var LookupAction = {
  delay: 100,
  prepare: function() { return (document.getElementById("inputField").value); },
  call: proxies.OrteLookup.OrteStartWith,
  finish: function (val) {
    var fld = document.getElementById("inputField");
    var dd = createDropdown(fld);
    FillDropdown(dd, val);
    if (isIE)
      NextDropdownEntry(fld);
  },
  onException: proxies.alertException
} // LookupAction

Looking at this script you can again see the actual flow of the action and there is no need to implement several JavaScript methods outside of the definition.

AJAX Form Services

2005-07-23T14:16:00.000+02:00

The implementation of the AJAX Form Services, that allows an efficient implementation of forms can be found in the JavaScript include file ajaxForms.js.

Again, only one global object named ajaxForms is defined to minimize possible name conflicts. Attached to this object the following methods are available.

data = ajaxForms.getData(obj)

This method searches all INPUT, TEXTAREA and SELECT elements that are contained inside the passed object and uses their values to build up the elements of a XML document.

The obj parameter can be passed using the id of a formular or as a reference to a HTML Object.

This result of this method is a XmlDocument object.

ajaxForms.setData(obj, data)

This method transfers all values from data into the corresponding INPUT, TEXTAREA and SELECT elements of the HTML form. All HTML elements that are part of the form but have no value in data will be cleared or unchecked.

The obj parameter can be passed using the id of a formular or as a reference to a HTML Object.

The data parameter can be passed as a XML text of a XmlDocument object.

This method also calls clearErrors at the end (see below).

ajaxForms.clearData(obj)

All HTML INPUT, TEXTAREA and SELECT elements that are part of the form are cleared or unchecked.

The data parameter can be passed as a XML text of a XmlDocument object.

ajaxForms.resetData(obj)

All HTML INPUT, TEXTAREA and SELECT elements that are part of the form get their initial value that is coded inside the

The obj parameter can be passed using the id of a formular or as a reference to a HTML Object.

ajaxForms.processException(ex)

AjaxForms implements a mechanism to display exceptions that are thrown by the server nearby the fields that causes them. If exceptions are handled by ajaxForms.processException() all ArgumentException are detected.

To enable the developer how the exception text is shown SPAN elements tagged with the css-class AJAXFORMEXCEPTION can be defined inside the form. The text of the exception is then inserted into this Element and can be formatted by using a CSS rule.

<span class="AJAXFORMEXCEPTION" name="LOANVALUE"></span>

ajaxForms.clearErrors()

This method clears all exception texts inside the form.

AJAX and Forms

2005-07-21T20:57:00.000+02:00

The good old HTML form element is used by many web pages for the communication of the data from forms. This mechanism was developed to work without any JavaScript or XML and long before AJAX.

It’s a typical scenario in web applications that they have some more or less static forms with input fields for displaying and editing data values. Therefore a concept to handle form situations is also needed in a AJAX engine.

This part is about the programming we need on the client. It’s implemented in JavaScript and uses intensively XML documents. Some words about the extensions in the Proxy Generator as well as the implementation on the server will follow. Some samples can already be found on the samples WebSite.

Classical approach and drawbacks

The mechanism behind form element works since the beginnings of HTML to send the data that is entered or changed by the user back to the WebServer. The format used by these postings has nothing in common with XML but uses for in many cases a URL like format defined by the mime type application/x-www.form-urlencoded. With the upcoming XHTML 2.0 definition also a XML Format and some more advanced form functionalities will be available. But all these good news are not supported by the wide spread browsers available today.

A direct access to the data inside a HTML Form in a whole does not exist in the browser nor in JavaScript. But of course the individual elements can be accessed one by one. The values that are shown to the user are normally included inside the HTML code that is sent from the server to the client. Collecting the values and sending them back to the server is hard coded to the submit action of the form that normally downloads new HTML Code and displays them in the window,

It’s obvious that this approach doesn’t fit into the processing of AJAX. The graphical elements of the form and the data is not separated properly.

Using Form Data

One way to realize an access to the data in a HTML form for AJAX applications is to use JavaScript. The include file ajaxForms.js was written to enable the developer to handle this effectively and without using long scripts in every form but to help with a collection of methods.

The goal of this approach is to distinguish between the data of the form represented as a XML document and the HTML elements that are used to display and edit the data.

To define a form on a HTML page you need a HTML Element that contains all the form elements. This encapsulating element can be a DIV tag.

All the input fields, checkboxes, textareas and select objects with a name that are inside this HTML element are considered holding data in the appropriate object properties. This data is the assembled into a XML document with a data root element by using the names of the HTML elements as the names of the inner tags.

This HTML code ...

<div id="frm" style="margin: 2px; padding: 2px; border: solid 1px green"
  <p>F1: <input name="F1" value="one by one"></p>
  <p>F2: <input type="checkbox" name="F2"></p>
  <p>T1: <textarea name="T1" style="width: 400px; height: 80px">some
text
lines</textarea>
  <p>S1: <SELECT name="S1">
    <option value="10">ten</option>
    <option value="11">eleven</option>
    <option value="12" selected="selected">twelve</option>
    <option value="13">thirteen</option>
  </SELECT>
</div>

... corresponds to this XML document:

<data>
  <F1>one by one</F1>
  <F2>false</F2>
  <T1>some
text
lines</T1>
  <S1>12</S1>
</data>

The data of a form is now available as a single value and therefore fits well into the existing functionalities of the AJAX engine.

In AJAX applications it is a typical that the same HTML Form is reused several times before getting and displaying new HTML code from the server so we also need methods for the reverse data flow that puts the data of an XML document back into the HTML form.

More Options for AJAX Actions

2005-07-18T21:53:00.000+02:00

Since the first publication I have implemented some changes and additions in the AJAX engine and the framework for WebServices.

ajax.Start(action1, option)

prepare(option) / finish(data, option), onExeption(ex, option)

When starting an AJAX action the only options that could be specified where those that are part of the JavaScript object describing the action. These options are the same for all executions of this action. With this addition it is now possible to define an option for a specific execution.

The ajax.Start Method now has a second parameter. This value is stored into the queue of the AJAX engine together with the fist parameter specifying the action.

When the prepare and finish methods are executed as well on handling en exception, this value is passed as an additional parameter. By using this value it is possible to store a context of an action. That may be for example a HTML object that started the action. Because all methods have access to it, it is now possible to use the same action definition for multiple fields, forms or other situations. Without this parameter it was necessary to implement the direct access to the HTML objects inside the prepare and finish methods.

proxies.cancel()

Calling this method will close the actual connection to the saver by calling the abort method of the xmlhttp object before the result is returned from the server.

This is only possible on asynchronous calls.

proxies.alertResult()

This method makes it easy to watch the communication of the return value of a server call. But the situation is similar to the Heisenberg uncertainty principle: If you watch the package you cannot see the effect anymore because the data from the server is shown to the user but is not passed to the finish method. Also the timing situation is ruined because an alert box is used.

This option can be activated by assigning the alertResult method to the otherwise internally used corefunc property.

proxies.service.method.corefunc = proxies.alertResult;

Even if it breaks, it was necessary from time to time to see the result of a call so this option remains in the client-side WebService framework.

Tip:

It is not well known that the Microsoft Internet Explorer (IE) allows to copy the content of an alert box into the clipboard by using Ctrl+C.

ajax.Cancel()

This method cancels the execution of the currently running action. If a timeout value is specified in the action options this method is called automatically.

ajax.CancelAll()

This method cancels the execution of the currently running and all the pending actions.

The AJAX prime factors sample

2005-07-16T14:19:00.000+02:00

The first sample that shows how to use the AJAX engine is in the files CalcFactorsAJAX.htm (Client) and CalcService.asmx (Server). With this sample the principle steps can be analyzed easily.

The connection to the already known WebService is done by using the proxy generator:

<script type="text/javascript" src="GetJavaScriptProxy.aspx?service=CalcService.asmx"></script>

The HTML code contains 2 input elements that are used for the communication with the user.

The import element with the id inputField is editable and used to enter a number that should be split into the prime factors. The event onkeyup was chosen for triggering the AJAX action.

This event is not only triggered by entering characters but by the special keys like backspace, delete or Ctrl+C for pasting a new value.

With IE, there is also the event onpropertychange available that suits better our needs here but the FireFox browser doesn’t implement this and there is no standard event defined for being triggered immediately on any value changes.

The field with id outputField is deactivated and is used to show the calculated prime factors.

...
  <td><input id="inputField" onkeyup="ajax.Start(action1)"></td>
...
  <td><input id="outputField" size="60" disabled="disabled"></td>
...

The AJAX action is declared inside the JavaScript block and there is no other programming necessary except this.

You can see within the methods prepare and finish how to exchange the values with HTML Elements.

The call method is setup by linking to the local method of the generated proxy and exceptions are displayed by using a simple alert box.

The delay parameter is set to 200 msec. This time was chosen after some empirical timing measurements (using myself) and was found being appropriate. When one of the testing people entered a number this time wasn’t exceeded between entering the digits and the action was indeed executed at the end of entering the whole number.

If the action was stared already by entering a digit and when another digit was entered before the delay time was over then the first action was removed from the queue, the second identical action was entered into the queue and the timer was started again.

// declare an AJAX action
var action1 = {
  delay: 200,
  prepare: function() { return (document.getElementById("inputField").value); },
  call: proxies.CalcService.CalcPrimeFactors,
  finish: function (p) { document.getElementById("outputField").value = p; },
  onException: proxies.alertException
} // action1

Looking at this script you can imagine the actual flow of the action. This is a big advantage for everyone that needs to analyze, extend or fix a broken implementation, because all the functionality is not spread over the source code into several methods, callback functions and timer events but kept together in this JavaScript object.

You can find all the samples on http://www.mathertel.de/AJAXEngine/.

Handling Exceptions

2005-07-11T23:18:00.000+02:00

Also in AJAX architectures failures in the communication and in the execution may raise errors. Fortunately when using a WebServices based framework these cases are also defines in the SOAP communication protocol.

The answer to a call to a WebService in the SOAP format will under normal conditions return the result of the method:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <CalcPrimeFactorsResponse xmlns="http://www.mathertel.de/CalcFactorsService/">
      <CalcPrimeFactorsResult>2 2</CalcPrimeFactorsResult>
    </CalcPrimeFactorsResponse>
  </soap:Body>
</soap:Envelope>

In the case of an error the information about the failure of the server-side execution will be passed back to the client.

In the simplest case this information is shown to the user but also other reactions may be appropriate like reloading the whole page.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <soap:Fault>
    <faultcode>soap:Server</faultcode>
    <faultstring>Server was unable to process request.
---> Input string was not in a correct format.</faultstring>
    <detail />
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

The client-side implementation allows the handling of the exceptions that occur at the level of the WebService proxies an on the level of the AJAX Actions.

In both cases there is an onException event available and a specialized method handling these exceptions can be plugged in. This method gets passed the thrown exception as a parameter and can organize the further functionality of the page.

There is usable method defined in ajax.js that can be used for showing exceptions:

proxies.alertException(ex):

This method shows the exception object in a readable format using an alert box. This method can be used in proxies.service.method.onException as well as in action.onException.