Saturday, April 21, 2012

Complex Action Confirmations

Application business requirements may specify actions demanding user-defined values. Field values of a selected data record are not sufficient to complete such actions.

Consider the example of implementing a custom business logic with “SQL” action. The example explains how to create a Standard Discount action that can be executed on any order in the Northwind sample application. The action will increment the discount of line items of a selected order by 1%.

The screen shot shows the application in action.

A custom action in the group with 'Grid' scope in a web app created with Code On Time application generator

The properties of the action are defined as follows.

Property Value
Command Name SQL
Header Text Standard Discount
Data
update "Order Details"
set Discount = 0
where 
    OrderID = @OrderID and Discount = 0.1
    
update "Order Details"
set Discount = cast(Discount as decimal(3,2)) + 0.01
where 
    OrderID = @OrderID and Discount < 0.1
Confirmation The discount will be increased by 1%.

If the action is selected then a simple confirmation is displayed.

A simple action confirmation in a web app created with Code On Time

A more flexible implementation of this action would allow a user to enter the exact discount that will apply to order line items. Let’s implement a confirmation that will allow capturing the discount and have it passed to the action implementation.

Start the application generator and click on the project name, click Design to activate the Project Designer. Select the Controllers tab in Designer and choose New | New  Controller option on the action bar.

Creating a new data controller in a Code On Time web application

Enter the following property values and click OK button.

Property Value
Name DiscountDialog

Right-click the DiscountDialog / Fields node on the Controllers tab in Project Explorer and select the New Field option.

Adding a new field to a data controller

Enter the following property values and click OK button to save the new field.

Property Value
Name Discount
Type Double
Code Default 0.01
Label Discount
Data Format String p

Our “confirmation” data controller is ready.

Select Orders / Actions / ag1 (Grid) / a100 – SQL | Standard Discount action node on the Controllers tab in Project Explorer.

Action with command name 'SQL' selected in Project Explorer

Change the action properties and click OK button.

Property New Value
Header Text Apply Discount
Data
update "Order Details"
set Discount = @Parameters_Discount
where 
    OrderID = @OrderID
Confirmation

_controller=DiscountDialog
_title=Apply Discount to Order Details
_width=500

Click Browse on the Project Designer toolbar to have the application generated. The home page of the app will open in the default web browser. Navigate to the Orders page and select Apply Discount option in the context menu of an order.

The modal form view will display. Enter a discount and click OK button to execute the action.

 A modal confirmation of 'SQL' action in a web app created with Code On Time web application generator

Any field values entered in the modal action parameter form are accessible in the “SQL” action script if your prefix the field name with “Parameters_”. Our script is referencing the entered Discount as @Parameters_Discout parameter.

If you are writing a custom business rules class or implementing shared business rules then you can reference the action parameter field by name “Parameters_Discount” as you would use any other field of a data controller.

The application client library displays a modal view if you define the confirmation property of the action as a collection of name/value arguments.

The library supports the following arguments. Only the “_controller” attribute is mandatory.

Argument Description
_controller The name of the data controller.
_view The ID of the view that must be activated in the modal popup. If left blank, then the first view of the data controller is activated. Optional.
_commandName The name of the start command. If left blank, then New command is the start command. Optional.
_commandArgument The optional argument of the start command.
_title The title of the action confirmation modal popup. If left blank, then the view label is displayed instead. Optional.
_width The width of the action confirmation modal popup. If left blank, then the default width of 800 is used. If the specified value exceeds 80% of the browser window width, then the popup width will be reduced to that value. Optional

The DiscountDialog controller defines a single field. There are no commands, views, or actions.

A data controller must define one or more fields to be used as an 'action confirmation'

The application framework treats data controllers that do not have a command as virtual controllers. Virtual Data Controllers are not based on a database table or view. The assumption is made that the controller has one data row only.

If the controller does not define its own views or actions then the application framework will complete the controller definition at runtime. This configuration is equivalent to the custom-defined controller shown in the picture.

A minimal 'action confirmation' data controller with custom views and actions

The virtual data controller used for action confirmation is not different from any other data controller based on a real database table or view. You can implement business rules and custom actions that may in turn require other virtual controllers for confirmation.

Developers can apply data controller virtualization techniques to customize the data controller actions at runtime according to the custom workflow requirements. For example, the action properties Data and Confirmation may be stored in a dedicated database table and applied to data controllers based on user identity.

No comments:

You can find more about Code OnTime Generator, Data Aquarium Framework, and other great products here.


© 2010 Code OnTime LLC. Intelligent code generation software for ASP.NET. Visit us at http://codeontime.com