Introduction
Starting v1.18.0, AppRun supports directives in the JSX view. AppRun directives are custom attributes that have names starting with $. They are syntax sugar to simply JSX code.
There are two built-in directives $on and $bind in AppRun. AppRun also allows you to create your own directives.
I will introduce the two built-in directives and then describe how to create custom directives in this post.
$on
The $on directive is for converting DOM events to AppRun events. If you have code that subscribes to DOM events and publishing AppRun events like below.
<button onclick={e=>this.run('click', e)}>Click Me</button>
Then you can use the $on directive:
<button $onclick='click'>Click Me</button>
The $on directive simplifies the code. It is declarative and easy to understand. It can be used for all DOM events, such as oninput, onkeydown, onchange… The $on directive also hides this keyword. No more this.run.Therefore, AppRun applications become no need for using this.
You can try out the @on directive by running the example of $on in the AppRun playground.
In @apprunjs 1.19.1, the $on directive links the DOM events to class functions and triggers the AppRun event life cycle without explicit event names. And it is strongly typed.
$bind
The $bind directive is for synchronizing data between the state and HTML input elements. Take a look at an example app below.
const state = 'world';
const view = state => <div>
<h1>Hello {state}</h1>
<input $bind />
</div>;
app.start(document.body, state, view, {});
You can expect that the $bind directive does two things. First, the input element has the value being set to ‘world.’ Second, when users type a new text in the input element, the new text is set back to the state and then display in the h1 element.
The $bind directive respects the name property of the input elements. If the input element has a name property. The value of the input element is synchronized to the state field of the same name. E.g.,
state["firstName"] <==> <input $bind name="firstName" />
You can also set the $bind property value without the name property.
state["firstName"] <==> <input $bind="firstName" />
The $bind directive can be used for many input types, such as text, number, checkbox, radio, select/option.
You can try out the @bind directive by running the example of $bind in the AppRun playground.
Custom Directive
In addition to providing the $on and $bind directives, AppRun allows you to create custom directives. All you need to do is to subscribe to the $ events.
When AppRun is processing the JSX code, it publishes the $ event if it finds the custom attributes named like $X. The event parameters contain the directive key, properties, and tag Name of the HTML element, and component instance.
app.on('$', ({key, props, tag, component}) => {
if (key === '$myDirective') {}
}
You don’t have to use all four event parameter. E.g., if you can use only the key and props to create the $animation directive to attach the animation classes from the animation library, animation.css.
app.on('$', ({key, props}) => {
if (key === '$animation') {
const value = props[key];
if (typeof value === 'string') {
props.class = `animated ${value}`;
}
}
});
You can see the animation directive live demo on @glitch.
Conclusion
AppRun is an event system. AppRun events drive the application. We use events for routing and debugging/dev tools. Now we also use events for directives. I hope you like it.