The requested page is not available for the requested platform. You are viewing the content for Default platform.

Template Customization

The eXpressApp Framework provides built-in Templates that are suitable for most business applications. By default, these Templates are used to generate a UI. Sometimes, you may need to change or replace something in a Template, and there are several ways to do this. Due to different mechanisms of Template creation in WinForms and ASP.NET Web applications, ASP.NET Web applications provide limited Template customization capabilities in comparison to WinForms applications. This topic details all aspects of Template customization for both platforms. In Mobile applications, template customization is not supported.

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

MainForm

LightStyleMainForm

MainRibbonFormV2

LightStyleMainRibbonForm

OutlookStyleMainRibbonForm

TemplateContext.View

DetailViewForm

DetailRibbonFormV2

TemplateContext.PopupWindow

PopupForm

TemplateContext.LookupControl

LookupControlTemplate

TemplateContext.LookupWindow

LookupForm

TemplateContext.NestedFrame

NestedFrameTemplate

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 provide Template implementation examples, the eXpressApp Framework installation provides 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.

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 Web Templates

All ASP.NET Web 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 Application Appearance).

Built-in Templates are added to an XAF application's ASP.NET Web 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 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 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 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