Creating Elements

Creating web components easily is advect's signature Feature.

Your first Component

Creating a component is easy with the declarative syntax. All you need is a <template> with the following attributes:

  • An id attribute (required). This will be used as the tag of your custom web element. This value will need to be valid for a custom web element.
  • An adv attribute (required). This does NOT need a value, this just tells the system that the template is indeed an element that needs to be registered and is not just another template you have inside your document.
  • The root attribute (optional) declares where in the component the markup will be added to. The options are light | shadow | none.
    • light markup will added to the regular dom when component is connected. (default when root is not present)
    • shadow markup will added to the shadow-dom when component is connected.
    • none no markup will added to component when connected.
  • The shadow attribute (optional) is passed to the mode of this.attachShadow call. The options are open| closed (default is closed) 

<!--Declare your component, anywhere in html -->
<template id="hello-button" root="light" shadow="closed" adv>
    <button ref onclick="$self.sayHello()"> Hello </button>
    <script type="module">
    export class HelloButton extends AdvectElement {
        sayHello() {
            alert('How's it going!')
        }
    }
    </script>
</template>

<!-- Now your all set -->
<hello-button></hello-button>

The <script type="module"> tag is also optional* but when provided allows for the scripting of your custom element.
The <script type="module"> is expected to export a class that extends AdvectElement with a name that is the PascalCase version of your component name. In this example <template id="hello-button" ... > must export a class HelloButton. (NOT as the default for the module).

Advect Element API

The AdvectElement class exposes the following properties

Property Type Description
html string The original markup for the custom web element.
refs_list HTMLNodeInterface[] The original list of refs in the component.
all_refs Element[] All '[ref]'s on the object of refs in the component.
refs Proxy References to elements with 'ref' attributes.
fuzzyRefs Proxy References to custom web elements, returns a promise to the ref.
$settings CustomElementSettings Settings for the custom web element.
mutationObserver MutationObserver Mutation observer for the element.
interectObserver IntersectionObserver Intersection observer for the element.
attr Proxy Helper for getting and setting attributes on this element, calls anyAttrChanged when setting.
data Proxy Object for accessing a component's dataset variables, calls anyAttrChanged when setting.
internals ElementInternals Getter for element internals.
onConnect Function<void> a function called after the component is added to the DOM
onDisconnect Function<void> a function called before the component is removed from the DOM
onAdopt Function<void> a function called after the component is adopted to another document

Using References

References are pointers to elements inside your custom element. Any element that has a ref attribute will be registered as a reference

Inside your custom element class refs can be access via the this.refs.yourRefName

Setting up an element as a reference enhances its event listener functions (onclick, oninput etc) it adds

  • New scope variables
    • $self - a pointer to your custom element
    • $this - a safe pointer pointer to the current reference
    • $refs - shorthand for $self.refs allowing a ref to access other refs
  • Makes them async
  • Adds onmutate which is called when the markup within a ref is changed
  • Allows all elements to use onload which essentially gives any element a connectedCallback 
<!--Declare your component, anywhere in html -->
        <!-- ✅ this is a ref -->
        <button ref="myButton"
            onload="console.log($this.innerText)"
            onclick="alert(`My someProperty is ${$self.someProperty}`)"> 
            I'll alert 
        </button>

        <!-- ❌ this is NOT a ref, will error "$self" is not defined, and onload will not be called -->
        <button
            onload="console.log($this.innerText)"
            onclick="alert(`My someProperty is ${$self.someProperty}`)"> 
            I'll Error 
        </button>

        <script type="module">
        export class RefExample extends AdvectElement {
            someProperty = 69420
        }
        </script>
    </template>
    
    <ref-example></ref-example>
Previous: Docs Home Next: Templating