User Interface

We continue discussion of business rules started with posts about RowBuilder attribute. We will create a method that will handle processing of employee territories that were check-marked by user in editForm1.

Field Territories  is a placeholder field of String type. Business rule method PrepareExistingEmployeeRow() retrieves a list of territories that an employee is responsible for.

Now it is time to implement saving of new checked territories and deletion of unchecked ones.

Handling of Custom Fields

We will need two methods in our business rule class to process Territories field value.

First method will hide that fact of changes to Territories field value from Data Aquarium Framework.

C#:

[ControllerAction("Employees", "editForm1", "Update", ActionPhase.Before)]
protected void BeforeEmployeeUpdate(int employeeId, 
    FieldValue territories, FieldValue lastName)
{
    territories.Modified = false;
    lastName.Modified = true;
}

VB:

<ControllerAction("Employees", "editForm1", "Update", ActionPhase.Before)> _
Protected Sub BeforeEmployeeUpdate(ByVal employeeId As Integer, _
    ByVal territories As FieldValue, ByVal lastName As FieldValue)
    territories.Modified = False
    lastName.Modified = True
End Sub

The name of the method implies that we want this method to execute just before an employee update. But method name means nothing to the framework. Data Aquarium Framework relies on attribute ControllerAction to decide if it has to invoke a business rule method.

Our ControllerAction attribute specifies that method BeforeEmployeeUpdate() shall execute when command Update is issued in form editForm1 of data controller Employees. There is also an execution phase information. We want this method to be invoked before the framework tries to perform an update.

There are three parameters: employeeId, territories, and lastName.

Data Aquarium Framework assumes that parameter names are matching the values of data fields specified for editForm1 in the data controller descriptor ~/Controllers/Employees.xml.

The native data field value information is held in FieldValue class instances. If you specify a parameter of type FieldValue then you gain access to its properties OldValue, NewValue, Value, and Modified.

If you don't care about the nature of changes of the field then you can simply specify an exact type that is matched to the data field definition in data controller descriptor.

We know that employeeId has not changed and that is why we specify System.Int32 as the type of the field. We do want to perform certain manipulations with the state of changes to territories and lastName fields. That requires FieldValue type.

The order of the fields and name capitalization does not have to match the definitions in data controller descriptor. Specify only the fields that you need.

The first line of the method resets Modified property to hide any field changes. Here is how Territories field was defined in data controller descriptor:

        <command id="command1" type="Text">
            <text>
                <![CDATA[
select
    "Employees"."EmployeeID" "EmployeeID"
    ,"Employees"."LastName" "LastName"
    ,"Employees"."FirstName" "FirstName"
. . . . . . . . . . . . . . . . . 
    ,"ReportsTo"."LastName" "ReportsToLastName"
    ,"Employees"."PhotoPath" "PhotoPath",
    ,null "Territories" <<< Territories Field Definition
from "dbo"."Employees" "Employees"
    left join "dbo"."Employees" "ReportsTo" on 
        "Employees"."ReportsTo" = "ReportsTo"."EmployeeID"
]]>
            </text>
        </command>

We are returning null as a field value. The field is not based on any actual database table field. The framework does not know that and will try to update null with a new value. Resetting Modified property to false will prevent any update attempts that would happen by default otherwise.

We do want the framework to perform an SQL update for any other fields that might have changed. If the only field that have changed is Territories then no update will be performed. That is why we always "pretend" that field lastName has been changed. An alternative is to write more code and execute an update on our own. You will have to call PreventDefault() method of your business rules class to prevent any default update logic from execution if you do your own updates.

Post-Action Business Logic

Here is how we will update the territories that an employee is responsible for.

C#:

