Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Collapse]eXpressApp Framework
 [Expand]Fundamentals
 [Expand]Getting Started
 [Collapse]Concepts
  [Expand]Application Solution Components
  [Expand]Business Model Design
  [Expand]Application Model
  [Collapse]UI Construction
    UI Element Overview
    Windows and Frames
   [Collapse]Templates
     Template Customization
    Action Containers
   [Expand]Views
   [Expand]View Items
    List Editors
    Add and Override Images
    Text Notifications
    ASP.NET Web Application Appearance
    Application Personalization
    Using a Custom Control that is not Integrated by Default
  [Expand]Extend Functionality
  [Expand]Data Manipulation and Business Logic
  [Expand]Security System
  [Expand]Localization
  [Expand]System Module
  [Expand]Extra Modules
  [Expand]Debugging and Error Handling
  [Expand]Filtering
  [Expand]Application Life Cycle
 [Expand]Design-Time Features
 [Expand]Functional Testing
 [Expand]Deployment
 [Expand]Task-Based Help
 [Expand]Frequently Asked Questions
 [Expand]API Reference
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

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. In Mobile applications, template customization is not supported. This topic details all aspects of Template customization for both platforms.

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

ContextTemplates
TemplateContext.ApplicationWindow MainForm
MainRibbonFormV2
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.

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.

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

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

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.

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

Expanded See Also

How would you rate this topic?​​​​​​​