The CustomElement resource is a core concept in Aurelia 2, enabling developers to create encapsulated and reusable components. Understanding how to leverage the CustomElement API is crucial for building robust applications. In this documentation, we will delve into the usage of CustomElement and its methods, providing detailed examples and explanations.
CustomElement.for
This method retrieves the Aurelia controller associated with a DOM node. The controller offers access to the element's view-model, lifecycle, and other properties.
Usage Examples
Retrieving a Controller for the Current Node
import { CustomElement } from 'aurelia';
const myElement = document.querySelector('.my-custom-element');
try {
const controller = CustomElement.for(myElement);
// You can now interact with the custom element's controller
} catch (error) {
console.error('The provided node does not host a custom element.', error);
}
Searching Parent Nodes for a Controller
const someInnerElement = document.querySelector('.some-inner-element');
const parentController = CustomElement.for(someInnerElement, { searchParents: true });
// parentController is the closest controller up the DOM tree from someInnerElement
Getting a Controller for a Named Custom Element
const controller = CustomElement.for(myElement, { name: 'my-custom-element' });
if (controller) {
// The controller is for a custom element named 'my-custom-element'
} else {
// No custom element with the specified name found
}
Retrieving a Controller Without Throwing an Error
const optionalController = CustomElement.for(myElement, { optional: true });
if (optionalController) {
// The node is a custom element and its controller is available
} else {
// The node is not a custom element, no error thrown
}
Parameters
node: The DOM Node for which to retrieve the controller.
opts: An object with optional properties to customize the behavior of the method.
Return Value
Returns an instance of ICustomElementController or null/undefined, depending on the options provided and whether a controller is found.
CustomElement.define
The define method registers a class as a custom element in Aurelia.
Usage Examples
Defining a Custom Element with a Name
import { CustomElement } from 'aurelia';
@customElement('my-custom-element')
class MyCustomElement {
// Custom element's logic here
}
CustomElement.define('my-custom-element', MyCustomElement);
Defining a Custom Element with a Definition Object
nameOrDef: A string representing the name or a PartialCustomElementDefinition object with configuration options.
Type: The class containing the logic for the custom element.
Return Value
Returns a CustomElementType representing the defined custom element.
CustomElement.getDefinition
Retrieves the CustomElementDefinition for a custom element class.
Usage Example
import { CustomElement } from 'aurelia';
const definition = CustomElement.getDefinition(MyCustomElement);
// Access the definition's properties, such as name, template, bindables, etc.
Parameters
Type: The class of the custom element.
Return Value
Returns a CustomElementDefinition object with metadata about the custom element.
CustomElement.annotate and CustomElement.getAnnotation
These methods are used to attach and retrieve metadata to/from a custom element class.