Integrating Business Objects with a Web Form

One of the main reasons you use business objects on a Web Form is to retrieve, manipulate, and save data. Part of this process includes binding data returned from business objects to Web Form controls. Setting up intelligent data binding in a Web Form requires three simple steps:

Register one or more business objects with the Web Form.
Add code to the form that calls business object methods to retrieve data.
Specify binding properties on Web controls.

The following sections describe these steps in detail.

Step 1: Registering Business Objects with a Web Form

Business objects are used on Web forms to retrieve and update data. If you want to bind user interface controls to data retrieved by a business object, you must first register that business object with the form.

Note: You must always register a business object in the Page_Load of an MM .NET Web Form. This ensures the business object is registered before any user interface controls instantiate.

For example, in C#:

using OakLeaf.MMTest.Business;

namespace OakLeaf.MMTest.Web.UI
{
	/// <summary>
	/// Employee Web Form
	/// </summary>
	public class CustomerOrdersForm : mmBusinessWebPage
	{
		protected Orders oOrder;
		protected OrderDetail oOrderDetail;

		private void Page_Load(object sender, System.EventArgs e)
		{
			this.oOrder = (Orders)this.RegisterBizObj(new Orders());
			this.oOrderDetail = (OrderDetail)this.RegisterBizObj(new OrderDetail());
		}
	}
}

In VB .NET:

Imports OakLeaf.MMTest.Business

Namespace OakLeaf.MMTest.Web.UI
 
   ' Employee Web Form
   Public Class CustomerOrdersForm
      Inherits mmBusinessWebPage
      Protected oOrder As Orders
      Protected oOrderDetail As OrderDetail
      
      Private Sub Page_Load(sender As Object, e As System.EventArgs)
         Me.oOrder = CType(Me.RegisterBizObj(New Orders()), Orders)
        Me.oOrderDetail = CType(Me.RegisterBizObj(New OrderDetail()), OrderDetail)
      End Sub 'Page_Load

   End Class

End Namespace

Note the following about this code:

This code instantiates an Orders and OrderDetail business objects in the Page_Load method and registers them with the form.
References to the business objects are stored in a form-level protected fields. This makes it easy to reference the business objects from other methods on the form.
A namespace has been added to reference the business object classes.

Checking IsPostBack

In the above code sample, the business objects are instantiated every time the form is loaded. Remember that a Web form is loaded when you first navigate to it, and is loaded again if it is posted back to the server (for example, by means of a Submit or Save button).

However, depending on how your Web form is designed to work, you may only need the business object when the form is posted back, or vice-versa. If this is the case, you can simply check the value of IsPostBack in the Page_Load method before instantiating the business object. For example, in the following code, the business objects are only instantiated and registered when the Web form is posted back:

protected Orders oOrder;
protected OrderDetail oOrderDetail;
	
private void Page_Load(object sender, System.EventArgs e)
{
	if (IsPostBack)
	{
		this.oOrder = (Orders)this.RegisterBizObj(new Orders());
		this.oOrderDetail = (OrderItem)this.RegisterBizObj(new OrderDetail());
	}
}

In VB .NET:

Protected oOrder As Orders
Protected oOrderDetail As OrderDetail

Private Sub Page_Load(sender As Object, e As System.EventArgs)
   If IsPostBack Then
      Me.oOrder = CType(Me.RegisterBizObj(New Orders()), Orders)
      Me.oOrderDetail = CType(Me.RegisterBizObj(New OrderDetail()), OrderDetail)
   End If
End Sub

Step 2: Retrieving Data using Business Objects

Once you've registered your business objects, you can add code to the Web form that calls business object methods to retrieve data. If you need data to be available when first navigating to the page, you can place code in the Page_Load method to retrieve the data. For example, the following code first calls Request.QueryString to retrieve the value of the orderID parameter passed to the page. It next instantiates and registers the business objects, then afterwards it retrieves the order header and order detail for the specified order.

In C#:

private void Page_Load(object sender, System.EventArgs e)
{
	// Get the Order ID
	int OrderID = int.Parse(Request.QueryString["orderID"]);

	// Instantiate and register the business objects
	this.oOrder = (Orders)this.RegisterBizObj(new Orders());
	this.oOrderDetail = (OrderDetail)this.RegisterBizObj(new OrderDetail());
	
	if (!IsPostBack)
	{
		// Get the Order Header and Order Detail
		DataSet dsOrder = this.oOrder.GetOrderByOrderID(OrderID);
		DataSet dsOrderDetail = this.oOrderDetail.GetOrderDetail(OrderID);
	}
}

And in VB .NET:

Private Sub Page_Load(sender As Object, e As System.EventArgs)

   ' Get the Order ID
   Dim OrderID As Integer = Integer.Parse(Request.QueryString("orderID"))

   ' Instantiate and register the business objects
   Me.oOrder = CType(Me.RegisterBizObj(New Orders()), Orders)
   Me.oOrderDetail = CType(Me.RegisterBizObj(New OrderDetail()), OrderDetail)
   
   If Not IsPostBack Then
      ' Get the Order Header and Order Detail
      Dim dsOrder As DataSet = Me.oOrder.GetOrderByOrderID(OrderID)
      Dim dsOrderDetail As DataSet = Me.oOrderDetail.GetOrderDetail(OrderID)
   End If
