Implementing Infragistics ASP.NET UI Controls in Iron Speed Designer Applications
Michael F. Sumption
GovIS, LLC

July 12, 2005
Iron Speed Designer V2.1

Introduction
Although Iron Speed Designer provides all the basic controls and styling a developer would need to create a great ASP.NET application, developers may wish to use third-party controls, such as Infragistics NetAdvantage ASP.NET UI controls, to enhance their application with a unique feature or style. Over the past few years, there have been many inquiries about the extensibility of Iron Speed Designer especially regarding the integration of third-party controls. In my last article, I talked about Implementing Crystal Reports. This article will focus on implementing various Infragistics controls such as WebMenu, WebToolbar, WebListbar, WebTree, WebTab, and WebGrid, thus demonstrating the ease and power of extending an Iron Speed Designer application. Examples are based on Iron Speed Designer 2.1.3, Infragistics NetAdvantage 2005 Vol. 1, and Microsoft Visual Studio .NET 2003 versions using the SQL Server 2000 Northwind database.
Creating a Header with the WebMenu and WebToolbar
When you first create an Iron Speed Designer application, a Header.ascx (i.e. Web User Control) file is also created, which is used in the various page templates to display content at the top of each page. By default, the Header contains an image tag for a logo, though it is not limited to the image alone. So, for our first example, let's add a WebMenu and WebToolbar for top level navigation and utility purposes.
  1. Open your application in Visual Studio .NET. In the Header & Footer folder of the Solution Explorer, open the Header.ascx file.
    NOTE: If this is the first time opening the app in Visual Studio .NET, then select Rebuild from the Build menu. You need to rebuild the project in Visual Studio .NET first before proceeding in order to resolve some class reference issues.
  2. Drag a WebMenu and WebToolbar control onto the page from the NetAdvantage 5.1 Web tab in the Visual Studio.NET Toolbox.
    NOTE: When the Infragistics controls are added to the page, their associated class declarations are added to the Header.gen.aspx.vb code-behind class, their associated Register tags are added to the HTML, and their associated namespace references are added to the project automatically. This is important to note because these declarations etc. will need to be copied and set in a later step.
  3. Go to the HTML view and arrange the controls within the HTML table according to your preference. See Figure 1 below for a sample layout (though not pretty).


  4. Create menu items and toolbar buttons and set their properties according to your application's requirements.
    NOTE: You can also apply a preset style or customize a style to suit your preference. See Figure 2 below for an example of setting the TargetURL property of the New | Customer menu item. Most all properties of Infragistics controls can be set at design-time in a Designer or at run-time in server-side or client-side (client object model - JavaScript) code.


  5. In order to build the project in Visual Studio .NET, Infragistics requires that their Shared DLL be local. So, in the Solution Explorer, expand the References node. Right-click on the Infragistics.WebUI.Shared.v5.1 namespace and select Properties. Change the Copy Local property to True. This will copy the Infragistics.WebUI.Shared.v5.1.dll to your app's Bin directory.
  6. Open the Header.safe.aspx.vb code-behind safe class and add the following control class declarations:


    Public Class Header
        Inherits HeaderGen
        Public Shadows WithEvents UltraWebMenu1 As Infragistics.WebUI.UltraWebNavigator.UltraWebMenu
            Public Shadows WithEvents UltraWebToolbar1 As Infragistics.WebUI.UltraWebToolbar.UltraWebToolbar
     

    SHORTCUT: Copy the declarations from the gen class, paste them into the safe class, and change the scope from Protected to Public Shadows.
    NOTE: This declaration allows us to write code in the safe class that references the Infragistics controls.
     
  7. Build the project and close it. Go back to Iron Speed Designer and open your application.
    NOTE: When you view the Header.ascx file in Design view in Iron Speed Designer, you will not be able to see the Infragistics controls.
  8. Open the Header.ascx file and switch to the ASPX view. Highlight and copy the following code that was previously set up in Visual Studio .NET:


  9. Switch to HTML view and paste the code at the top above the GEN:TEMPLATE tag.
  10. Switch back to the ASPX view and highlight and copy all of the new HTML code for the Infragistics controls.
  11. Switch to the HTML view and paste the code into the HTML table.
    NOTE: The HTML template source file is used by Iron Speed Designer to regenerate the .aspx page properly in the future.
    NOTE: If you make any changes to the Infragistics controls in Visual Studio .NET, you will need to repeat steps 10 and 11.
  12. Almost done, there's a couple more steps to make sure that Iron Speed Designer compiles the application properly when using the Visual Basic (vbc.exe) compiler. Copy the following files to your application's Bin directory: Infragistics.WebUI.UltraWebNavigator.v5.1.dll, Infragistics.WebUI.UltraWebToolbar.v5.1.dll. In the default installation of Infragistics NetAdvantage 2005 Vol. 1, these files are located at C:\Program Files\Infragistics\NetAdvantage 2005 Volume 1\ASP.NET\Bin.
  13. In your application's root directory, open the file CompileApplication.rsp in a text editor. Append the names of the three Infragistics DLL's to the /reference: line as follows (comma delimited, no spaces, the third DLL is the "Shared DLL" from Step 6):


    /reference:BaseClasses.dll, BaseClasses.Web.Controls.dll, System.dll, System.Data.dll, System.Drawing.dll, System.Web.dll,
    System.Xml.dll, Infragistics.WebUI.Shared.v5.1.dll, Infragistics.WebUI.UltraWebNavigator.v5.1.dll, Infragistics.WebUI.UltraWebToolbar.v5.1.dll
     


  14. Add any desired functionality code to the Header.safe.aspx.vb class for the Infragistics controls. Build and run the app. You're done!
