Implementing an Ajax Live Form with NetAdvantage WebClient Controls

This article teaches you how to implement the Live Form Ajax pattern using NetAdvantage web client controls.

The Live Form pattern is an approach to building web forms that does not require the user to make an explicit submission to the server to make "something happen". The page created for this article, allows users to discover editable parts of the page, edit the content and enjoy automatic persistence.

Take a Look

Some screen shots are in order to help explain what is going on. First, a user will encounter a page that at first glance seems to be a normal display page.

However as the user begins to interact with the content the page begins to respond to user actions. When the user hovers the mouse over the title element, the border changes color to indicate that this portion of the page is editable.

At this point editing the content is as simple as clicking on the editable region. When the text is clicked, the UI updates further to change the border once again giving a clue that you have entered an edit mode.

Once focus is left from the control a request is made to the server to process the change. While the change is in progress the UI is updated again to signify that there are pending changes.

Finally once a response is received from the server, the UI is updated one last time to return the page to its original visual state with the latest data.

From here you may refresh the page or even open the page in a new browser to verify the changes are persisted.

The same pattern is used to make the Publish Date editable. Here is a screen shot of what the editing experience looks like when setting a new date.

The Illusion of Persistence

One of the main features of this solution the fact that the page persists the data without explicit submission. In an attempt to side-step the many peripheral issues surrounding data layers and other persistence mechanisms, this sample uses the BookRepsitory’s persistence features.

The illusion of saving data is achieved by maintaining state in an object loaded into an ASP.NET cache entry. For more information read about the BookRepository: The Mock Data Repository for Testing and Demos and The Illusion of Persistence: Saving Test Data.

The Title Editor

Now that you have context for the project, the first step is to create the title editor. Between the page’s FORM tags enter the following markup:

<asp:ScriptManager EnablePageMethods="true" runat="server" />

<input type="hidden" id="bookID" value="<%= this.book.ID.ToString() %>" />

<div><igtxt:WebTextEdit 

    ID="txtTitle" 

    onfocus="txtTitle_Focus();"

    onblur="txtTitle_Blur();"

    onclick="txtTitle_Click();"

    CssClass="liveInput big"

    Width="800" 

    runat="server" /></div>

What you see on this page is:

• ScriptManager: The ScriptManager is a usual suspect for doing just about anything Ajax. Note that the property enablePageMethods is set to "true". This is required as so that ASP.NET AJAX will create proxy functions for methods in the codebehind marked with the WebMethod attribute.
• Hidden HTML field: This hidden control acts as a container for the current record’s primary key value. This value is used in the Ajax calls back to the server so the system can reliably find the current record.
• WebTextEdit control: This is the control that is responsible for the editing of the book title. The page uses style sheets to hide the fact in the beginning that you are looking at an input control. Notice the JavaScript functions that the control points to for focus, click and blur. You will implement these functions to make the Ajax calls to the server and keep the UI up-to-date with the current edit state.

The Style Sheet

The CSS for this page is simple yet vital to providing the necessary feedback to the user.

Open a style block on your page and enter the following CSS:

body

{

    font-family:Arial, Helvetica, Sans-Serif;        

    margin-top:25px;  

    font-size:1.8em;  

    text-align:center;

}

#published

{

    position:absolute;

    top:159px;

    width:140px;

    left:405px;

}

#date, #dateControl

{

    position:relative;

    width:150px;

    margin-left:auto;

    margin-right:auto;

}

.big

{

    font-size:4em;

}

.none

{

    display:none;

}

.liveInput, .liveInputDirty, .liveInputEdit

{

    border:1px solid #fff;

    text-align:center;

}

.liveInput:hover

{

    border:1px solid #6c3;

}

.liveInputDirty, .liveInputDirty *

{

    color:#ccc;

    border:1px solid #fcc;

}

.liveInputEdit, .liveInputEdit *

{

    border:1px dashed #666;

}

We’ll skip a detailed explanation of the style sheet in hopes that if you are reading this far your CSS skills are sophisticated enough to handle the simple entries in the above style sheet.

The only detail that is perhaps noteworthy here is that the classes will follow the progression of liveInput for an untouched state, liveInputEdit for when users are editing the data and liveInputDirty to update the UI while the server is processing changes.

Supporting JavaScript

A common script action required to update the UI is to change the CSS properties on a given element. In the tradition of DOM manipulation heavyweight jQuery, the script features some helper methods that make it easy to add and remove CSS classes from an element. These methods are optimized to work with plain DOM objects instantiated by either calling $get, getObjectById and for the NetAdvantage specific notation igedit_getById.

To begin, open a script block and enter the following code:

function addCssClass(ctl, cssName)

{

    var c = (ctl.Element) ? ctl.Element : ctl;

    c.className += (" " + cssName + " ");

}

The addCssClass function simply appends the given cssName to the list of classes associated with the element.

function removeCssClass(ctl, className)

