(untagged)

Implementing AJAX Code Customizations in Generated Applications

Iron Speed Designer

25 Apr 2008

The article demonstrates how easy it is to add AJAX code customizations in applications generated using Iron Speed Designer V4.0.

This article is in the Product Showcase section for our sponsors at CodeProject. These articles are intended to provide you with information on products and services that we consider useful and of value to developers.

Introduction

Iron Speed Designer Version 4.0 generates AJAX enabled applications and provides AJAX support for both .NET Framework 1.1 and .NET Framework 2.0 applications. Applications generated by Iron Speed Designer V4.0 automatically include these features required to support your AJAX code customizations:

Inclusion of the Microsoft Atlas DLL (.NET 2.0) or AjaxPro DLL (.NET 1.1) in the application’s Bin folder and project files.
Web.config changes for Microsoft Atlas support (.NET Framework 2.0) or AjaxPro support (.NET Framework 1.1).
JavaScript functions you can call to display a popup (call-out).

Moreover, applications migrated from earlier versions of Iron Speed Designer are upgraded with AJAX support. In short, we have done the ground work, so you can implement code customizations that harness the power of AJAX.

Microsoft provides native support only for .NET Framework 2.0 applications through the Atlas Framework. However, a number of third-party frameworks that support AJAX are available for use with .NET Framework 1.1 applications. The Iron Speed Designer employs AjaxPro.dll (a third-party DLL available for free) for use with .NET applications.

Writing a Call-Out Code Customization Using AJAX

You can easily add AJAX code customizations to Iron Speed Designer generated applications. To add a wide variety of AJAX code customizations, you simply add a few lines of JavaScript code to handle the OnClick or OnMouseOver events and to retrieve and format data from the database.

The following example demonstrates how easy it is to add AJAX code customizations in applications generated using Iron Speed Designer V4.0. It uses AJAX to make asynchronous calls to methods defined in the code-behind file of the page, which then calls back to a client-side JavaScript function to display data in a popup window.

Procedure

Step 1: Invoke a JavaScript function on the MouseOver event

Start by defining an area where the user can mouse over to see the popup data. In this example, when the user moves the mouse over a record, the MyCustomFunction() JavaScript function is called. This function takes two arguments, the first of which is the primary key ID of the record over which the mouse is moved. The second argument is the reserved word 'event' that determines the location of the mouse.

In your page’s HTML layout file, add an <a OnMouseOver... /> HTML tag to define the mouse over region. Note: Be sure to add this in the HTML layout file and not in the ASPX page generated by Iron Speed Designer. You can use a FieldValue code generation tag to specify the primary key ID for the first argument to MyCustomFunction. Make sure to specify the database field corresponding to the Field Value code generation tags in the Page Properties dialog box.

<a OnMouseOver='MyCustomFunction(<GEN:FieldValue NAME="MyRecordID"/>, event);'>
    <GEN:FieldValue NAME="MyRecordName"/>
</a>

Step 2: Define two JavaScript functions to handle the OnMouseOver event

Define two JavaScript functions within script tags in your HTML layout page. The first function is called by the OnMouseOver event. This function saves the current mouse position, and then calls the AJAX method declared in the code-behind file of your Page class. The second function is the call-back function invoked by the (code-behind) AJAX method.

There are slight differences between .NET Framework 1.1 (using AjaxPro.dll) and .NET Framework 2.0 (using Microsoft Atlas), as described below.

.NET Framework 1.1 applications

<script type ="text/javascript">
function MyCustomFunction(MyRecordID, event)
{
    // Save the mouse position for later use by detailRolloverPopup()
    SaveMousePosition(event);
 
    // Invoke the Ajax method defined in the code-behind of the page
    // Replace MYAPP with your application's name
    // and MYPAGE with the corresponding page class's name
    // Also, specify the callback function - MyCallBack (defined below)
    MYAPP.UI.MYPAGE.GetRecordDescription(MyRecordID, MyCallBack);
}
 
function MyCallBack(result)
{
    // The detailRollOverPopup() displays the content
    // returned from the Ajax call in a popup window
    // It accepts three parameters:
    // - aTitle, string to be displayed in the title bar of the popup window.
    // - aContent, string containing HTML to be displayed in the body of the popup.
    // - aPersist, boolean indicating whether the popup
    //   should remain visible even on mouseout.
    detailRolloverPopup('Window Title', result.value, false);
}
</script>