Creating an Application Navigation Bar with WebListbar and WebTree
Let's say that you want a navigation control with a Microsoft Outlook 2003 UI style. Well, the Infragistics WebListbar and WebTree controls can do just the trick. Assuming that your application uses an Iron Speed Designer theme with a vertical left-side menu, follow these steps to replace the built-in Iron Speed Designer menu with a new application navigation bar:
  1. Open your application in Iron Speed Designer. From the Tools menu, select the Configure Menu ... option. Check all the menu items and delete them.
  2. In the Application Explorer, open the Menu.ascx file in the Menu Panels folder. Go to the HTML view. Remove any unwanted cells and arrange the HTML table with one row and cell.
  3. Build and close your application. Open your application in Visual Studio .NET.
  4. Create a new Web User Control with the name of EmployeeTreeView.ascx and save it in the Menu Panels folder.
  5. Drag and drop a WebTree control onto the new Web User Control. Go to the HTML view and arrange the control within the HTML table according to your preference.
  6. Create nodes in the WebTree control and set their properties according to your application's requirements.
    NOTE: What if you wanted to populate the WebTree control dynamically at run-time with names and reporting hierarchy from an Employee table. Following is a code sample that accomplishes that goal while setting various properties such as TargetURL with an added parameter. The WebTree control is directly bindable to a data source; however, I prefer to populate the control in this manner in order to use Iron Speed Designer methods and to set the properties.


    Private Sub Page_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
    If (Not IsPostback()) Then
      ' Get instance of the table's access class
      Dim ra As RepAccess = RepAccess.Instance

      ' Create sort order for hierarchical (i.e. ReportsTo) sorting. This assumes that your table has
      ' a "Root", "ReportsTo", and "ID" column in your DB table
      Dim so As New IronSpeed.Base.Data.SqlBuilderSortOrder(False, False)
      so.AddColumn(ra.RootColumn, IronSpeed.Base.Data.SqlBuilderSortDirection.OrderDir.Desc)
      so.AddColumn(ra.ReportsToColumn, IronSpeed.Base.Data.SqlBuilderSortDirection.OrderDir.Asc)
      so.AddColumn(ra.IDColumn, IronSpeed.Base.Data.SqlBuilderSortDirection.OrderDir.Asc)

      ' Get Reps (i.e. employees) from DB table with sort order
      Dim rRecs As ArrayList = ra.GetList(Nothing, so, 0, 100)
      If (Not IsNothing(rRecs) AndAlso rRecs.Count > 0) Then
        Dim rRec As RepRecord

        ' Create root node, loop thru Reps arraylist and populate remaining nodes
        Dim rootNode As New Infragistics.WebUI.UltraWebNavigator.Node
        For Each rRec In rRecs

          ' Set root node based on the "Root" field in the DB table
          If rRec.GetRootFieldValue = "T" Then
            rootNode.Text = rRec.GetRepNameFieldValue
            rootNode.Tag = CStr(rRec.GetIDFieldValue)
            rootNode.TargetURL = "../Rep/ShowRepRecord.aspx?Rep=" & CType(rRec.GetIDFieldValue, String)
            UltraWebTree1.Nodes.Add(rootNode)
          Else

            ' Set all other nodes here
            Dim node As New Infragistics.WebUI.UltraWebNavigator.Node
            node.Text = rRec.GetRepNameFieldValue
            node.Tag = CStr(rRec.GetIDFieldValue)
            node.TargetURL = "../Rep/ShowRepRecord.aspx?Rep=" & CType(rRec.GetIDFieldValue, String)

            ' If the Rep's ID field value matches their ReportsTo field value then they're added under the root node,
            ' otherwise the Rep's node is added under their supervisor's (i.e. parent) node
            If rRec.GetIDFieldValue = rRec.GetReportsToFieldValue Then
              rootNode.Nodes.Add(node)
            Else
              Dim parentNode As Infragistics.WebUI.UltraWebNavigator.Node
              parentNode = UltraWebTree1.Find(CStr(rRec.GetReportsToFieldValue))
              If Not IsNothing(parentNode) Then
               parentNode.Nodes.Add(node)
              End If
            End If
          End If
        Next

        ' Store treeview to session for restore after postback since it will not persist when used globally across
        ' your entire application while embedded in a WebListbar control in the Menu.ascx file.
        Session("RepTree") = UltraWebTree1
      End If
    Else

      ' Restore treeview after postback
      UltraWebTree1.ClearAll()
      Dim wt As Infragistics.WebUI.UltraWebNavigator.UltraWebTree = _
        CType(Session("RepTree"), Infragistics.WebUI.UltraWebNavigator.UltraWebTree)
          UltraWebTree1.Nodes.AddRange(wt.Nodes)
    End Sub


  7. In the Solution Explorer, open the Menu.ascx file in the Menu Panels folder.
  8. Drag and drop a WebListbar control onto the page. Go to the HTML view and arrange the control within the HTML table according to your preference.
  9. Create groups in the WebListbar control and set their properties according to your application's requirements. For this example, I'll create a group named Employees.
  10. Right-click on the Employees group and select the Edit Template | "Employees" Group Template menu item.
  11. From the Solution Explorer, drag and drop the EmployeesTreeView.ascx file onto the Group Template Service region of the WebListbar control (see Figure 3).


  12. Right-click on the Employees group and select the End Template Editing menu item.
  13. Do steps 6 - 13 in the prior section "Creating a Header ..." with the appropriate file names etc. from this example.
    NOTE: The WebTree control is contained in the WebNavigator.dll.
    NOTE: Besides the Register tag for the WebListbar control, there is another Register tag that needs to be copied from the ASPX view to the HTML view in Iron Speed Designer. This other Register tag refers to the Web User Control (i.e. EmployeesTreeView.ascx) that was embedded in the WebListbar control Employees group. The Register tag looks like this:


  14. Add any desired functionality code to the Menu.safe.aspx.vb class for the Infragistics controls. Build and run the app (see Figure 4). You're done!
