Templates Support. Design-Time Features

If you want a certain Property Editor to display data using a custom Template, you need to implement the Template and customize it via the Model Editor.

Before proceeding, it is recommended that you review the UI Introduction topic.

Getting Started

  • Add XafariModule and XafariEditorsModule to the Module Project.
  • Add XafariWebModule and XafariEditorsWebModule to the ASP.NET Web Module Project.
  • In the Web Application Project, invoke the Add New Item dialog and navigate to the Xafari section. Then, select Xafari Default Template Content, specify the name, and press Add.

templates_support_21

  • Implement User Control with the requirements of your application. The sections below describes how to apply a custom Template to the Editor.

Model Editor

As mentioned above, a custom Template is a Web User Control; it is encoded in the .ascx file. To store Templates, it is necessary to create a special directory in your project. For the purpose of definiteness, we call it Templates.

The Options|CustomTemplates node contains the TemplatesFolderPath property. It specifies the path to the Templates directory relative to the root directory of the application.

templates_support_8

If a property of the business object is displayed via the Xafari Property Editor that supports custom Templates, then you can specify the parameters of the editor using one of the following Application Model nodes:

  • OwnMembers|Property,
  • _DetailView|Items|Item,
  • _ListView|Columns|Column.

templates_support_9

Each of the listed nodes exposes the following parameters:

  • The UseCustomTemplate flag specifies whether or not to apply a custom Template when displaying the property; the default value is true.
  • The TemplatePathEditMode and TemplatePathViewMode properties specify the path to custom Templates. These properties allow to specify a Template, depending on the current Property Editor mode. Both default values are null. There are two ways to set the path: a) relative to the root directory of the application and b) relative to the Templates directory.

templates_support_10

  • The MinWidth and MaxWidth properties specify the minimum and maximum width of the default Template.

If the list of the business objects is displayed via the Xafari List Editor that supports custom Templates, then you can specify the parameters of the editor using the _ListView node of the Application Model:

templates_support_11

The _ListView node exposes the following parameters:

  • The UseCustomTemplate flag specifies whether or not to apply a custom Template when displaying the list, the default value is true.
  • The EditorTemplatePath property specifies the path to a custom Template. The default value is null. There are two ways to set the path: a) relative to the root directory of the application and b) relative to the Templates directory.
  • MinWidth and MaxWidth properties specify minimum and maximum width of the default Template.

To apply custom Templates to Nested Frame Control, it is necessary to navigate to the node of the appropriate property of the business object. The TemplateFrameContex parameter specifies the name of context used to define the path to the custom Template. If it is null, then the default Template is used.

templates_support_12

Template Resolvers

The Property Editor can use custom Templates but it is not necessary to specify the path to the Template file directly, as described above. I.e., the TemplatePathEditMode, TemplatePathViewMode and EditorTemplatePath properties, that have been described above, can contain the null value (the default path is empty), but the Property Editor still finds the requested .ascx file. This is possible due to the mechanism named Template Resolvers.

There is the Options|Custom Templates node in the Application Model. To organize the access to Templates, it contains three child nodes: Frame, ListEditor, and ViewItem.

ViewItem

This section provides the search of templates for the Detail View items. The number and sequence of the nodes in this section defines the search order. Each node exposes the Index and TemplatePath properties.

templates_support_13

The Index property specifies the node sequence. The Detail View item will check the Template in accordance with this sequence. The framework will look for the Template by the path specified in the TemplatePath property.

The TemplatePath property specifies the path to the Template, it may be relative or absolute. The path is a string that is interpreted by Xafari Object Formatter. An instance of the Detail View item is sent as an object for interpretation.

In the Property Editor context you can use the {0:View<GetType>} construction. It will be interpreted as a type name of the Detail View which uses the item.

The TemplatePath samples:

  • example

{0:Model.PropertyEditorType.FullName}\{0:View<GetType>}{0:ViewEditMode}.ascx
 {0:Model.PropertyEditorType.Name}/{0:View<GetType>}{0:ViewEditMode}.ascx
 Templates/{0:Model.PropertyEditorType.Name}.ascx

ListEditor

This section provides search of templates for the List Editor. The number and sequence of nodes in this section defines the search order. Each node exposes the Index and TemplatePath properties.

templates_support_14

The Index property specifies a sequence of nodes. List Editor will check the Template in accordance with this sequence. The framework will look for the Template by the path specified in the TemplatePath property.

The TemplatePath property specifies the path to the Template. It is defined with the same rules as for the ViewItem node.

Frame

This section provides the Templates search for ListPropertyEditor and DetailPropertyEditor. The number and sequence of nodes in this section defines the search order. Each node exposes the Index and TemplatePath properties.

templates_support_15

The Index property specifies the sequence of the nodes. The List Editor will check the Template in accordance with this sequence. The framework will look for a Template by the path specified in the TemplatePath property.

The TemplatePath property specifies the path to theTemplate, it may be relative or absolute. The path is a string that will be interpreted using Xafari Object Formatter. An instance of CreateCustomTemplateEventArgs is sent as an object for interpretation.

Note:

Property Editor or List Editor templates are UserControl class descendants used to implement the ICustomTemplate interface. Alternatively, you can inherit from the PropertyEditorTemplateBase class.

The ListPropertyEditor or DetailPropertyEditor Templates must be the descendants of the NestedFrameControlBase class.

The full path to the Template should not exceed 260 characters.