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.
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 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.
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.
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.
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.
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.
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.
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.