End Sub

Alternately, if you want to retrieve data in response to a user selection, you can place code in an event handler to retrieve the data. For example, the following code instantiates and registers the Orders business object in the Page_Load method if the form is being posted back. Afterwards, the btnGetOrders_Click event handler runs and it calls the business object's GetOrdersByCustomerID method to retrieve all orders for the specified customer. Notice this method gets the customer ID from a textbox on the form.

In C#:

private void Page_Load(object sender, System.EventArgs e)
{
	if (IsPostBack)
	{
		this.oOrder = (Orders)this.RegisterBizObj(new Orders());
	}
}

private void btnGetOrders_Click(object sender, System.EventArgs e)
{
	// Retrieve orders for the specified customer
	this.oOrder.GetOrdersByCustomerID(this.txtCustomerID.Text);
}

And in VB .NET:

Private Sub Page_Load(sender As Object, e As System.EventArgs)
   If IsPostBack Then
      Me.oOrder = CType(Me.RegisterBizObj(New Orders()), Orders)
   End If
End Sub

Private Sub btnGetOrders_Click(sender As Object, e As System.EventArgs)
   ' Retrieve orders for the specified customer
   Me.oOrder.GetOrdersByCustomerID(Me.txtCustomerID.Text)
End Sub

Step 3: Binding Web Controls to Data

Although you can manually write code that binds your Web controls to data returned from business objects, all MM .NET Web Forms controls contain properties you can set that automatically bind the control to data. You can use the integrated MM .NET Binding Source and Binding Source Member builders to easily set these properties.

Here is the Binding Source dialog. It allows you to specify a business object that you want to bind a Web control to:

You launch this dialog at design time, by selecting an MM .NET Web control on your Web Form, going to the Properties Window and selecting the BindingSource property. This displays an ellipses button next to the property that you click to launch the dialog:

Here is the Binding Source Member dialog. It allows you to specify which data member loaded by the business object you want to bind a Web Control to:

You launch this dialog at design time, by selecting an MM .NET Web control on your Web Form, going to the Properties Window and selecting the BindingSourceMember property. This displays an ellipses button next to the property that you click to launch the dialog:

Note: For more information on binding properties and using these dialogs, see the Help topic Data Binding MM .NET Web Forms Controls.

Saving DataSets using Business Objects

You can use a business object's SaveDataSet method to save data from an MM .NET Web form.

Here is a typical scenario:

You retrieve data in the Page_Load of a Web form by calling a business object method. Typically, you should persist this data (for example, in a Session variable) so when you later save the data, MM .NET can determine if another user has changed the original data.

Here's an example in C#:

private void Page_Load(object sender, System.EventArgs e)
{
	// Instantiate and register the Orders business object
	this.oOrder = (Orders)this.RegisterBizObj(new Orders());

	// Retrieve the specified order and save it in a Session variable
	Session["dsOrder"] = this.oOrder.GetOrderByOrderID(OrderID);
}

And in VB .NET:

Private Sub Page_Load(sender As Object, e As System.EventArgs)
   ' Instantiate and register the Orders business object
   Me.oOrder = CType(Me.RegisterBizObj(New Orders()), Orders)
   
   ' Retrieve the specified order and save it in a Session variable
   Session("dsOrder") = Me.oOrder.GetOrderByOrderID(OrderID)
End Sub

Note: Although we are using the Session object in this example to save user state, you can also use the ASP.NET Cache object instead when you have a user ID that can be used to uniquely identify each user. See the MM .NET Help topic Persisting User State for details.

After the Page_Load method executes, when Web controls bound to this business object instantiate, they display the data retrieved by the business object.
The user changes the values in the Web controls.

The user clicks a Submit button which fires an event handler containing code that retrieves the original data stored in the Session variable. This data as well as a reference to the Orders business object is then passed to the form's Save method. Within this method a call is made to the business object's SaveDataSet method which raises a Saving event to which all Web controls bound to the business object respond. The controls take their data and store it in the business object's current DataSet.

Here's an example in C#:

private void btnSave_Click(object sender, System.EventArgs e)
{
	//  Retrieve the original DataSet from the Session variable
	DataSet dsOrder = (DataSet)Session["dsOrder"];

	// Call the Web Form's Save method, passing the business object and the original data.
	// The business object raises a Saving event and all bound Web controls
	// bind their data back into the DataSet
	if (this.Save(this.oOrder, dsOrder, this.oOrder.TableName) ==
		mmSaveDataResult.RulesPassed)
	{
		Response.Redirect("CustomerOrders.aspx");
	}
}

And in VB .NET:

Private Sub btnSave_Click(sender As Object, e As System.EventArgs)
    '  Retrieve the original DataSet from the Session variable
    Dim dsOrder As DataSet = CType(Session("dsOrder"), DataSet)

    ' Call the Web Form's Save method, passing the business object and the original data.
    ' The business object raises a Saving event and all bound Web controls
    ' bind their data back into the DataSet
    If Me.Save(Me.oOrder, dsOrder, Me.oOrder.TableName) = mmSaveDataResult.RulesPassed Then
       Response.Redirect("CustomerOrders.aspx")
    End If
End Sub