UxmlTemplateAttribute

Attribute that binds a UXML template to a class by name. Provides lazy-loaded access to the VisualTreeAsset via GetVisualTreeAsset(), which searches the AssetDatabase on first access and caches the result.

Definition

Namespace: Paragon.Editor Assembly: Paragon.Editor.dll

public class UxmlTemplateAttribute : Attribute

Inheritance: Attribute → UxmlTemplateAttribute

Remarks

UxmlTemplateAttribute provides a declarative way to associate a UXML template with an editor class (e.g., a custom editor, property drawer, or editor window). Instead of manually loading the VisualTreeAsset in each class, the attribute handles the lookup and caching.

Template Resolution

The attribute finds the UXML file by name using AssetDatabase.FindAssets() with a t:VisualTreeAsset type filter. It then matches by file name (without extension) to ensure the correct asset is returned, even if multiple VisualTreeAsset results exist.

Caching

The VisualTreeAsset is loaded on the first call to GetVisualTreeAsset() and cached for subsequent calls. This avoids repeated AssetDatabase searches.

Error Handling

If no VisualTreeAsset with the specified name is found, GetVisualTreeAsset() throws a FileNotFoundException with a descriptive message.

Quick Lookup

Goal	How
Bind a UXML template	[UxmlTemplate("MyTemplate")] on the class
Load the template	GetType().GetCustomAttribute<UxmlTemplateAttribute>().GetVisualTreeAsset()
Clone into element	asset.CloneTree(rootElement)
Template location	Anywhere in the project — found by name via AssetDatabase

Fields

Field	Type	Access	Description
name	string	private readonly	The name of the UXML template to search for (without extension)
visualTreeAsset	VisualTreeAsset	private	Cached VisualTreeAsset (null until first access)

Constructors

UxmlTemplateAttribute(string)

Creates the attribute with the specified template name.

public UxmlTemplateAttribute(string name)

Parameter	Type	Description
name	string	Name of the UXML template file (without path or extension)

Methods

GetVisualTreeAsset

Loads and returns the VisualTreeAsset matching the template name. Caches the result after the first successful lookup.

public VisualTreeAsset GetVisualTreeAsset()

Returns: The VisualTreeAsset for the named template.

Throws: FileNotFoundException — if no VisualTreeAsset with the specified name exists in the AssetDatabase.

Algorithm:

1. If visualTreeAsset is already cached, returns it immediately

2. Searches AssetDatabase with FindAssets("t:VisualTreeAsset {name}")

3. Converts GUIDs to asset paths

4. Finds the first path whose file name (without extension) matches name exactly

5. Loads the asset and caches it

6. If no match is found, throws FileNotFoundException

Common Pitfalls

Template name must match exactly The search matches the UXML file name (without extension) exactly. If the template is named MyEditor_Template.uxml, the attribute must use [UxmlTemplate("MyEditor_Template")]. Case sensitivity depends on the OS file system.

FileNotFoundException on missing templates If the UXML file does not exist in the project, GetVisualTreeAsset() throws FileNotFoundException. Ensure the template asset exists before deploying code that references it.

Editor-only — uses AssetDatabase This attribute depends on AssetDatabase, which is only available in the Unity Editor. It cannot be used in runtime code.

Template can be anywhere in the project The AssetDatabase search is project-wide. The UXML file does not need to be in the same folder as the class — it just needs to be somewhere under Assets/.

Examples

Decorating an Editor

using Paragon.Editor;
using UnityEditor;
using UnityEngine.UIElements;

[UxmlTemplate("MyCustomEditor")]
[CustomEditor(typeof(MyComponent))]
public class MyComponentEditor : UnityEditor.Editor
{
    public override VisualElement CreateInspectorGUI()
    {
        var root = new VisualElement();
        var template = GetType()
            .GetCustomAttribute<UxmlTemplateAttribute>()
            .GetVisualTreeAsset();
        template.CloneTree(root);
        return root;
    }
}

Using in an EditorWindow

using Paragon.Editor;
using UnityEditor;
using UnityEngine.UIElements;
using System.Reflection;

[UxmlTemplate("MyWindow")]
public class MyEditorWindow : EditorWindow
{
    public void CreateGUI()
    {
        var template = GetType()
            .GetCustomAttribute<UxmlTemplateAttribute>()
            .GetVisualTreeAsset();
        template.CloneTree(rootVisualElement);
    }
}

See Also

• DrawerIndentationAttribute — another editor-configuration attribute

• Attributes Overview — system overview