Business Rules/Logic

The following screen shows  a customer record from the Northwind sample presented in edit mode. Suppose that you want to add a button to the form to automatically calculate certain field values.

Start the web application generator and select your project. Click Design to activate the Project Designer.

Activate Controllers tab in the Project Explorer and right-click Customers / Actions / ag2 (Form) node. Choose New Action option to create a new action.

Enter the following properties.

select
  @CompanyName = @CompanyName +  '+',
  @ContactName = @ContactName + '-'

Save the action and click Browse on the Designer toolbar.

Your web application will be displayed in the default web browser. Navigate to the Customers page and start editing any record.

You will notice the Calculate Values button displayed above and below the form fields. Click the button and you will see “+” added to the Company Name field and “-” added to the Contact Name field.

If you press Calculate Values button a few more times then you will see more “+” and “-” characters added to the same fields.

If you cancel the changes then the record will not be updated.

The changes made by SQL action will be persisted if you click OK button.

Action SQL causes the client library to send the current field values to the server. The core application framework knows how to handle this action.

First, the framework will find the text entered in the “Data” property of the action.

Next, it will parse the text to detect any parameters.

If you database server uses another symbol to indicate a parameter, then make sure to enter this symbol instead of “@”.

If the parameters are found then the framework will try to match them to the names of the available data fields. The application will also recognize parameters that have “_Value”, “_NewValue”, and “_OldValue” suffix. If there is a matching data field then the field’s current, new, or old value will be assigned to the parameter.

All parameters are marked as Input/Output parameters.

The application will execute the SQL text. If any parameter values have changed, then they will be packaged and sent back to the client. The client library will reflect the changed values in the user interface as if the application user has entered them in the input text boxes.

It is expected that the SQL text in action’s Data property contains instructions assigning values to parameters that are not matched to the fields. You can use any SQL language constructs supported by your database server as if you were executing them in a tool such as SQL Management Studio.

Consider the following sample data for SQL action:

declare @Temp nvarchar(50)

-- swap City and Country
set @Temp = @City
set @City= @Country
set @Country= @Temp

-- update Company Name
select @CompanyName = @CompanyName + ': ' + City + '/' + Country
from Customers 
where CustomerID = @CustomerID

Enter this text in the Data property of the action and click OK button.

This is the result of action execution if you browse to a customer record, start editing, and push the Calculate Values button.

If you need more than just an interaction with the database to perform a calculation, then consider using custom business rules or shared business rules for implementation. Learn more about implementing calculations with “Custom” action.

Code On Time web applications offer impressive adaptive filtering and search capabilities that require zero programming. Consider the following screen shot from the Northwind sample.

Application user has selected specific categories,

specific suppliers,

a range of prices,

and specific values of product units on order.

A user can remove the filter at will by either clicking on individual filter elements or dismissing the entire filter.

An application developer can also configure a filter based on arbitrary conditions at runtime. The filter can be constructed just before the data is retrieved from the database.  Users will see the filter as if they have selected all options on their own. End users can always cancel or adjust the “soft” filter to reveal more data rows.

This may be useful when a specific data row has to be brought to the application user’s attention.  “Soft” filtering will work even better when combined with the auto highlight first row or auto select first row features.

Enable shared business rules in your web application and enter the following code.

C#:

using System;
using System.Data;
using System.Collections.Generic;
using System.Linq;
using MyCompany.Data;

namespace MyCompany.Rules
{
    public partial class SharedBusinessRules : MyCompany.Data.BusinessRules
    {
        [ControllerAction("Orders", "grid1", "Select", ActionPhase.Before)]
        public void AssignOrdersFilter()
        {
            if (!IsTagged("Filtered"))
            {
                AddTag("Filtered");
                DateTime startDate = new DateTime(1998, 1, 1, 0, 0, 0, DateTimeKind.Utc);
                DateTime endDate = new DateTime(1998, 6, 1, 23, 59, 59, DateTimeKind.Utc);
                AssignFilter(
                    new FilterValue("OrderDate",
                        RowFilterOperation.Between, startDate, endDate),
                    new FilterValue("EmployeeLastName",
                        RowFilterOperation.Equal, "Callahan"),
                    new FilterValue("ShipViaCompanyName",
                        RowFilterOperation.Includes, "Speedy Express", "United Package"),
                    new FilterValue("Freight", 
                        RowFilterOperation.Between, 10, 30)
                );
                Result.ShowViewMessage("A \"soft\" filter has been applied to this list.");
            }
        }
    }
}

Visual Basic:

Imports MyCompany.Data
Imports System
Imports System.Collections.Generic
Imports System.Data
Imports System.Linq

Namespace MyCompany.Rules
    Partial Public Class SharedBusinessRules
        Inherits MyCompany.Data.BusinessRules

        <ControllerAction("Orders", "grid1", "Select", ActionPhase.Before)> _
        Public Sub AssignOrdersFilter()
            If Not IsTagged("Filtered") Then
                AddTag("Filtered")
                Dim startDate As DateTime = New DateTime(1998, 1, 1, 0, 0, 0, DateTimeKind.Utc)
                Dim endDate As DateTime = New DateTime(1998, 6, 1, 23, 59, 59, 
                    DateTimeKind.Utc)
                AssignFilter(
                    New FilterValue("OrderDate",
                        RowFilterOperation.Between, startDate, endDate),
                    New FilterValue("EmployeeLastName",
                        RowFilterOperation.Equal, "Callahan"),
                    New FilterValue("ShipViaCompanyName",
                        RowFilterOperation.Includes, "Speedy Express", "United Package"),
                    New FilterValue("Freight",
                        RowFilterOperation.Between, 10, 30)
                )
                Result.ShowViewMessage("A ""soft"" filter has been applied to this list.")
            End If
        End Sub
    End Class
End Namespace

Save the code file and navigate to the page Orders. The method AssignOrdersFilter will be invoked when the data is about to be retrieved. The method will apply a filter one time only in the lifecycle of the page instance displayed in the web browser to prevent interference with application user actions.

Notice that we are filtering by UTC dates to ensure that Microsoft.NET will not try to compensate for the time difference between the server and the web browser.

In the end, the method will display a view-level message rendered just above the grid view informing the app user about the “soft”- filter.

Select data view Customers/ Orders / container1 / view in the Project Explorer.

If you enable Search On Start in the data view properties then the Orders page will open up with the search bar pre-filled with filter values and no data will be displayed. Users will have to click Search to initiate the retrieval of data.

If you have enabled automatic selection or highlighting of the first row in the properties of the page data view then the view will perform the first action in the context menu of the first data row or simulate a click in the first row. This sort of behavior will happen even if you do not “soft” filter the data.

You can also coincide the selection or highlighting of the first row with the assignment of a “soft” filter in business rules  by calling Result.SelectFirstRow or Result.HightlightFirstRow right after the call of ShowViewMessage method.

For example, this is the effect of Result.HighlightFirstRow method call.

Developers should use access control rules or filter expressions when the application business logic does not permit cancellation of data filters at will by the application users.