Template Customization

• Nov 27, 2025
• 4 minutes to read

The XAF provides built-in Templates that generate UIs suitable for most business applications. You can also modify these templates to suit your needs.

WinForms Templates

A template is created using the XafApplication.CreateTemplate method. This method is invoked by a Window or Frame object. The template type is determined using the caller object’s Context property, initialized in the constructor. The following table lists available contexts and corresponding Template types:

Context	Templates
TemplateContext.ApplicationWindow	LightStyleMainForm LightStyleMainRibbonForm OutlookStyleMainRibbonForm MainFormV2 MainRibbonFormV2
TemplateContext.View	DetailFormV2 DetailRibbonFormV2
TemplateContext.PopupWindow	PopupForm
TemplateContext.LookupControl	LookupControlTemplate
TemplateContext.LookupWindow	LookupForm
TemplateContext.NestedFrame	NestedFrameTemplateV2

The created Template is assigned to the Window’s Window.Template property, and then the Window’s View (see Frame.View) is assigned to the Template using its Frame.SetView method.

To implement a custom Template, use module projects. If you need to use a Template that is not implemented in a module project, you must first initialize the types info subsystem with information on the Template. To do this, add a XafTypesInfo.Instance.FindTypeInfo method call to your Program.Main method in the Program.cs file of the WinForms application project, and pass the custom Template type as the method parameter.

You can create a custom Template by inheriting from a control, and implementing the IFrameTemplate or IWindowTemplate interface. To supply Template implementation examples, the XAF installation includes code templates for each Template kind. To create a Template for your application using a code template, invoke Template Kit and choose the required code template from XAF WinForms Templates category. Specify a name for the new Template and press Add.

You can customize the added Template at either design time or in code. To see an example for ribbon-based templates, refer to the How to: Create a Custom WinForms Ribbon Template topic. For other templates, refer to the How to: Create a Custom WinForms Standard Template topic. Note that all built-in Templates shipped with XAF are fully customizable using the Visual Studio designer and you can easily add custom Action Containers.

Note

If you use .NET, make sure that the DevExpress.ExpressApp.Win.Design NuGet package is added to the YourSolutionName.Win project. This package contains the required design-time functionality based on .NET preview features.

To use your Template instead of the default one, handle the XafApplication.CreateCustomTemplate event, and return an instance of your Template when needed. The following code demonstrates this.

C#

static class Program {
    //...
    public static void Main() {
        //...
        MySolutionWindowsFormsApplication application = new MySolutionWindowsFormsApplication();
        application.CreateCustomTemplate += application_CreateCustomTemplate;
        // ...
    }
    static void application_CreateCustomTemplate(object sender, CreateCustomTemplateEventArgs e) {
        if (e.Context == TemplateContext.ApplicationWindow)
            e.Template = new MySolution.Module.Win.MyMainForm();
    }
}

You can also customize a Template every time it is created in a particular context. For this purpose, handle the XafApplication.CustomizeTemplate event in a manner similar to the CreateCustomTemplate event (see above).

To customize a Template when it is created for a particular Window (Frame), handle the Frame.TemplateChanged event. This event is raised after a Template is assigned to a Window (Frame).

ASP.NET Core Blazor Templates

XAF ships with the following built-in templates for ASP.NET Core Blazor applications:

• ApplicationWindowTemplate
• ApplicationRibbonWindowTemplate
• DetailFormTemplate
• DetailRibbonFormTemplate
• LogonWindowTemplate
• PopupWindowTemplate
• NestedFrameTemplate

You can customize these templates to suit your needs.

The following code sample accesses the Popup Window template and changes the template’s MaxWidth property value.

File:
MySolution.Blazor.Server\Controllers\PopupResizeController.cs

C#

using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Blazor;
using DevExpress.ExpressApp.Blazor.Templates;
// ...
public partial class PopupResizeController : WindowController {
    public PopupResizeController() {
        InitializeComponent();
        this.TargetWindowType = WindowType.Main;
    }

    protected override void OnActivated() {
        base.OnActivated();
        // Subscribe to the CustomizeTemplate event
        ((BlazorApplication)Application).CustomizeTemplate += 
            PopupResizeController_CustomizeTemplate;
    }

    private void PopupResizeController_CustomizeTemplate(object sender, CustomizeTemplateEventArgs e) {
        // Change MaxWidth for popup windows
        if(e.Context == TemplateContext.PopupWindow) {
            ((PopupWindowTemplate)e.Template).MaxWidth = "900px";
        }
    }

    protected override void OnDeactivated() {
        // Unsubscribe from the CustomizeTemplate event
        ((BlazorApplication)Application).CustomizeTemplate -=
            PopupResizeController_CustomizeTemplate;
        base.OnDeactivated();
    }
}

For more information and examples, refer to the following topics:

• How To: Create a Custom Blazor Application Template
• How to: Adjust the Size and Style of Pop-up Dialogs (Blazor)

Pop-up Window Template of the PopupWindowShowAction

The PopupWindowShowAction displays a pop-up window with a specified View. In a WinForms application, the PopupForm or LookupForm Template is used, depending on whether a Detail or List View is included. In an ASP.NET Web Forms application, the Dialog.aspx page is used as a Template. To customize the pop-up window Template, handle the Action’s PopupWindowShowAction.CustomizeTemplate event, which occurs after you assign the Template to a Window.