.cursorrules for xaf.md

XAF Actions and Controllers Overview

This document provides a comprehensive guide to Actions and Controllers in XAF, including descriptions and code examples. Every time you choose to apply a rule(s), explicitly state the rule(s) in the output. You can abbreviate the rule description to a single word or phrase.

Actions

Actions in XAF are UI elements (e.g., buttons, menu items) that execute specific logic when triggered by the user. Actions are associated with Controllers and can be customized to fit various scenarios.

Types of Actions

1. SimpleAction

A straightforward Action that executes code when triggered.

Example: SimpleAction Implementation

using DevExpress.ExpressApp; using DevExpress.ExpressApp.Actions;

public class SimpleActionExampleController : ViewController { public SimpleActionExampleController() { SimpleAction simpleAction = new SimpleAction(this, "SimpleActionExample", DevExpress.Persistent.Base.PredefinedCategory.Edit) { Caption = "Perform Action", ToolTip = "This is a SimpleAction example" }; simpleAction.Execute += SimpleAction_Execute; }

private void SimpleAction_Execute(object sender, SimpleActionExecuteEventArgs e) {
    *// Custom logic for the action*
    Application.ShowViewStrategy.ShowMessage("SimpleAction executed!", InformationType.Success);
}

}

2. ParametrizedAction

An Action that accepts user input before execution.

Example: ParametrizedAction Implementation

using DevExpress.ExpressApp; using DevExpress.ExpressApp.Actions;

public class ParametrizedActionExampleController : ViewController { public ParametrizedActionExampleController() { ParametrizedAction parametrizedAction = new ParametrizedAction(this, "ParametrizedActionExample", DevExpress.Persistent.Base.PredefinedCategory.Edit, typeof(string)) { Caption = "Search", ToolTip = "Enter a keyword to search" }; parametrizedAction.Execute += ParametrizedAction_Execute; }

private void ParametrizedAction_Execute(object sender, ParametrizedActionExecuteEventArgs e) {
    string searchTerm = e.ParameterCurrentValue as string;
    if (!string.IsNullOrEmpty(searchTerm)) {
        Application.ShowViewStrategy.ShowMessage($"Searching for: {searchTerm}", InformationType.Info);
    }
}

}

3. SingleChoiceAction

An Action that allows users to select from predefined options.

Example: SingleChoiceAction Implementation

using DevExpress.ExpressApp; using DevExpress.ExpressApp.Actions;

public class SingleChoiceActionExampleController : ViewController { public SingleChoiceActionExampleController() { SingleChoiceAction singleChoiceAction = new SingleChoiceAction(this, "SingleChoiceActionExample", DevExpress.Persistent.Base.PredefinedCategory.Edit) { Caption = "Choose Option", ItemType = SingleChoiceActionItemType.ItemIsOperation };

    singleChoiceAction.Items.Add(new ChoiceActionItem("Option 1", "Option1"));
    singleChoiceAction.Items.Add(new ChoiceActionItem("Option 2", "Option2"));

    singleChoiceAction.Execute += SingleChoiceAction_Execute;
}

private void SingleChoiceAction_Execute(object sender, SingleChoiceActionExecuteEventArgs e) {
    string selectedOption = e.SelectedChoiceActionItem.Data as string;
    Application.ShowViewStrategy.ShowMessage($"You selected: {selectedOption}", InformationType.Info);
}

}

4. PopupWindowShowAction

An Action that displays a pop-up window before execution.

Example: PopupWindowShowAction Implementation

using DevExpress.ExpressApp; using DevExpress.ExpressApp.Actions; using DevExpress.Persistent.Base;

