I've blogged about a few of the behaviours of Lightning Web Components, but the proof is really in building useful bits. What happens when you actually try to make a re-usable component?
For our example, we'll rebuild 'ui:message'. A now (seemingly) defunct base component that would render a message in a box that is coloured based on the 'severity' of the message being shown. In the original it could be set to 'closable', although we're going to ignore that and focus on just the rendering of it.
In a Lightning component we would use it like this:
Original usage - Lightning Component
<ui:message title="Error" severity="error" >{!v.errorMessages}</ui:message>
Ideally, the version we will create, would be used like this:
Desired usage
<c-message title="Error" severity="error" >{errorMessages}</c-message>
Looks pretty straightforward, and actually - it is. Just as long as we know about a few simple concepts.
Before we go into them, let's see what a working example could look like:
Javascript component
import { LightningElement, api } from 'lwc';
export default class Message extends LightningElement {
@api title;
@api severity;
get classes() {
return this.severity + ' uiMessage';
}
}
HTML Template
<template>
<div class={classes} role="alert" >
<div class="uiBlock" >
<div class="bBody" >
<h4>{title}</h4><slot></slot>
</div>
</div>
</div>
</template>
OK then, let's pick a few of these bits apart, and hopefully we'll explain a few little behaviours along the way.
First up, let's take a look at the '@api' declarations.
@api
The @api property lines are pretty simple to understand - they define that 'title' and 'severity' are publicly available properties of the component. In the context of Lightning Web Components, public and private mean 'available outside of the component, and invisible to the outside of the component'. It's tempting to think that this is to do with the scope of the Javascript, but it's not.
That is, every property of the Javascript component is available to be referenced in the HTML template - whether it is 'public' or 'private'. One way of thinking about it is that the HTML template forms part of the component, and so it can see private properties.
Another (probably more accurate) way of thinking about it is that the template is processed by the Javascript component (that code it's immediately obvious, but it's almost certainly in LightningComponent - which this class extends), and the Javascript can see its own properties, so the private ones are available.
However, other components (like ones that include this in their templates) can only see public properties. @api is how you make them public. Doing so means that they are available as attributes on the tag you use to include the component (hence <c-message title="Error"... is possible)
Not only that, but every @api decorated property is also 'reactive'. That is, whenever its value changes the component is re-rendered. The documentation is pretty clear on that point - and is presented as a fundamental property of a public property:
To expose a public property, decorate it with @api. Public properties define the API for a component. An owner component that uses the component in its markup can access the component’s public properties. Public properties are reactive. If the value of a reactive property changes, the component’s template rerenders any content that references the property.
Why would a public property be reactive?
Put simply, if we change the value of one of those properties in a parent component, we want the component to re-render - and it's pretty much guaranteed that we ALWAYS want the component to re-render.
For example, we may do the following:
<c-message title="{title}" severity="{severity}" >{messages}</c-message>
When the value of 'title' or 'severity' changes, we would always want the message box to re-render to show our new values. And so the framework takes care of that and makes EVERY public property of the component reactive
So that takes care of the attributes we need to pass in, what about the content?
Slots
Lightning Components had facets. And they weren't intuitive. I mean they weren't complex, but they weren't in keeping with HTML - they always felt unnatural - especially in the simplest of cases.
Lightning Web Components fixes that, with slots. And in the simple case they are trivial. The documentation isn't long, and doesn't need to be.
All we need to do, in this simple case, is add <slot></slot> into our component, and the body of any tag that instantiates the component will be rendered in that slot.
Now something that's missing from the documentation, which is a fairly obvious behaviour once you see it in action, is that slots are effectively reactive.
That is, if you change the content of the tag, that content is immediately reflected in the component's rendered output.
So, in our example:
<c-message title="Error" severity="error" >{errorMessages}</c-message>
Whenever the value of 'errorMessages' changes, the slot inside the 'message' component is re-rendered to include the new content.
I admit, I had assumed that this would be the case, but I didn't immediately realise that it was an assumption. So I thought it was worth calling out
Getters
The final part of the example that I want to explain is the use of the 'getter':
get classes() {
return this.severity + ' uiMessage';
}
What we're doing here is building a list of CSS classes for a node in the component that includes one of the passed in attributes plus a standard class that must be applied
The use of the getter illustrates an important difference between the behaviour of the templates in Lightning Components (LC) and Lightning Web Components (LWC), as well a reminder of the behaviour of properties.
That is, in LC we could have done the following in our template:
<div class="{!v.severity + ' uiMessage'}" role="alert" >
In LC, our replacements could include expressions, so we could build up strings in the template. In LWC, we can't do this, we can only reference properties or getters.
Not only that, but we can't build up the strings in the attribute assignment.
I.E. We can't do this:
<div class="{severity} uiMessage" role="alert" >
In LWC we don't assign properties to attributes in this way, the framework takes care of the wrapping in double quotes, escaping the strings, and other such things, so we can only assign the property, and that's it.
I.E. This is what is allowed:
<div class={severity} role="alert" >
So, if we want to assign more than just the value of 'severity' to the class attribute, we need to build that string up outside of the template.
Your first reaction might be - OK, we can create a trackable property to store it, right?
@track classes = this.severity + ' uiMessage';
But this doesn't work. You'll end up with the classes property defined as 'undefined uiMessage', and it won't change. Why is that?
Well, it's tempting to think that 'track' and 'api' mean that Javascript will re-run when things change, but that's not what they do - nor what the documentation says they'll do
Rather, if a property is reactive it means that the component will be re-rendered when the property changes. That says nothing about running Javascript.
So when we look at the above, what happens is the property 'classes' is set when the Javascript object is constructed. At this point the property 'severity' is undefined. When the 'severity' is updated via the attribute, the component is re-rendered and the 'classes' property is re-injected into the template, but the Javascript that sets the classes property is not re-run - that is only executed when the object is instantiated.
So, instead of setting the 'classes' property directly, we set up a getter for it:
Javascript component
get classes() {
return this.severity + ' uiMessage';
}
Now, when the 'severity' property changes, the 'classes' property is re-injected. In order to get the value for 'classes', the getter is executed - this is the only way the property can be retrieved. In doing so, the string concatenation is re-evaluated and the new value is retrieved.
Summary
None of the concepts here are particularly difficult, or really that earth shattering, but building even the simplest of re-usable components starts to shed some light on what the parts do any why.
The framework has been very thoughtfully put together, and some of the techniques will be different to what people are used to, having cut their Javascript teeth with Lightning Components, but the changes are for very good reasons. An example like this really shows how those changes make for simple components.
No comments:
Post a Comment