.NET Framework 2.0 applications

AJAX methods (referred to as ‘web methods’ in the Atlas framework) for .NET Framework 2.0 applications can be defined in two different locations: in the page’s code-behind (*.vb or *.cs) file, or in a Web Service (*.asmx file). Each approach has its own merits. While Web Services guarantee interoperability between various platforms, they can be subject to security issues. On the other hand, defining web methods in the page’s code-behind overcomes the security issue.

Invoking a web method defined in the page’s code-behind file.

If the web method is defined in the page’s code-behind file (MyPage.aspx.vb or MyPage.aspx.cs), then use the PageMethods JavaScript command to invoke the web method. The PageMethods command invokes a specific method in the current page, thereby eliminating the need for a web service.

The JavaScript function below uses the PageMethods command to invoke an Ajax web method that is defined in the page’s code-behind file. Note that this JavaScript function should be placed within script tags in your HTML layout page.

<script type ="text/javascript">
function MyCustomFunction(MyRecordID, event)
{
        // Save the mouse position for later use by detailRolloverPopup()
 
        SaveMousePosition(event);
        // Invoke the WebMethod defined in the code-behind
        // of the page through the PageMethods command
        // The PageMethods command will enable you to invoke
        // a specific method in the current page
        // eliminating the need for a web service.
        // Also, specify the callback function - MyCallBack (defined below)
        PageMethods.GetRecordDescription(MyRecordID, MyCallBack);
}
 
function MyCallBack(result)
{
        // The detailRollOverPopup() displays the content
        // returned from the Ajax call in a popup window
        // It accepts three parameters:
        // - aTitle, string to be displayed in the title bar of the popup window.
        // - aContent, string containing HTML to be displayed in 
        //   the body of the popup.
        // - aPersist, boolean indicating whether the popup should
        //   remain visible even on mouseout.
        detailRolloverPopup('Window Title', result, false);
}
</script>

Invoking a web method defined in a Web Service.

A web method defined in a Web Service can be directly invoked by specifying the name of the method and the Web Service in which it is defined. The Web Service (*.asmx file) can be added through Visual Studio’s ‘Add New Component’ option and saved within the root directory of your Iron Speed Designer-generated application.

The JavaScript function below invokes an AJAX web method that is defined in a Web Service. Note that this JavaScript function should be placed within script tags in your HTML layout page.

<script type ="text/javascript">
function MyCustomFunction(MyRecordID, event)
{
        // Save the mouse position for later use by detailRolloverPopup()
 
        SaveMousePosition(event);
        // Invoke the web method defined in the Web Service.
        // This example assumes the name of the web service file created
        // to be MyWebService and the web method
        // defined in this web service to be GetRecordDescription.
        // Also, specify the callback function - MyCallBack (defined below)
        MyWebService.GetRecordDescription(MyRecordID, MyCallBack);
}
 
function MyCallBack(result)
{
        // The detailRollOverPopup() displays the content returned
        // from the Ajax call in a popup window
        // It accepts three parameters:
        // - aTitle, string to be displayed in the title bar
        //   of the popup window.
        // - aContent, string containing HTML to be displayed
        //   in the body of the popup.
        // - aPersist, boolean indicating whether the popup
        //   should remain visible even on mouseout.
        detailRolloverPopup('Window Title', result, false);
}
</script>

Step 3: Add a ScriptManager reference to your page (.NET Framework 2.0 only)

Note: This step applies only for applications built for .NET Framework 2.0.

In your HTML layout page, include the <atlas:ScriptManager> element. This tag enables Microsoft Atlas client scripts to be downloaded when the web page is requested, and enables the page for Microsoft Atlas. Please note that this tag must be placed within the page’s <form> tag. The ScriptManager tag definition varies depending on where the web method is defined.

The ScriptManager tag for web methods defined in the code-behind of the page:
```
<atlas:ScriptManager ID="scriptManager1" runat="server"/>
```

The ScriptManager tag for web methods defined in a Web Service (specify the location of the Web Service file appropriately in the Path property of the ServiceReference tag):

<atlas:ScriptManager ID="scriptManager1" runat="server">
   <Services>
      <atlas:ServiceReference Path="../MyApp/MyWebService.asmx" />
   </Services>
</atlas:ScriptManager>

Step 4: Include code in the code-behind file

.NET Framework 1.1 applications