public class PopupWindowShowActionExampleController : ViewController { public PopupWindowShowActionExampleController() { PopupWindowShowAction popupAction = new PopupWindowShowAction(this, "PopupWindowShowActionExample", PredefinedCategory.Edit) { Caption = "Show Popup" }; popupAction.CustomizePopupWindowParams += PopupAction_CustomizePopupWindowParams; popupAction.Execute += PopupAction_Execute; }

private void PopupAction_CustomizePopupWindowParams(object sender, CustomizePopupWindowParamsEventArgs e) {
    e.View = Application.CreateListView(typeof(MyBusinessObject), true);
}

private void PopupAction_Execute(object sender, PopupWindowShowActionExecuteEventArgs e) {
    foreach (var selectedObject in e.PopupWindowViewSelectedObjects) {
        *// Process selected objects*
    }
    Application.ShowViewStrategy.ShowMessage("Popup action executed!", InformationType.Success);
}

}

Controllers

Controllers encapsulate business logic and manage Actions. They can trigger Actions automatically or in response to user interactions.

Types of Controllers

1. ViewController

A Controller that operates on a specific View (e.g., ListView, DetailView).

Example: ViewController Implementation

using DevExpress.ExpressApp;

public class ViewControllerExample : ViewController { public ViewControllerExample() { TargetViewType = ViewType.DetailView; TargetObjectType = typeof(MyBusinessObject); }

protected override void OnActivated() {
    base.OnActivated();
    *// Custom logic for when the View is activated*
}

protected override void OnDeactivated() {
    *// Cleanup logic*
    base.OnDeactivated();
}

}

2. ObjectViewController

A specialized Controller for Views displaying specific objects.

Example: ObjectViewController Implementation

using DevExpress.ExpressApp;

public class ObjectViewControllerExample : ObjectViewController<DetailView, MyBusinessObject> { protected override void OnActivated() { base.OnActivated(); // Custom logic for the target object } }

3. WindowController

A Controller that operates at the application window level.

Example: WindowController Implementation

using DevExpress.ExpressApp;

public class WindowControllerExample : WindowController { public WindowControllerExample() { TargetWindowType = WindowType.Main; }

protected override void OnActivated() {
    base.OnActivated();
    *// Custom logic for the main window*
}

protected override void OnDeactivated() {
    *// Cleanup logic*
    base.OnDeactivated();
}

}

Combining Actions and Controllers

Controllers typically include one or more Actions, providing a framework for encapsulating custom logic.

Example: Combining Actions and a Controller

using DevExpress.ExpressApp; using DevExpress.ExpressApp.Actions;

public class CombinedController : ViewController { public CombinedController() { TargetObjectType = typeof(MyBusinessObject);

    SimpleAction combinedAction = new SimpleAction(this, "CombinedAction", DevExpress.Persistent.Base.PredefinedCategory.Edit) {
        Caption = "Do Something"
    };

    combinedAction.Execute += CombinedAction_Execute;
}

private void CombinedAction_Execute(object sender, SimpleActionExecuteEventArgs e) {
    Application.ShowViewStrategy.ShowMessage("Combined action executed!", InformationType.Success);
}

}

Best Practices 1. Encapsulate Logic: Place business logic in Controllers for better reusability and maintainability. 2. Use Appropriate Actions: Choose the Action type that best fits the user interaction requirements. 3. Clean Up: Always undo customizations in the OnDeactivated method to ensure the Controller doesn’t interfere with other Views.

Directory Breakdown

• BusinessObjects/: Define domain classes that represent the data model. All entities inherit from DevExpress.Persistent.BaseImpl.EF.BaseObject.
• Controllers/: Implement custom logic and actions for XAF modules.
• Editors/: Create and manage custom property editors and UI components.
• Pages/: Store Razor components for Blazor's UI layer.
• Services/: Add reusable service classes for business logic and backend functionality.
• Utils/: Store utility classes for helper methods or common functionality.
• DatabaseUpdate/: Manage schema updates and seed data scripts for the database.

Rules for Directory Maintenance

• Consistency: Ensure all new classes, components, or services are placed in the appropriate directories.
• Documentation: Document the purpose and functionality of custom controllers and editors.
• Updates: Regularly sync changes between BusinessObjects/ and DatabaseUpdate/ to keep the schema consistent.
• Separation of Concerns: Follow strict separation of concerns; domain logic in BusinessObjects/, UI logic in Pages/, and backend services in Services/.

---