Define the Scope of Controllers and Actions

• Sep 25, 2023
• 5 minutes to read

This topic describes how to set conditions for activating Controllers and their Actions.

Specify the Scope of Controllers

Activate or Deactivate a Controller

If you have implemented a Controller that executes code in the Controller.Activated event handler or in the OnActivated and OnViewControlsCreated methods, you might have to define the conditions when this code is executed. For instance, you may need to define that a Controller customizing a grid editor should be active for List Views only. To do this, change the Controller.Active property’s value directly or using one of Controller’s properties listed later in this topic.

The Controller.Active property also affects the visibility of all Actions declared in this Controller (if a Controller is inactive, all its Actions are also inactive). To hide a single Action, you can use the ActionBase class’s properties (see Change the Scope of Actions).

The following members help you specify the required conditions for Controller activation:

Member	Description
Controller.Active	Provides access to a collection of reason/value pairs used to activate or deactivate a Controller or determine its active state. The Controller is active when all items in this collection have the true value. You can add an item with a value representing a conditional expression, so the Controller is deactivated when this expression returns false.
ViewController.TargetObjectType	Specifies the type of objects a View should represent to activate a View Controller.
ViewController.TargetViewId	Specifies the ID of the View for which a View Controller is intended.
ViewController.TargetViewType	Specifies the type of the View for which a View Controller is intended.
ViewController.TargetViewNesting	Specifies whether the View for which a View Controller is intended must be root, nested or any.
WindowController.TargetWindowType	Specifies the kind of the Window for which a Window Controller is intended.

Activate a Controller for Particular Views and Objects

You can inherit your Controller from ViewController<ViewType> or ObjectViewController<ViewType, ObjectType> and use the generic parameters to control for what views and types a View Controller should be activated. The example below demonstrates how to activate a Controller only for the Person class’s Detail View.

C#

public class ViewController1 : ObjectViewController<DetailView, Person> {
    protected override void OnActivated() {
        base.OnActivated();
        Person person = this.ViewCurrentObject;
        DetailView detailView = this.View;
        // ....
    }
}

VB.NET

Public Class ViewController1
    Inherits ObjectViewController(Of DetailView, Person)
    Protected Overrides Sub OnActivated()
        MyBase.OnActivated()
        Dim person As Person = Me.ViewCurrentObject
        Dim detailView As DetailView = Me.View
        ' ....
    End Sub
End Class

Note that the ObjectViewController`2.ViewCurrentObject and ObjectViewController`2.View properties types are changed based on types passed as generic parameters. This may be useful when you want to avoid casting the View Controller’s View to ListView or DetailView. Note that the Visual Studio Designer does not work for Controllers inherited from generic types.

Change the Scope of Actions

When implementing an Action, you may want it to be displayed in a particular form. For instance, a CancelAppointment Action should be displayed for Views representing Appointment object(s) only. There are two approaches to deactivating an Action: deactivating its Controller and deactivating the Action itself.

Deactivate an Action’s Controller

In most cases, you can turn off (deactivate) a Controller in which an Action is declared to hide this Action. If you deactivate a Controller, all its Actions will be invisible. Refer to the Specify the Scope of Controllers section to learn how to do this.

Deactivate an Action Itself

It is also possible to define the target Views and Windows for each Action individually. To do this, use the following properties:

Member	Description
ActionBase.Active	Provides access to a collection of key/value pairs used to determine or change the Action’s active state. The resulting state determines the Action’s visibility.
ActionBase.Enabled	Provides access to a collection of key/value pairs used to determine an Action’s enabled/disabled state. A Disabled Action is visible in the UI, but it is grayed out and cannot be executed.
ActionBase.TargetObjectsCriteria	Specifies a criteria for enabling an Action.
ActionBase.TargetObjectsCriteriaMode	Specifies whether all the currently selected objects must meet the TargetObjectsCriteria criteria to enable an Action.
ActionBase.TargetObjectType	Specifies the type of the object(s) that the current View should represent to activate an Action.
ActionBase.TargetViewId	Specifies the ID of the View for which an Action is intended.
ActionBase.TargetViewNesting	Specifies whether the View for which an Action is intended must be root, nested or any.
ActionBase.TargetViewType	Specifies the type of the View for which an Action is intended.
ActionBase.SelectionDependencyType	Specifies a context for enabling an Action.

These properties control whether an Action is visible in certain Views and Windows. Refer to the ActionBase.Active topic to learn other ways to control visibility state (for example, hide an Action depending on a business object’s property value).

Activate a Controller or Action for Multiple Business Objects or Views

To make a single ViewController or Action available in Views of different business object types simultaneously, consider one of the following solutions:

• Set the ViewController.TargetObjectType property in code to an interface or their base class type, which is implemented or inherited by all these business types respectively.
• Specify several View identifiers (separated with a semicolon ;) via the ViewController.TargetViewId property.
• Manage the Controller.Active or ActionBase.Active properties manually depending on required conditions.