To define a custom element, begin by creating a class that extends
FASTElement and decorate it with the
@customElement decorator, providing the element name.
Example: A Basic
With this in place, you can now use your
name-tag element anywhere in HTML with the following markup:
Example: Using a Web Component
Web Component names must contain a
- in order to prevent future conflicts with built-in elements and to namespace components from different libraries. For more information on the basics of Web Components see this set of articles.
HTML has a few special tags known as "self-closing tags". Common examples include
<img>. However, most HTML elements and all web components must have an explicit closing tag.
We've got a basic Web Component in place, but it doesn't do much. So, let's add an attribute and make it render something.
Example: Adding Attributes to a
To add attributes to your HTML element, create properties decorated by the
@attr decorator. All attributes defined this way will be automatically registered with the platform so that they can be updated through the browser's native
setAttribute API as well as the property. You can optionally add a method with the naming convention propertyNameChanged to your class (e.g.
greetingChanged()), and this method will be called whenever your property changes, whether it changes through the property or the attribute API.
All properties decorated with
@attr are also observable. See observables and state for information about how observables enable efficient rendering.
By default, anything extending from
FASTElement will automatically have a
ShadowRoot attached in order to enable encapsulated rendering. The example above references the
shadowRoot to set its
innerHTML any time the
greeting property changes.
To see it in action, you can use the same HTML as above, or change the default
greeting with the following:
Example: Using a Web Component with Attributes
By default, any attribute created with
@attr will perform no explicit type coercion other than when it reflects its value to the HTML DOM via the
setAttribute API. However, you can convert DOM attribute string values to and from arbitrary types as well as control the
mode that is used to reflect property values to the DOM. There are three modes available through the
mode property of the attribute configuration:
reflect- The default mode that is used if none is specified. This reflects property changes to the DOM. If a
converteris supplied, it will invoke the converter before calling the
boolean- This mode causes your attribute to function using the HTML boolean attribute behavior. When your attribute is present in the DOM or equal to its own name, the value will be true. When the attribute is absent from the DOM, the value of the property will be false. Setting the property will also update the DOM by adding/removing the attribute.
fromView- This mode skips reflecting the value of the property back to the HTML attribute, but does receive updates when changed through
In addition to setting the
mode, you can also supply a custom
ValueConverter by setting the
converter property of the attribute configuration. The converter must implement the following interface:
Here's how it works:
- When the DOM attribute value changes, the converter's
fromViewmethod will be called, allowing custom code to coerce the value to the proper type expected by the property.
- When the property value changes, the converter's
fromViewmethod will also be called, ensuring that the type is correct. After this, the
modewill be determined. If the mode is set to
reflectthen the converter's
toViewmethod will be called to allow the type to be formatted before writing to the attribute using
mode is set to
boolean, a built-in
booleanConverter is automatically used to ensure type correctness so that the manual configuration of the converter is not needed in this common scenario.
Example: An Attribute in Reflect Mode with No Special Conversion
Example: An Attribute in Boolean Mode with Boolean Conversion
Example: An Attribute in Reflect Mode with Custom Conversion
The element lifecycle
All Web Components support a series of lifecycle events that you can tap into to execute custom code at specific points in time.
FASTElement implements several of these callbacks automatically in order to enable features of its templating engine (described in declaring templates). However, you can override them to provide your own code. Here's an example of how you would execute custom code when your element is inserted into the DOM.
Example: Tapping into the Custom Element Lifecycle
The full list of available lifecycle callbacks is:
|constructor||Runs when the element is created or upgraded. |
|connectedCallback||Runs when the element is inserted into the DOM. On first connect, |
|disconnectedCallback||Runs when the element is removed from the DOM. |
|attributeChangedCallback(attrName, oldVal, newVal)||Runs any time one of the element's custom attributes changes. |
|adoptedCallback||Runs if the element was moved from its current |
Working without decorators
definition field on your class. The
definition field only needs to present the same configuration as the
@customElement decorator. Here's an example that shows the use of the
definition field along with a manual call to
define the element:
definition can also be separated from the class and passed into the
define call directly if desired. Here's how that would look: