Template Customization

• Mar 09, 2024
• 5 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 Gallery 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 6+, 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();
    }
}

VB.NET

Public Class MySolution
    '...
    Public Shared Sub Main()
        '...
        Dim _application As MySolutionWindowsFormsApplication = _
        New MySolutionWindowsFormsApplication()
        AddHandler _application.CreateCustomTemplate, AddressOf application_CreateCustomTemplate
        ' ...
    End Sub
    Shared Sub application_CreateCustomTemplate(ByVal sender As Object, _
            ByVal e As CreateCustomTemplateEventArgs)
        If e.Context = TemplateContext.ApplicationWindow Then
    e.Template = New MySolution.Module.Win.MyMainForm()
        End If
    End Sub
End Class

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
• LogonWindowTemplate
• PopupWindowTemplate
• NestedFrameTemplate

You can customize these templates to suit your needs. 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)

ASP.NET Web Forms Templates

All ASP.NET Web Forms Templates are pages. These pages (Templates) are created when the client application requires this. Then, the page’s Load event is raised. In the event handler, a Window is created, and a View is created and assigned to this Window. After this, the Template is assigned to the Window and the View is assigned to the Template.

Different sets of templates are provided for the applications that use new and classic styles (see ASP.NET Web Forms Application Appearance).

Built-in Templates are added to an XAF application’s ASP.NET Web Forms application project. The default template content is carried out on User Controls located in the DevExpress.ExpressApp.Web assembly, so the content is updated automatically when you upgrade to a new version of XAF. You can add XAF page content to the application project and make required modifications with it (see How to: Customize an ASP.NET Web Forms Template). To use the modified content instead of default, open the Global.asax.cs (Global.asax.vb) file and specify the path to your custom User Control, as shown below.

C#

protected void Session_Start(Object sender, EventArgs e) {
    // ...
    WebApplication.Instance.Settings.DefaultVerticalTemplateContentPath =
        "MyDefaultVerticalTemplateContent.ascx";
    WebApplication.Instance.Setup();
    WebApplication.Instance.Start();
}

VB.NET

Protected Sub Session_Start(ByVal sender As Object, ByVal e As EventArgs)
    ' ...
    WebApplication.Instance.Settings.DefaultVerticalTemplateContentPath = _
        "MyDefaultVerticalTemplateContent.ascx"
    WebApplication.Instance.Setup()
    WebApplication.Instance.Start()
End Sub

In this code, a path to the DefaultVertical template content is changed. More settings that specify paths to other template content are available using the WebApplication.Settings property.

Since ASP.NET Web Forms Templates represent regular Web Forms pages, you do not need to handle the XafApplication.CreateCustomTemplate or XafApplication.CustomizeTemplate event.

To customize JavaScript scripts used by Templates, handle the WebWindow.CustomRegisterTemplateDependentScripts event.

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.