Creating a Master-Multi-Detail Page with WebTab
Making web applications look and function like traditional Windows applications can be challenging. One example of this is the Master-Multi-Detail page where multiple detail record sets are contained within tabs of a TabControl under the Master record. The WebTab control has a TargetURL property that allows you to display a page inside a tab using an iframe. In Iron Speed Designer, it's easy to create an empty page with a bound table panel that would represent a detail record set. Put these two concepts together with a few tips and you have the following example:
  1. Open your application in Iron Speed Designer. Open the EditEmployeesRecord.aspx page (Northwind).
  2. Click the Configure... button of the EmployeesRecord panel. Go to the Master-Detail section. Clear any included Details.
  3. Create a new Empty page named Territories.aspx and save it in the EmployeeTerritories folder.
  4. Drag and drop an EditTable panel onto the page.
    NOTE: You may wish to remove the title section of the panel since this will be redundant with the title on the tab.
  5. Configure the EditTable panel by connecting it to the EmployeeTerritories table. In the Query section of the Table Panel Wizard, add a WHERE clause that sets the EmployeeID field equal to a URL parameter value (see Figure 5). Click OK to close the Edit WHERE Clause dialog. Click Finish to close the Table Panel Wizard dialog.


  6. Right-click the inline row Edit button, and select the Properties menu item. Select the Bindings tab.
    NOTE: Of course, in an EditTable you can modify the record directly, but there may be a scenario where you want to edit the record in an EditRecord page, such as when the record has too many fields, or when you are using a ShowTable panel instead.
    NOTE: In a Detail page, if the end-user clicks the Add (ShowTable) or Edit button, the complete AddRecord or EditRecord page will appear in the iframe including the Header etc., which is undesirable. So, then you have two options: create a custom AddRecord and EditRecord page for each Detail to display in the iframe, or redirect to the regular AddRecord and EditRecord pages in the main (i.e. parent) browser window. Since the latter option is more practical,  steps 6 - 9 are necessary.
  7. Change the Button Command and Action After Command settings as follows in Figure 6. This change allows us to customize the redirection of the button to occur in the main browser window instead of the iframe.


  8. Open the Territories.safe.aspx.vb file and insert the following OnIronSpeedEvent code into the CustomRecordControl class section (for the in-line row Edit button).


    Public Class CustomRecordControl
      Inherits IronSpeed.Base.Web.UI.WebControls.RecordControl

      Public Overrides Sub OnIronSpeedEvent(ByVal args As IronSpeed.Base.IronSpeedEventArgs)
        Select Case (args.CustomEventName)
          Case "Edit"

            ' Get the selected employee record
            Dim etRec As EmployeeTerritoriesRecord = _
              CType(Me.GetRecord(False), EmployeeTerritoriesRecord)

              ' Write out the redirection to the parent window with parameter
              Page.Response.Write("<script>window.parent.location.href=" & _
              "'EditEmployeeTerritoriesRecord.aspx?EmployeeTerritories=" & _
              CStr(etRec.GetEmployeeIDFieldValue) & _
              "'</script>")
        End Select

        ' Do not forget to call the underlying MyBase.OnIronSpeedEvent - otherwise
        ' your other functionality will stop working.
        MyBase.OnIronSpeedEvent(args)
        End Sub
        ...
     

  9. Also in the Territories.safe.aspx.vb file, add the following code at the page level (e.g. in the "Additional code customizations" region). This override keeps the page from being cached in the browser History collection, which is essential to this functionality.


    Protected Overrides Sub UpdateSessionNavigationHistory()
      'Do nothing
    End Sub
     


  10. Repeat steps 3 - 9 for the Orders Detail page.
  11. Open the ShowEmployeesTable.aspx page. Right-click on the Edit button and select the Properties menu item. Select the Bindings tab.
  12. In the Action After Command section of the Page Properties dialog, click the Edit button of the URL Parameters field.
  13. In the Parameter Value section of the URL Parameter dialog, click the Field Value radio button and select the EmployeeID field from the corresponding drop-down-list-box (see Figure 7). Click OK to close the URL Parameter dialog. Click OK to close the Page Properties dialog.
    NOTE: Changing the URL Parameter setting ensures that the value (i.e. master record primary key) can be easily used in a later step for retrieving the detail records to be displayed in the tabs. Yes, you could just select the Primary Key radio button without URL Encoding, but I prefer this method instead.


  14. Build and close your application. Open your application in Visual Studio .NET. Open the EditEmployeesRecord.aspx page.
  15. Drag and drop a WebTab control onto the page. Go to the HTML view and arrange the control below the EmployeesRecord panel in a cell according to your preference.
  16. Create two tabs in the WebTab control and set their properties according to your application's requirements. For this example, set the tabs' Text and Key properties to "Territories" and "Orders" respectively.
    NOTE: The Key property is a string identifier used to access the tab in the Tabs collection by name.
  17. Open the EditEmployeesRecord.safe.aspx.vb file and add the following code to the MyPage_Load event.
    NOTE: This code retrieves the EmployeeID (i.e. master record primary key) value from the QueryString and sets each tab's TargetURL property so that each Detail table panel within the tabs retrieves the related Detail records.
    NOTE: When navigating from a ShowTable page to an EditRecord page where the primary key value for the record is passed in the URL, the default URL parameter name is the same name as the table. In this case, the table name is Employees.


    Private Sub MyPage_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.Load
      If (Not Me.IsPostBack) Then
        Dim empID As String = Request.QueryString("Employees")
        UltraWebTab1.Tabs.FromKeyTab("Territories").ContentPane.TargetUrl = _
          "../EmployeeTerritories/Territories.aspx?EmployeeID=" & empID
        UltraWebTab1.Tabs.FromKeyTab("Orders").ContentPane.TargetUrl = _
          "../Orders/Orders.aspx?EmployeeID=" & empID
        ...
     


  18. Build and close your application. Open your application in Iron Speed Designer.
  19. Do steps 6 - 13 in the first section "Creating a Header ..." with the appropriate file names etc. from this example.
  20. Build and run the app (see Figure 8). Whew ... you're done!