[ControllerAction("Employees", "editForm1", "Update", ActionPhase.After)]
protected void AfterEmployeeUpdate(FieldValue territories, int employeeId)
{
    string[] newTerritories = 
        Convert.ToString(territories.NewValue).Split(',');
    string[] oldTerritories = 
        Convert.ToString(territories.OldValue).Split(',');
    // remove "unchecked" territories
    foreach (string territoryId in oldTerritories)
        if (!(String.IsNullOrEmpty(territoryId)) && 
            (Array.IndexOf(newTerritories, territoryId) == -1))
        {
            EmployeeTerritories et = 
                EmployeeTerritories.SelectSingle(employeeId, territoryId);
            et.Delete();
        }
    // add new "checked" territories
    foreach (string territoryId in newTerritories)
        if (!(String.IsNullOrEmpty(territoryId)) && 
            (Array.IndexOf(oldTerritories, territoryId) == -1))
        {
            EmployeeTerritories et = new EmployeeTerritories();
            et.EmployeeID = employeeId;
            et.TerritoryID = territoryId;
            et.Insert();
        }
}

VB:

<ControllerAction("Employees", "editForm1", "Update", ActionPhase.After)> _
Protected Sub AfterEmployeeUpdate(ByVal territories As FieldValue, _
    ByVal employeeId As Integer)
    Dim newTerritories As String() = _
        Convert.ToString(territories.NewValue).Split(",")
    Dim oldTerritories As String() = _
        Convert.ToString(territories.OldValue).Split(",")
    ' remove "unchecked" territores
    For Each territoryId In oldTerritories
        If Not String.IsNullOrEmpty(territoryId) AndAlso _
            Array.IndexOf(newTerritories, territories) = -1 Then
            Dim et As EmployeeTerritories = _
                EmployeeTerritories.SelectSingle(employeeId, territoryId)
            et.Delete()
        End If
    Next
    ' add new "checked" territories
    For Each territoryId In newTerritories
        If Not String.IsNullOrEmpty(territoryId) AndAlso _
            Array.IndexOf(oldTerritories, territories) = -1 Then
            Dim et As EmployeeTerritories = New EmployeeTerritories()
            et.EmployeeID = employeeId
            et.TerritoryID = territoryId
            et.Insert()
        End If
    Next
End Sub

Parameter territories is defined as a variable of type FieldValue since we want to know the previous value of the field. We split new and old value of the field by comma.

Next we scan old territories and if any territory is not in the list of new ones then we delete the territory with the help of EmployeeTerritories class that was automatically generated for us by ASP.NET code generator Code OnTime Generator.

Finally we scan new territories and for any "new" territories that were not in the list of old ones we are executing an employee territory insertion. Again we do that we the help of automatically generated business object EmployeeTerritories.

Conclusion

A simple and easy to understand server programming model for business rules is a crown jewel of Data Aquarium Framework.  Business rules are built on top custom action handlers and provide a truly simple and easy to use programming mode to enhance your AJAX ASP.NET application with server code.

In our next post we will discuss programmatic data filtering via business rules.

The latest update to Data Aquarium Framework introduces two new properties, StartCommandName and StartCommandArgument. You can use these properties to start a DataViewExtender instance in the desired mode by forcing it to execute a command just before the view is rendered in a web browser.

Quick Sample

Create a new page ~/NewProduct.aspx in a project generated with our ASP.NET Code Generator.

<%@ Page Title="" Language="C#" MasterPageFile="~/MasterPage.master" 
    AutoEventWireup="true" CodeFile="NewProduct.aspx.cs" Inherits="NewProduct" %>

<asp:Content ID="Content1" ContentPlaceHolderID="head" runat="Server">
</asp:Content>
<asp:Content ID="Content2" ContentPlaceHolderID="Header1Placeholder" runat="Server">
    New Product
</asp:Content>
<asp:Content ID="Content3" ContentPlaceHolderID="Header2Placeholder" runat="Server">
    Northwind
</asp:Content>
<asp:Content ID="Content4" ContentPlaceHolderID="BodyPlaceholder" runat="Server">
    <div id="Products" runat="server" />
    <aquarium:DataViewExtender ID="ProductsExtender" runat="server" 
        TargetControlID="Products" 
        Controller="Products" View="createForm1" 
        StartCommandName="New" StartCommandArgument="createForm1" />
