On the first part of the Aurelia custom elements series, we gave an overview on how Aurelia can add components dynamically. In this post, we’ll be tackling the bindable properties of Aurelia custom elements and we’ll give a list of decorators that can be used to further customize your Aurelia custom elements.
In Aurelia custom elements, you can specifically name it using the customElement decorator on your view-model class. Your custom name will not be converted to dash-case meaning for example, @customElement(‘SecretMessage’) won’t be converted to secret-message but only secretmessage.
Aurelia custom elements has bindable properties. Within the custom element’s view, all properties or functions may be bound however it has to specify which of these properties or functions will be bindable by adding the bindable decorator. One-way binding mode is the default mode but if needed, it can be overidden by setting the bindable decorator with a property named defaultBindingMode. This property can be set into three different options: oneTime, oneWay or twoWay.
This custom element example will check if it needs to eliminate the message it receives every ten seconds by databinding. Because of the specified custom element binding mode twoWay, the textbox will be cleared when the message self-destructs and binds the updated property using the custom element.
Here are the other decorators that can be used to further customize your custom element.
- @children(selector) – A property is decorated to create an array in your class that automatically syncs the items depending on the specified selector against the element’s actual child content.
- @child(selector) – This decorates a property that creates a single child content element as reference.
- @processContent(false|Function) – When special processing is required, this decorator notifies the compiler. You can indicate it to return true or false depending if you think the compiler should process the content or not. The function’s form is: function(compiler, resources, node, instruction):boolean
- @useView(path) – Specifies the view to use.
- @noView(dependencies?) – This custom element was indicated not to have a view and will handle its own rendering internally.
- @inlineView(markup, dependencies?) – This will provide a string that compiles to the view of the custom element.
- @useShadowDOM() – A ShadowDOM injects a special optional DOMBoundary instance into the constructor. The view is then rendered in ShadowDOM and now represents the shadow root.
- @containerless() – The element’s view will be rendered without the custom element container wrapping it. This won’t go with @child, @children or @useShadowDOM decorators. Use it with these guidelines.
- @viewResources(…dependencies) – Same as <require>, it adds dependencies to the underlying view but declared in the view-model. Strings with moduleIds, objects with src/optional properties or classes of the module that will be included can be used as arguments.