Components
This page goes over how reactive components work in Elegance.
What are components?
Components, in the most basic sense, are extensions of elements.
Components are the way in Elegance to get reactivity. And what we mean by reactivity is the page automatically updating when the value of it's state changes. We achieve this in a few ways (more on this later)
Components always have a view method, which resolves into some kind of element.
To create a component, you call the global component() function:
const Button = component({
view() {
return <button>Click Me!</button>
}
})Then, we can use our component in any page, like so:
export default function Page() {
return <div>
<Button/>
</div>
}The server calls the view method of Button during rendering, generates the necessary HTML, and ships the component to the browser, so that when required, it can be updated.
Reactivity
Right now our Button component is boring! Let's make it do something interesting like count a number.
For this, we can either use a global atom, or a component local atom. The two differ in way that every time you create another instance of the component, the component-local atom has a unique value, whereas the global one doesn't. Both have their uses of course.
We can add a local atom set to our button like this:
const Button = component({
atoms: {
counter: 0,
},
view() {
return <button>Click Me!</button>
}
})We could just as easily add as many atoms to this component as we'd like, and when their values change, the component re-calls view, and refreshes the page HTML.
Event Handlers
Let's actually make counter update with an onClick event.
To do this, we can just add an onClick prop to our <button> element, give it a function, and in the function increment counter's value by one.
We'll need to access our atoms, which are conveniently passed to us via the view functions parameters:
const Button = component({
atoms: {
counter: 0,
},
view({ atoms: { counter, }}) {
return <button
onClick={() => {
counter.value++;
}}
>
Click Me!
</button>
}
})The view method also get's other paramaters, like the "component self", which contains values passed to the component during creation (like className), as well as root (only available in the client runtime), which contains the live HTMLElement fresh from the browser.
Component Methods
There are other component methods, each of them have a good use.
onNavigate()
This method is called whenever client side navigation occurs. You can imagine a scenario where a component or layout requires an active connection to somewhere, and you need to gracefully handle closing it, this is perfect for that and really any scenario where you need to handle cleanup. Please note that this is only called for the navigate function. Obviously native navigation can never trigger this.
onMount()
This method is called whenever the component initially is displayed on the page. For example, if the component is visible on the page upon first load, it is called then in the browser.
This method is also called for subsequent "mounts". So, if you have a component and it stops existing (due to conditional rendering or otherwise), and then it appears back, it will be called.
onUmount()
This method is called right before a component is removed from the DOM.
This is practically the antithesis of onMount.
init()
This method is called on the server during the intial server-side render. It's async, and it's purpose is to allow population of a component's atoms when feasible.
It's most common usage is reading values from a database / fetching from an API.
This method is always cut out of the client bundle no matter what.
fallback()
This method provides a kind of "error boundary" to a component. If this component (or any component in it's subtree) throws an error, and that error is unhandled, fallback() is called, and the resulting "fallback" UI is displayed.
You generally want this as specific as possible, as errors bubble upwards. Fallbacks should catch all types of errors (illegal atom mutation, event handler issues, view() issues). If you throw in a fallback, catastrophic things might occur.