Register your page with the RegisterTypeForAjax() method.
For .NET Framework 1.1 applications, the AjaxPro DLL requires you to register pages that are invoked by client-side AJAX calls. The RegisterTypeForAjax() method takes care of registering the page. In the page’s code-behind file of the page where you added the HTML and JavaScript tags, invoke RegisterTypeForAjax() within the PageLoad method. This method accepts the Page class’ name as an argument. The name of the Page class whose Page Load event is invoked needs to be specified as the argument in this case.
Define AJAX methods with AjaxPro.AjaxMethod.
All AJAX methods must be declared using the AjaxPro.AjaxMethod command. This enables your server-side methods to be invoked from client-side JavaScript. In our example, the server-side GetRecordDescription() method accepts the record’s ID as an argument, constructs a ‘WHERE’ clause that is used to retrieve the selected record's details based on its record ID, and returns the description for the specified record to the client-side callback function.

C#, .NET Framework 1.1:

public class MYPAGE: BaseApplicationPage
{
  private void MYPAGE_Load(object sender, System.EventArgs e)
  {
        // Register the page class so that client-side JavaScript can call an
        // AjaxMethod.
        // Change MYPAGE to the corresponding name of the page class.
        AjaxPro.Utility.RegisterTypeForAjax(GetType(MYPAGE));
  }
  // Define all Ajax methods in .NET 1.1 with the AjaxMethod tag.
  // Replace <Record ID> with the Id field of your database table.
  // Replace <Table Name> with the name of your database table.
  // Replace <Description Field> with the name of a description field from your
  // database table.
  [AjaxPro.AjaxMethod]
  public string GetRecordDescription(int MyRecordID)
  {
        // For INTEGER Id's
        string whereStr = " <Record ID> = " + MyRecordID;
        // For STRING Id's, comment the line above and uncomment the line below.
        // string whereStr = " <Record ID> = '" + MyRecordID + "'";
        <Table Name>Record selectedRecord = <Table Name>Table.GetRecord(whereStr);
        // In this example the description of the selected record is retrieved
        string content = "The description for the selected record is " + 
                         selectedRecord.<Description Field>;
        return content;
  }
}

Visual Basic .NET, .NET Framework 1.1:

Public Class MYPAGE Inherits BaseApplicationPage
Private Sub MYPAGE_Load(ByVal sender As Object, _
        ByVal e As System.EventArgs) Handles MyBase.Load
     ' Register the page class so that client-side JavaScript can
     ' call an AjaxMethod.
     ' Change MYPAGE to the name of the page class.
     AjaxPro.Utility.RegisterTypeForAjax(GetType(MYPAGE))
End Sub
 
' Define all web methods in .NET 1.1 with the AjaxMethod tag.
' Replace <Record ID> with the Id field of your database table.
' Replace <Table Name> with the name of your database table.
' Replace <Description Field> with the name of a description field from your
' database table.
<AjaxPro.AjaxMethod()> _
Public Function GetRecordDescription(ByVal MyRecordID As Integer) As String
     ' For INTEGER Id's
     Dim whereStr As String = "<Record ID> = " & MyRecordID
     ' For STRING Id's, comment the line above and uncomment the line below.
     Dim whereStr As String = "<Record ID> = '" & MyRecordID & "'"
     Dim rec As <Table Name>Record = <Table Name>Table.GetRecord(whereStr)
     ' In this example the description of the selected record is
     ' retrieved.
     Dim content As String = "The description for the chosen record is" & _
                             rec.<Description Field>
     Return content
End Function
End Class

.NET Framework 2.0 applications

Define the server-side web method that returns the record’s description to the client-side function either in your page’s code-behind file (MyPage.aspx.vb or MyPage.aspx.cs) or in the Web Service file (MyWebService.asmx). All web methods must be declared using the System.WebServices.WebMethod command which enables server-side web methods to be invoked from client-side JavaScript and makes the results returned by these web methods available for use by the client-side callback function.

C#, .NET Framework 2.0:

Web method defined in the page’s code-behind file:

