This topic describes all of the elements available in the XML template file. You can edit your XML template files using any XML editor or plain text editor of your choice. See Edit a container template.
A complete template file reference document for FBX Assets is also available at http://www.autodesk.com/maya-docs.
The following diagram shows a sample template file with two views, and illustrates the placement of the XML elements within the template file.
The following table provides a summary of what each template element can contain. Detailed descriptions of each element follow.
| Template | View | Attribute | Group | Property |
|---|---|---|---|---|
|
|
|
|
|
The main body of the template is defined by a single <template> element. Within the template, a series of <attribute> properties describe the published attribute interface of the container.
The following table describes the main elements of a template file.
| Element | Description |
|---|---|
<encoding> |
Must be UTF-8. If the encoding is not specified, UTF-8 is assumed. |
| <templates> | Encloses all file elements. |
| <package> | (Optional) If a template is part of a named package, this attribute specifies the package name. See Template packages for more information. |
| <using> | A <using> statement should be included to identify all packages required by the file. Maya automatically adds <using> directives to templates created or saved from Maya. |
| <template> | Encloses all elements within the template file. Usually there is one template definition per file. See Template elements. |
| <view> | (Optional) View elements define customized user interface layouts for the template. Multiple views can be associated with each template. See View elements. |
Templates can optionally be organized into packages. Setting up the package structure involves some extra steps but it offers a number of advantages when establishing libraries of templates that are intended to be reused or shared. See Organize container templates into packages.
Packaged templates are referred to by both their package name and template name, separated by a period. For example a template1 located in pkg1 will have the full name "pkg1.template1". When a template is put into a package, the package name acts like a namespace, reducing conflicts with templates of the same name in other packages.
All template files in the same package are stored in a folder matching the package name. For example, a package named pkg1 would be located in folder pkg1. The parent folder of the package should be located on the template search path.
In the following example, template1 and template2 are in package pkg1, template3 and template4 are in pkg2. The parent directory templatePackages would be specified on the template search path and references to either package could be resolved.
.../templatePackages/pkg1/template1.template
.../templatePackages/pkg1/template2.template
.../templatePackages/pkg2/template3.template
.../templatePackages/pkg2/template4.template
The package name must be specified in each template in the package:
<templates package=pkg1></templates>
Templates that refer to definitions from a package require a <using> directive. The <using> directive ensures the package is available so that the information in the template can be resolved at load time. When a template is saved from Maya, this directive is automatically added if it is required.
<templates><using package='pkg1'>....</templates>
The following table describes the elements allowed within the template definition of a template file.
| Element | Description |
|---|---|
| <template> | The main element of a template file. It defines the published interface of a container. |
| <name> | Uniquely identifies this template. It cannot contain any special symbols or multi-byte characters. By convention in Maya, the template name and filename correspond. Templates in packages are namespaced with the package name so the same template name can be used in multiple packages. |
| <attribute> | Template elements contain a series of attribute elements that define the template contents. See Attribute elements. |
| <label> | (Optional) Display label for the template. When a label is not specified, the template name is used. This value can be localized. See Localization elements: Interface labels and descriptions for more information. |
| <description> | (Optional) A notation for the template. When available, this value is used in some parts of the user interface to display tooltip help. This value can be localized. See Localization elements: Interface labels and descriptions for more information. |
Each published attribute is described by an attribute element. The following table describes the elements allowed within an attribute definition.
| Element | Description |
|---|---|
| <name> | Corresponds to the published name of the attribute on the container. |
| <type> | Corresponds to the data type of the attribute. This information is generated from the attribute type when templates are created in Maya. A set of standard types are defined in the Maya package which correspond to Maya attribute types. See Attribute types for more detailed information. |
| <label> | (Optional) Display label for the attribute. If the label is not specified, a label is generated from the attribute name. The attribute label may also be overridden when the attribute is used in a view. See Localization elements: Interface labels and descriptions for more information. |
| <description> | (Optional) Annotation text for the attribute. This text appears in some parts of the UI (such as the Attribute Editor) as tooltip help. The description can also be overridden when the attribute is used in a view. See Localization elements: Interface labels and descriptions for more information. |
<attribute name='attribute1' type='maya.float3'>
<label>Display Name</label>
<description>Your description here.</description>
</attribute>
Template attribute types are used by Maya to document the expected type of the attribute that will be bound to the published attribute. They are generated using information from bound attributes when the template is created. Unbound attributes will have their types set to VOID, which indicates that the type is unknown.
The template format supports several mechanisms for defining attribute types. Templates created from Maya will contain either built-in or customized types. It is not an error for a template to contain unresolved types; however, Maya generates warnings if they are encountered.
The following built-in types can be used directly or can be used to define custom types:
Custom attribute types are defined using <type> elements. A set of custom types corresponding to Maya attribute types is supplied. These types are defined in the 'maya' package. Templates created from Maya that use these types will have the <using package='maya'> directive and the type names will be prefixed with this package name. Refer to the FBX Assets reference document available at http://www.autodesk.com/maya-docs for more information on creating custom types.
A template can have one or more views associated with it. A view describes a particular display layout for the container and can be used to tailor the container interface for different purposes (for example different users or workflows).
Views are defined using <view> elements. The attributes in a view are referenced from the template using <property> elements. Attributes can be grouped using <group> elements. View-specific overrides can optionally be supplied for certain template information. In particular, the attribute’s label and description text that is displayed in the interface can be customized on a per-view basis if desired.
A view element defines a customized user interface layout for the contents of the template. When the view is active, only those attribute properties included in the view definition are shown in the user interface, and the other template attributes are suppressed. The view properties can be organized into groups.
Some information (labels, descriptions) can be provided on both the template and the view. View-specific definitions take precedence over template-level information when they are provided.
| ELement | Description |
|---|---|
| <name> | Provides a name for this view. The view name is an identifier and cannot contain spaces, special symbols, or multi-byte characters. To provide a user-interface label for the view, use the <label> attribute. |
| <template> | Identifies the template with which this view is associated. |
| <label> | (Optional) Display label for the view. If the label is not specified, the view name is used. This value can be localized. See Localization elements: Interface labels and descriptions for more information. |
| <description> | (Optional) Annotation text for the view. This text displays in some parts of the interface (such as the Attribute Editor) as tooltip help. See Localization elements: Interface labels and descriptions for more information. |
| <property> | Views contain a series of property elements which refer to template attributes. See Property elements. |
| <group> | Properties can be organized into groups. See Group elements. |
<view name='ShadingArtist' template='fountain'>
<label>Shading Artist</label>
<description>This view is for the shading team. </description>
<group name='Water_Shader'>
<property name='water_diffuse'/>
<property name='water_color'/>
</group>
</view>
Views can contain group elements. Groups organize the attributes in Maya’s windows and editors. In the Attribute Editor and Asset Editor for example, groups are used for creating collapsible layouts. In some cases, the use of groups is not supported (such as in the Channel Box) and the view properties are laid out in an ordered list instead.
The following table describes all elements that are allowed within a group definition.
| Element | Description |
|---|---|
| <name> | Provides a name for this group. The group name is an identifier and cannot contain spaces, special symbols, or multi-byte characters. To provide a display label for the group, use a <label> element. |
| <label> | (Optional) Display label for the group. If the label is not specified, the group name is used. This value can be localized. See Localization elements: Interface labels and descriptions for more information. |
| <description> | (Optional) Annotation text for the group. This text is used in some parts of the interface (such as the Attribute Editor) as tooltip help. See Localization elements: Interface labels and descriptions for more information. |
| <property> | Groups contain a series of property elements which identify the template attributes included in the group. |
<group name='Brick_Shader'>
<label>Brick Shading Properties</label>
<description>Control main brick shader.<description>
<property name='brick_diffuse'/>
<property name='brick_color'/>
<property name='brick_transparency'>
</group>
The following table lists the elements allowed within a property definition.
| Element | Description |
|---|---|
| <name> | View attribute properties refer to template attributes by their name. |
| <label> | (Optional) Display label for the attribute when used in this view. This value is view-specific and overrides any template-level label that is set on the attribute. If no label has been set on the attribute (either in the view or the template), the label is derived from the attribute name. This value can be localized. See Localization elements: Interface labels and descriptions for more information. |
| <description> | (Optional) Display annotation for the attribute when used in this view. This value is view-specific and overrides any template-level annotation that is set on the attribute. This text is used in some parts of the interface (such as the Attribute Editor) as tooltip help. See Localization elements: Interface labels and descriptions for more information. |
<property name=’brick_glowIntensity’>
<label>Brick Glow Intensity<label>
<description>Controls glow intensity of brick shader.<description>
</property>
Localization elements: Interface labels and descriptions
Most of the text values in the template file are object identifiers or similar values that cannot contain spaces or other special characters. The exception to this are the <label> and <description> tags, which are used on various elements to set display-only label and annotation text for the user interface. The data values for these fields support localized data (UTF-8 encoded), spaces, special characters, and punctuation.
Interface information fields (<label> and <description>) can be provided on both the template and the view. View-specific definitions (when provided) take precedence over those defined in the template. For example, if an attribute has a label defined in the template and a different label defined in the view, the view label takes precedence.
The <label> and <description> elements define display-only strings for the user interface and apply to many elements in the XML format. Since these values are display-only, they can contain spaces and other special characters that are not allowed in the object name fields. They also provide the ability to localize the template interface into other languages. All text values defined in the XML file are to be encoded in UTF-8.
See also Localize the container user interface.
