Announcing AppRun Directives

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.