Binding to a WebGrid
The Infragistics WebGrid is a very powerful grid control that can be bound to a variety of data source types including a DataTable. The DataTable can be easily created from the GetList method of Iron Speed Designer's TableAccess class (see the Code Customization Wizard topic, "Creating a DataTable Object"). This is fine and easy to accomplish for read-only purposes. However, it gets fairly complex when you attempt to update data from the WebGrid with this approach. Consequently, when I use the WebGrid control (seldom), I simply redirect to an AddRecord or EditRecord page, from the selected WebGrid row, to update data.
Tip: Upgrading to a New Version of Infragistics Controls
Here's a tip that will save you a great deal of frustration. Infragistics provides a wonderful utility to upgrade your Visual Studio .NET project to a new version of Infragistics controls. Primarily, it updates the Register tags in your .aspx pages with the new assembly name etc. So, guess what happens when you open your application in Iron Speed Designer and build it. The HTML template source files for all your pages, which contains the "old" Register tag overwrites the HTML of your .aspx pages that the Infragistics utility just fixed. Thus, you end up back at square one. So, be sure to copy the "new" Register tag from the ASPX view and replace the "old" one in the HTML view for all your pages that contain Infragistics controls.
Conclusion
Although this article has focused on Infragistics controls, other third-party controls can be implemented similarly. Iron Speed Designer provides an extensible open architecture to enhance your applications with virtually any style or functionality. Also, check out the Iron Speed Designer Knowledge Base "Using Third Party Controls" for additional information. Although the above screen shot examples have not been formatted completely, Infragistics controls have extensive formatting capabilities. Now, if only Infragistics would release the same "Outlook" type (i.e. calendar, task, etc.) controls for ASP.NET apps that they currently have for Win Forms apps, then I would be a truly happy camper.
About The Author
Michael Sumption is President and CEO of GovIS, LLC, a software development, training, and consulting firm in Northern California. Michael has been developing applications with Infragistics controls for 3+ years and has been using Iron Speed Designer for over a year.


       Copyright © 2005-2008, Iron Speed, Inc. Iron Speed® is a registered trademark. All rights reserved. Privacy Statement