{

    var c = (ctl.Element) ? ctl.Element : ctl;        

    var classes = c.className.split(" ");

    var cssClass = "";

    for (var i = 0; i < classes.length; i++)

    {

        if (classes[ i ] != className)

        {

            cssClass += classes[ i ] + " "; 

        }

    }

    c.className = cssClass;

}

The removeCssClass function creates an array of the currently assigned CSS classes and then rebuilds the list only to skip over the class requiring removal.

With these helper functions available now you can begin to implement the control specific logic for editing the title.

Live Title Interaction: the JavaScript

Now you are ready to start implementing live interaction with the title control.

Add the following code to your script block:

var oldVal = "";

function txtTitle_Focus()

{

    var ctl = igedit_getById("<%= txtTitle.ClientID  %>");

    oldVal = ctl.getValue();

}

When the control come to focus txtTitle_Focus is run and gets a refernce to the edit control using the NetAdvantage client-side object model (CSOM) API. The current value is set aside here into the oldValue variable in order to check to make sure there are changes before the page attempts to call back to the server.

function txtTitle_Click()

{

    var ctl = igedit_getById("<%= txtTitle.ClientID  %>");

    removeCssClass(ctl, "liveInput");

    addCssClass(ctl, "liveInputEdit");

}

The txtTitle_Click function’s job is to simply update the UI so the user knows they’ve entered the edit mode. To accomplish this the liveInput class is removed and the liveInputEdit class is added.

function txtTitle_Blur()

{

    var ctl = igedit_getById("<%= txtTitle.ClientID  %>");

    var val = ctl.getValue();

    addCssClass(ctl, "liveInput");

    removeCssClass(ctl, "liveInputEdit");

    if (val != oldVal)

    {

        PageMethods.UpdateTitle($get("bookID").value, val, titleSuccess, fail);

        removeCssClass(ctl, "liveInput");

        addCssClass(ctl, "liveInputDirty");

    }

}

The real work on the page happens when the txtTitle_Blur function is run. First step is to get the new value and then update the UI back to the unaltered state. This action may seem counter-intuitive, but if the following conditional block does not run (because the value is not changed) then the control must returned to the unaltered visual state.

If the user has changed the value then the page’s UpdateTitle method is called using ASP.NET AJAX page methods (you will implement this method in the codebehind in the next section). Arguments to the call include a reference to the hidden input control that is holding the current primary key value, the updated title text, and callback pointers of functions to run in the event of a success or failure.

Once the AJAX call is dispatched, the UI is updated to reflect the data’s dirty state.

function titleSuccess(response)

{

    var ctl = igedit_getById("<%= txtTitle.ClientID  %>");

    removeCssClass(ctl, "liveInputDirty");

    addCssClass(ctl, "liveInput");

    if (!response)

    {

        ctl.setValue(oldVal);

        alert("The server encountered an error while trying to update the title.");

    }

}

When the page hears back from the server, it will either receive a success or failue notification. In the event that the operation was sucessful the titleSucess function is run.

This function takes the final steps to update the UI to reflect an unaltered state. There is also a chance, though, that the Ajax response returns successfully but the intended action is not complete. As you will see when implementing the code behind, if an exception is encountered the server will log the details and return false to the client.

If the change was not successful the WebTextEdit control’s value is reset back to the original value and the user is notified that something went wrong.

function fail(reponse)

{

    alert("Fail " + reponse);

}

Should the request itself fail the aptly-named fail function is run. As with most Ajax demos this code just stubs-out this section with the stern warning that you should never do something like this in a production environment.

Live Title Interaction: the Codebehind

Open the code behind for your page and enter the following code just after the class definition:

protected Book book = null;

This protected variable will hold the instance of the book once loaded. The field is marked as protected so that the ASPX page can access its members when rendering the page.

protected void Page_Load(object sender, EventArgs e)

{

    if (!this.Page.IsPostBack)

    {

        this.book = BookRepository.Instance.GetByID(1);

        this.txtTitle.Text = this.book.Title;

        this.wdcPublishDate.Value = this.book.PublishDate;

    }

}

When the page loads the book is hydrated from the data repository and the controls are filled with the appropriate data.

[WebMethod]

public static bool UpdateTitle(int id, string title)

{

    try

    {

        System.Threading.Thread.Sleep(3000);

        Book b = BookRepository.Instance.GetByID(id);

        b.Title = title;

        BookRepository.Instance.Update(b);

        return true;

    }

    catch (Exception ex)

    {

        // publish exception

        System.Diagnostics.Debug.WriteLine(ex.Message);

        return false;

    }

}

There are a few details to note about the UpdateTitle method. First, the method is decorated as a "WebMethod" (found in the System.Web.Services namespace) which triggers ASP.NET AJAX to create a client-side proxy function. Second, the method is marked as static as this is a requirement for page methods. Third, note the call to the current thread to sleep. This is required so you are able to see the changes in the UI as the page is waiting for a response. On most development machines the response time would be so fast that the UI updates would take place immediately. The call to sleep the thread mimics more what the request/response time might be on the web.

