Components
Components are another option for reusable building blocks of your Enhance application. They are single file components wrapping your HTML, CSS and JavaScript in a portable web component. Components live in the app/components/
folder in Enhance projects.
Naming
The tag name of your component is determined by its file name. Meaning app/components/my-card.mjs
will be authored as <my-card></my-card>
in your HTML page. Enhance components are HTML custom elements, so they require two or more words separated by a dash.
app/components/my-message → <my-message></my-message>
app/components/my-link → <my-link></my-link>
When a project grows to include more components than can comfortably fit in a single folder, they can be divided into sub-directories inside app/components/
.
The folder name becomes part of the custom element tag name:
app/components/blog/comment → <blog-comment></blog-comment>
app/components/blog/comment-form → <blog-comment-form></blog-comment-form>
@enhance/custom-element
Components are web components — meaning: they extend HTMLElement
like vanilla web components and provide you all the lifecycle methods you would expect (connectedCallback
, disconnectedCallback
, adoptedCallback
, and attributeChangedCallback
).
When you write an Enhance component you will extend the CustomElement
class from the @enhance/custom-element
package. These single file components allow you to take advantage of slotting and style scoping in the light DOM while avoiding some of the issues the shadow DOM creates.
import CustomElement from '@enhance/custom-element'
export default class MyCard extends CustomElement {
connectedCallback() {
this.heading = this.querySelector('h5')
}
render({ html, state }) {
const { attrs={} } = state
const { title='default' } = attrs
return html`
<style>
:host {
position: relative;
display: flex;
flex-direction: column;
min-width: 0;
word-wrap: break-word;
color: black;
background-color: #fff;
background-clip: border-box;
border: 1px solid rgba(0,0,0,.125);
border-radius: 0.25rem;
}
.card-img {
width: 100%;
border-top-left-radius: calc(0.25rem - 1px);
border-top-right-radius: calc(0.25rem - 1px);
}
.card-body {
flex: 1 1 auto;
padding: 1.25rem;
}
.card-title {
margin-bottom: 0.75rem;
font-size: 1.25rem;
font-weight: 500;
}
</style>
<slot name="image"></slot>
<div class="card-body font-sans">
<h5 class="card-title">${title}</h5>
<slot></slot>
</div>
`
}
static get observedAttributes() {
return [ 'title' ]
}
titleChanged(value) {
this.heading.textContent = value
}
}
customElements.define('my-card', MyCard)
You may be thinking that the render
function looks familiar and you would be right. These render
functions are Enhance Elements. This enables us to share rendering logic between the client side and server side so any Enhance Component will be server side renderable.
When an Enhance component is server-side rendered it is “enhanced” with an attribute to indicate that the slotting algorithm and style transform have already been run. The attribute look like this:
<my-card enhanced=”✨”></my-card>
The client-side code will look for this attribute and only run if your component hasn’t already been “enhanced”. Thus avoiding an unnecessary render pass.
If you have an existing Enhance Element you can always import it into your Component and use it as your render
function.
UI Updates
Updates to Enhance Components are triggered by attribute changes. Any change to an attribute listed in the observedAttributes
will trigger a <attribute name>Changed
method. For example if you are observing the title
attribute of our my-card
component any time that attribute value is updated the titleChanged
method will be executed. This enables you to write surgical DOM updates which will always be the most performant way to update your page.
DOM Diffing
Other frameworks supply a DOM diffing solution, and Enhance Components are no different. However, we believe DOM diffing should be enabled on an opt-in basis. To enable DOM diffing in our my-card
component, we will add the MorphdomMixin
class from @enhance/morphdom-mixin
.
import CustomElement from '@enhance/custom-element'
import MorphdomMixin from '@enhance/morphdom-mixin'
export default class MyCard extends MorphdomMixin(CustomElement) {
render({ html, state }) {
const { attrs={} } = state
const { title='default' } = attrs
return html`
<style>
:host {
position: relative;
display: flex;
flex-direction: column;
min-width: 0;
word-wrap: break-word;
color: black;
background-color: #fff;
background-clip: border-box;
border: 1px solid rgba(0,0,0,.125);
border-radius: 0.25rem;
}
.card-img {
width: 100%;
border-top-left-radius: calc(0.25rem - 1px);
border-top-right-radius: calc(0.25rem - 1px);
}
.card-body {
flex: 1 1 auto;
padding: 1.25rem;
}
.card-title {
margin-bottom: 0.75rem;
font-size: 1.25rem;
font-weight: 500;
}
</style>
<slot name="image"></slot>
<div class="card-body font-sans">
<h5 class="card-title">${title}</h5>
<slot></slot>
</div>
`
}
static get observedAttributes() {
return [ 'title' ]
}
}
customElements.define('my-card', MyCard)
Once added the MorphdomMixin
will handle updating the DOM whenever an observedAttributes
is modified. The <attribute name>Changed
methods are no longer necessary. Instead on an attribute change the render
method will be re-run and the output will be compared against the current DOM. Only the modified DOM nodes will be updated.
morphdom
does string based diffing on the actual HTML element and not a virtual DOM diff so every element you want compared needs to have a string change or unique id.
Lists
When working with lists of data in the DOM it is highly advisable to add a unique attribute to the list item like an id
or key
. This will assist morphdom
in determining what items have changed in the list.
Reducing Boilerplate
Many other web components provide a way of reducing the amount of boilerplate code one needs to write. Enhance provides the @enhance/element
package which builds upon the CustomElement
and MorphdomMixin
classes while providing a more succinct way of writing Enhance Components.
Revisiting our my-card
component we get:
import enhance from '@enhance/element'
const MyCard = {
attrs: [ 'title' ],
init(element) {
console.log('My Card: ', element)
},
render({ html, state }) {
const { attrs={} } = state
const { title='default' } = attrs
return html`
<style>
:host {
position: relative;
display: flex;
flex-direction: column;
min-width: 0;
word-wrap: break-word;
color: black;
background-color: #fff;
background-clip: border-box;
border: 1px solid rgba(0,0,0,.125);
border-radius: 0.25rem;
}
.card-img {
width: 100%;
border-top-left-radius: calc(0.25rem - 1px);
border-top-right-radius: calc(0.25rem - 1px);
}
.card-body {
flex: 1 1 auto;
padding: 1.25rem;
}
.card-title {
margin-bottom: 0.75rem;
font-size: 1.25rem;
font-weight: 500;
}
</style>
<slot name="image"></slot>
<div class="card-body font-sans">
<h5 class="card-title">${title}</h5>
<slot></slot>
</div>
`
},
connected() {
console.log('CONNECTED')
},
disconnected() {
console.log('DISCONNECTED')
}
}
enhance("my-card", MyCard);
export default MyCard