Add a Parametrized Action

• Jan 25, 2021
• 4 minutes to read

This lesson explains how to add a Parametrized Action. The Parametrized Action displays an editor that allows users to input a value (that is a parameter) before running the action.

In this lesson, you will implement a new View Controller and add a new Parametrized Action to it. This Action will search for a DemoTask object by its Subject property value, and display the found object on a detail form.

Note

Before you proceed, take a moment to review the previous lessons.

• Inherit from the Business Class Library Class (XPO)
• Initialize a Property After Creating an Object (XPO)
• Add a Simple Action

Step-by-Step Instructions

1. Add a new View Controller to the MySolution.Module project, as described in the Add a Simple Action lesson. Name it FindBySubjectController.

2. Open the newly created MySolution.Module | Controllers | FindBySubjectController.cs file and specify the controller options:

   C#

   public partial class FindBySubjectController : ViewController {
       public FindBySubjectController() {
           InitializeComponent();
   
           TargetViewType = ViewType.ListView;
           TargetViewNesting = Nesting.Root;
           TargetObjectType = typeof(DemoTask);
       }
       // ...
   }
   

3. Add a Parametrized Action and handle its Execute event:

   C#

   public partial class FindBySubjectController : ViewController {
       public FindBySubjectController() {
           InitializeComponent();
           TargetViewType = ViewType.ListView;
           TargetViewNesting = Nesting.Root;
           TargetObjectType = typeof(DemoTask);
   
           ParametrizedAction findBySubjectAction =
               new ParametrizedAction(this, "FindBySubjectAction", PredefinedCategory.View, typeof(string)) {
                   Caption = "Find Task By Subject",
                   ImageName= "Action_Search"
               };
           findBySubjectAction.Execute += FindBySubjectAction_Execute;
       }
       private void FindBySubjectAction_Execute(object sender, ParametrizedActionExecuteEventArgs e) {
           var objectType = ((ListView)View).ObjectTypeInfo.Type;
           IObjectSpace objectSpace = Application.CreateObjectSpace(objectType);
           string paramValue = e.ParameterCurrentValue as string;
           object obj = objectSpace.FindObject(objectType, 
               CriteriaOperator.Parse("Contains([Subject], ?)",  paramValue));
           if(obj != null) {
               DetailView detailView = Application.CreateDetailView(objectSpace, obj);
               detailView.ViewEditMode = DevExpress.ExpressApp.Editors.ViewEditMode.Edit;
               e.ShowViewParameters.CreatedView = detailView;
           }
       }
   // ...
   }
   

4. Run the application.

   Select the Task item in the navigation control (the Find Task by Subject editor is the Action you implemented). Type a word from an existing DemoTask object’s Subject property into this editor and press Enter. A detail form with this object is displayed.

   

Detailed Explanation

Controller Settings

To enable the FindBySubjectController with its FindBySubjectAction only for DemoTask List Views, specify the following properties:

• Set the ViewController.TargetViewType property to “ListView”
• Set the ViewController.TargetObjectType to MySolution.Module.DemoTask

Set the ViewController.TargetViewNesting property to Root to activate the Controller only for root Views.

Action Settings

Handle the Action’s ParametrizedAction.Execute event to implement the search functionality.

The Execute event is raised after a user submits a parameter in the Action’s editor. The handler implemented in this lesson looks for the DemoTask object whose subject contains the text specified as a parameter, and invokes the detail form for this object.

Use the event handler’s ParametrizedActionExecuteEventArgs.ParameterCurrentValue property to get the action parameter.

Search Implementation

In XAF, you use the Object Space to query and update persistent objects. In this lesson, you call the static XafApplication.CreateObjectSpace method to create an Object Space.

Use the IObjectSpace.FindObject method to find a DemoTask object. This method gets the following parameters:

• The type of the objects represented in the current List View. Use the View’s object type info (see View.ObjectTypeInfo).
• Search criteria. To generate a criteria, create a BinaryOperator object and pass criteria components as the constructor’s parameters. For more information, refer to the following XPO documentation: Simplified Criteria Syntax.

Create a New View

To show the found object in a separate Detail View do the following:

• Create a View (call the XafApplication.CreateDetailView method)
• Assign the View to the ShowViewParameters.CreatedView property of the event handler’s ActionBaseEventArgs.ShowViewParameters parameter.

Tip

You can initialize the ShowViewParameters property in the Execute event handler of any Action of any type. This allows you to always show a View after an Action is executed.

For more information on how to show a View in a separate window, refer to the following topic: Ways to Show a View.

Manage an XAF Application

The XafApplication object is useful when you need to create a List View, Detail View, Object Space, etc. The XafApplication object is accessible from many locations in an XAF application. In Controllers, it can be accessed via the Controller.Application property.

Next Lesson

Add an Action that Displays a Pop-up Window