Add a Parametrized Action (.NET Framework)

• Sep 09, 2022
• 5 minutes to read

Tip

For .NET 6 applications, see: Add a Parametrized Action (.NET 6).

In this lesson, you will learn how to add a Parametrized Action. These types of Actions are slightly more complex than the Simple Actions you learned about in the previous lesson. The Parametrized Action provides an editor, so that an end-user can input a value before execution. In this lesson, a new View Controller will be implemented and a new Parametrized Action will be added 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 proceeding, take a moment to review the following lessons:

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

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

• Right-click the newly created MySolution.Module | Controllers | FindBySubjectController.cs (FindBySubjectController.vb) file, and choose View Designer to invoke the Designer. Drag ParametrizedAction from the DX.22.1: XAF Actions Toolbox tab to the Designer. In the ParametrizedAction Properties window, set the Name and ID properties to “FindBySubjectAction”, and set the Caption property to “Find Task by Subject”.

  

• To activate the FindBySubjectController with its FindBySubjectAction for DemoTask List Views only, set the ViewController.TargetViewType property to “ListView”, and set ViewController.TargetObjectType to MySolution.Module.DemoTask via the Controller’s Properties window. To activate the Controller for root Views only, set the ViewController.TargetViewNesting property to Root.

  

• Next, you need to handle the Action’s ParametrizedAction.Execute event to implement the search functionality. Focus the FindBySubject Action in the Controller’s Designer. Switch to the Events view in the Properties window. Double-click the Execute event, replace the auto-generated event handler code with the following.

  C#

  private void FindBySubjectAction_Execute(object sender, ParametrizedActionExecuteEventArgs e) {
      IObjectSpace objectSpace = Application.CreateObjectSpace(((ListView)View).ObjectTypeInfo.Type);
      string paramValue = e.ParameterCurrentValue as string;
      object obj = objectSpace.FindObject(((ListView)View).ObjectTypeInfo.Type,
          CriteriaOperator.Parse(string.Format("Contains([Subject], '{0}')", paramValue)));
      if(obj != null) {
          DetailView detailView = Application.CreateDetailView(objectSpace, obj);
          detailView.ViewEditMode = DevExpress.ExpressApp.Editors.ViewEditMode.Edit;
          e.ShowViewParameters.CreatedView = detailView;
      }
  }
  

  VB.NET

  Private Sub FindBySubjectAction_Execute(ByVal sender As Object, ByVal e As ParametrizedActionExecuteEventArgs)
      Dim objectSpace As IObjectSpace = Application.CreateObjectSpace(CType(View, ListView).ObjectTypeInfo.Type)
      Dim paramValue As String = TryCast(e.ParameterCurrentValue, String)
      Dim obj As Object = objectSpace.FindObject(CType(View, ListView).ObjectTypeInfo.Type, CriteriaOperator.Parse(String.Format("Contains([Subject], '{0}')", paramValue)))
      If obj IsNot Nothing Then
          Dim detailView As DetailView = Application.CreateDetailView(objectSpace, obj)
          detailView.ViewEditMode = DevExpress.ExpressApp.Editors.ViewEditMode.Edit
          e.ShowViewParameters.CreatedView = detailView
      End If
  End Sub
  

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

  Note

  • To search for an object, you will need an Object Space. The Object Space is always used when manipulating persistent objects. To use the Object Space in this task, create it using the XafApplication.CreateObjectSpace method. Since an application is accessible nearly everywhere in code, its CreateObjectSpace method is always helpful.
  • To use the IObjectSpace.FindObject method, pass the type of the searched object, along with its criteria. To get the type of the objects represented in the current List View, use the View’s object type info (see View.ObjectTypeInfo). To generate a criterion, create a BinaryOperator object by passing criteria components as the constructor’s parameters. For additional information, refer to the Querying a Data Store section in the XPO documentation.
  • To get the value entered by an end-user in the editor that represents the FindBySubjectAction, use the event handler’s ParametrizedActionExecuteEventArgs.ParameterCurrentValue parameter.
  • To show the found object in a separate Detail View, create the View via the XafApplication.CreateDetailView method and assign it to the ShowViewParameters.CreatedView property of the event handler’s ActionBaseEventArgs.ShowViewParameters parameter. Show View Parameters can be initialized in the Execute event handler of an Action of any type, so you can always show a View after Action execution. For additional information on how to show a View in a separate window, refer to the Ways to Show a View topic.
  • As you may have already noticed, 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.

• Run the WinForms or ASP.NET Web Forms application. Select the Task item in the navigation control. Find the Find Task by Subject editor that represents the Action you have implemented. Type a word from an existing DemoTask object’s Subject property into this editor. Press the Enter key or click Find Task by Subject. A detail form with this object will be displayed.

  

You can see the code demonstrated here in the MySolution.Module | Controllers | FindBySubjectController.cs (FindBySubjectController.vb) file of the Main Demo installed with XAF. The MainDemo application is installed in %PUBLIC%\Documents\DevExpress Demos 22.1\Components\XAF\MainDemo by default. The ASP.NET Web Forms version is available online at https://demos.devexpress.com/XAF/MainDemo.

 

Next Lesson: Add an Action that Displays a Pop-up Window