You may choose to handle the state of your objects any number of ways, but for this demo, we are simply getting the latest version of the object from the repository, updating the title and sending the changes back.

If everything goes as planned, the method returns true to the client.

If an exception is encountered the code here stubs out how you may handle the situation in the real world. First we add a comment reminding you to always log or otherwise publish any exceptions that may bubble up to the user. Next, the call to Debug.WriteLine is a handy place to set a breakpoint and inspect the error. Finally the method returns false to the client. The approach you see here is better than simply allowing the exception to bubble all the way up to the client because you are now able to do something valuable with the error information before the server relinquishes control of the operation.

Try it Out

Launch the web page and edit the title. You should be able to see the changes in the UI for each step in the editing process.

The Publish Date Editor

The date editor is implemented much the same as the title editor. The following explanation will cover any of the divergent concepts from what was necessary to build the title editor.

Return to the ASPX page and enter the following mark up directly after the closing DIV tag for the title editor:

<div id="published">Published:</div>

<div id="dateControl" class="none">

    <igsch:WebDateChooser Width="300px" ID="wdcPublishDate" runat="server" >

        <ClientSideEvents ValueChanged="wdcPublishDate_ValueChanged" />

    </igsch:WebDateChooser>

</div>

<div id="date" class="liveInput" onclick="date_Click(this);">

    <%= this.book.PublishDateShort %>

</div>

There are two main differences in how the UI elements are constructed for the publish date. Rather than the editing control being styled for the display state, this page uses a text literal to give the UI clues that the data is editable. When the user clicks on the DIV with the date ID the element will disappear and the input control will appear in its place.

Notice the ClientSideEvents node nested under the WebDateChooser control. This is how you associate a function with the client-side event for ValueChanged.

Live Publish Date Interaction: the JavaScript

Return to the script block and enter the following JavaScript:

function date_Click(date)

{

    var dateControl = $get("dateControl");

    addCssClass(date, "none");

    removeCssClass(dateControl, "none");

    addCssClass(dateControl, "liveInputEdit");

}

When the user clicks on the date literal, the element is hidden and the WebDateChooser is shown in the edit state.

var newDate = "";

function wdcPublishDate_ValueChanged(oDateChooser, newValue, oEvent)

{

    var dt = new Date(newValue);

    newDate = (dt.getMonth()+1) + "/" + dt.getDate() + "/" + dt.getFullYear();

    var dateControl = $get("dateControl");

    removeCssClass(dateControl, "liveInputEdit");

    addCssClass(dateControl, "liveInputDirty");

    PageMethods.UpdatePublishDate($get("bookID").value, newValue, dateSuccess, fail);

}

Much like the blur function for the title, the wdcPublishDate_ValueChanged function holds most of the processing logic for this element. When the ValueChanged event fires this function is run and the newValue argument holds the user’s newly chosen value. This value, however, is not in the same format that you might expect. In order to display the chosen value in the same format as seen in the previous state you must manipulate the data with the JavaScript date object.

Then next step is to switch CSS classes to update the controls to reflect the data’s dirty state.

Finally the UpdatePublishDate method is called in much the same manner as when you were updating the title.

function dateSuccess(response)

{

    var dateControl = $get("dateControl");

    var date = $get("date");

    removeCssClass(dateControl, "liveInputDirty");

    removeCssClass(date, "none");

    addCssClass(dateControl, "none");

    if (response)

    {

        date.innerText = newDate;        

    }

    else

    {

        alert("The server encountered an error while trying to update the publish date.");

    }

}

The dateSuccess function should look familiar to you as well. First order of business is to get references to both the date literal and date control elements on the page. Then the stylesheets are updated and if the operation was a success the display literal is updated with the new value.

Live Publish Date Interaction: the Codebehind

The codebehind that updates the publish date is nearly identical to what is implemented to edit the title:

[WebMethod]

public static bool UpdatePublishDate(int id, DateTime publishDate)

{

    try

    {

        System.Threading.Thread.Sleep(3000);

        Book b = BookRepository.Instance.GetByID(id);

        b.PublishDate = publishDate;

        BookRepository.Instance.Update(b);

        return true;

    }

    catch (Exception ex)

    {

        // publish exception

        System.Diagnostics.Debug.WriteLine(ex.Message);

        return false;

    }

}

Try it Out

Launch the web page and edit the publish date. You should be able to see the changes in the UI for each step in the editing process.

Conclusion

Building pages that use the Live Form pattern are simple to execute and create a great user experience. Be careful though, this approach is only recommended for forms that have a few editable items. Creating long forms that use this pattern will create unnecessary network traffic and could bring rise to some interesting concurrency issues.

Resources

• Full ASPX listing
• Full C# listing
• Live Form Ajax Pattern
• BookRepository
• NetAdvantage Web Client – Not yet a subscriber? Download the trial today.

Watch the Videos

Part 1

Part 2

Part 3

Part 4

Part 5