Skip to main content

Template Customization

  • 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.

TemplateGalery_WinForms

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.

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

You can customize these templates to suit your needs. For more information and examples, refer to the following topics:

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.

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

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.

See Also