</asp:Content>

If you were to omit two last attributes in DataViewExtender markup then a read-only view of the first record of your data controller command is displayed. The framework treats all views the same way - there is no magic in "createForm1" name. The client engine will simply select the first record and present it in a specified view.

A client-side command "New" must be executed to force a display of a new record in createForm1. New properties will do the trick.

Client-Side State Machine

Another great feature available to developers is the client-side action state machine.

Run sample described above and then create a new record. As soon as a record is inserted you will be redirected to the "grid" view of all products. The same happens if you press Cancel button.

Suppose you want to use Cancel button to simply reset the form to the original "new" state. Also you want to rename button OK to Save and have it display a newly inserted record in "preview" mode that will lead to some fictitious step 2. A new button Save and New will create a new record and switch to the "new" mode right after a new record is created.

Open ~/Controllers/Products.aspx and change action group with scope "Form" as shown below.

<actionGroup scope="Form">
    <!-- modified actions -->
    <action whenLastCommandName="Select" whenLastCommandArgument="editForm1" 
            commandName="Edit" />
    <action whenLastCommandName="Select" whenLastCommandArgument="editForm1" 
            commandName="Delete" confirmation="Delete?" />
    <action whenLastCommandName="Select" whenLastCommandArgument="editForm1" 
            commandName="Cancel" headerText="Close" />
    <!-- no changes -->
    <action whenLastCommandName="Edit" commandName="Update" headerText="OK" />
    <action whenLastCommandName="Edit" commandName="Delete" confirmation="Delete?" />
    <action whenLastCommandName="Edit" commandName="Cancel" />
    <!-- modified actions -->
    <action whenLastCommandName="New" commandName="Insert" commandArgument="ShowProduct" 
            headerText="Save" />
    <action whenLastCommandName="New" commandName="Insert" commandArgument="SaveAndNew" 
            headerText="Save and New"/>
    <action whenLastCommandName="New" commandName="New" commandArgument="createForm1" 
            headerText="Cancel" confirmation="Do you want to reset this form?"/>
    <action whenLastCommandName="Insert" whenLastCommandArgument="ShowProduct" 
            commandName="Select" commandArgument="createForm1"/>
    <action whenLastCommandName="Insert" whenLastCommandArgument="SaveAndNew" 
            commandName="New" commandArgument="createForm1"/>
    <action whenLastCommandName="Select" whenLastCommandArgument="createForm1" 
            commandName="Navigate" commandArgument="~/Default.aspx?ProductID={ProductID}" 
            headerText="Continue to Step 2"/>
    <action whenLastCommandName="Select" whenLastCommandArgument="createForm1" 
            commandName="Cancel"/>
</actionGroup>

You probably noticed that new attribute whenLastCommandArgument is used to filter actions and complements attribute whenLastCommandName.

Action Insert creates a new record and in a case of success will try to select an action that is matched to the last command and argument. Pairs command/argument with values Insert/ShowProduct and Insert/SaveAndNew will trigger automatic execution of commands Select/createForm1 and New/createForm1.

Server-side actions Insert, Update, Delete, and any custom actions are forcing the state machine to execute if command has been successfully completed and server code did not request redirect or client script execution.

Here is how the screen looks when you refresh ~/NewProduct.aspx.

Enter details of a new product and click Save button. Product review form is presented.

If you click on Continue to Step 2 then you will be redirected to a URL that looks similar to the one below:

http://localhost:50689/NewFeatures/Default.aspx?ProductID=140

Hiding View Selector

The "orange" view selector at the top may spoil your view workflow ideas. Modify the content Content1 as shown below:

<asp:Content ID="Content1" ContentPlaceHolderID="head" runat="Server">
<style type="text/css">
    table.ViewSelector {
        display:none;
    }
</style>

The view selector will be hidden from users.