partial class MyPage : BaseApplicationPage
// Code-behind class for the MyPage page.
// Place your customizations in Section 1. Do not modify Section 2.
{
  #region "Section 1: Place your customizations here."
     // Define all web methods in .NET 2.0 within the WebMethod tag.
     // Replace <Record ID> with the Id field of your database table.
     // Replace <Table Name> with the name of your database table.
     // Replace <Description Field> with the name of a description field from your
     // database table.
     [System.Web.Services.WebMethod()]
     public string GetRecordDescription(int MyRecordID)      {
        // For INTEGER Id's
        string whereStr = " <Record ID> = " + MyRecordID;
        // For STRING Id's, comment the line above and uncomment the line below.
        // string whereStr = " <Record ID> = '" + MyRecordID + "'";
        <Table Name>Record selectedRecord = <Table Name>Table.GetRecord(whereStr);
        // In this example the description of the selected record is retrieved
        string content = "The description for the selected record is " + 
            selectedRecord.<Description Field>;
        return content;
     }
  #endregion 
  #region "Section 2: Do not modify this section."
     :
     :
  #endregion
}

Web method defined in the MyWebService.asmx file:

using System.Web;
using System.Web.Services;
using System.Web.Services.Protocols;
 
[WebService(Namespace = "http://tempuri.org/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]

public class WebService : System.Web.Services.WebService
{
     // Define all web methods in .NET 2.0 within the WebMethod tag.
     // Replace <Record ID> with the Id field of your database table.
     // Replace <Table Name> with the name of your database table.
     // Replace <Description Field> with the name
     // of a description field from your database table.
     [WebMethod]
     public string GetRecordDescription(int MyRecordID)
     {
        // For INTEGER Id's
        string whereStr = " <Record ID> = " + MyRecordID;
        // For STRING Id's, comment the line above and uncomment the line below.
        // string whereStr = " <Record ID> = '" + MyRecordID + "'";
        <Table Name>Record selectedRecord = <Table Name>Table.GetRecord(whereStr);
        // In this example the description of the selected record is retrieved
        string content = "The description for the selected record is " + 
                         selectedRecord.<Description Field>;
        return content;
     }
}

Visual Basic .NET, .NET Framework 2.0:

Web method defined in the page’s code-behind file:

Partial Class MyPage Inherits BaseApplicationPage
' Code-behind class for the MyPage page.
' Place your customizations in Section 1. Do not modify Section 2.
 
  #Region "Section 1: Place your customizations here."
  ' Define all web methods within the WebMethod tag.
  ' Replace <Record ID> with the Id field of your database table.
  ' Replace <Table Name> with the name of your database table.
  ' Replace <Description Field> with the name of a description field from your
  ' database table.
  <Services.WebMethod()> _
        Public Function GetRecordDescription(ByVal MyRecordID As Integer) As String
           ' For INTEGER Id's
           Dim whereStr As String = "<Record ID> = " & MyRecordID
           ' For STRING Id's, comment the line above and uncomment the line below.
           ' Dim whereStr As String = "<Record ID> = '" & MyRecordID & "'"
           Dim rec As <Table Name>Record = <Table Name>Table.GetRecord(whereStr)
           'In this example the description of the selected record is retrieved
           Dim content As String = "The description for the chosen record is " & _
                                   rec.<Description Field>
           Return content
        End Function
  #End Region
  #Region "Section 2: Do not modify this section."
     :
     :
  #End Region
End Class

Web method defined in the WebService.asmx file:

<%@ WebService Language="VB" Class="MyWebService" %>
Imports System.Web
Imports System.Web.Services
Imports System.Web.Services.Protocols
 
Public Class MyWebService Inherits System.Web.Services.WebService
     ' Define all web methods within the WebMethod tag.
     ' Replace <Record ID> with the Id field of your database table.
     ' Replace <Table Name> with the name of your database table.
     ' Replace <Description Field> with the name of a description field from your
     ' database table.
     <WebMethod()> _
        Public Function GetRecordDescription(ByVal MyRecordID As Integer) As String
           ' For INTEGER Id's
           Dim whereStr As String = "<Record ID> = " & MyRecordID
           ‘ For STRING Id's, comment the line above and uncomment the line below.
           ' Dim whereStr As String = "<Record ID> = '" & MyRecordID & "'"
           Dim rec As <Table Name>Record = <Table Name>Table.GetRecord(whereStr)
           'In this example the description of the selected record is retrieved
           Dim content As String = 
               "The description for the chosen record is " & rec.
           Return content
        End Function
End Class

Step 5: Build and run the application

That’s all there is to it! When you mouse over the fields you selected in your application, you should see an attractively formatted call-out bubble.

References

The latest AJAX .NET DLLs can be downloaded from here.

You can refer to the following sites for additional details and simple AJAX examples:

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here