AppRun Event Directives
Tags: apprun, javascript, webdev, typescript
Published: 2020-03-17 19:58:43

---
title: AppRun Event Directives
published: true
description: This post introduces the AppRun event directives.
tags: #apprun #javascript #webdev #typescript
---

## Introduction

[AppRun](https://apprun.js.org) is a JavaScript library for building reliable, high-performance web applications using the Elm inspired Architecture, events, and components.

> If you are new to AppRun, read the [AppRun Book](https://www.amazon.com/Practical-Application-Development-AppRun-High-Performance/dp/1484240685/) or visit [AppRun Docs](https://apprun.js.org).

This post introduces a new method of event handling using the _event directives_.

## Event Directives

We have been using events since the first AppRun release to drive the applications which have the logic broken down into three separate parts.

* State (a.k.a. Model) — the state of your application
* View — a function to display the state
* Update — a collection of event handlers to update the state

Take a look at the following application as an example. The count adds up when we click the button.

```javascript
const view = state => <button onclick={()=>app.run('+1')}>
  Clicks: {state}
</button>;
const update = {
  '+1': state => state + 1;
};
app.start(document.body, 0, view, update);
```

Every time we click the button, the DOM event is converted to the AppRun events, and then triggers the AppRun event lifecycle:

* AppRun calls the event handler (+1) to update the _state_
* AppRun calls the _view_ function to generate virtual DOM
* AppRun renders the virtual DOM to the HTML element

The newly released [AppRun Directives](https://medium.com/@yiyisun/announcing-apprun-directives-6a063f88379c), allows us to use the _Event Directives_ to run the same steps above without events.

## JSX Event Directives

The directives are special HTML attributes that have names starting with $, such as _$onclick_. They are the extensions to the JSX syntax to simplify the JSX or add extra features.

We can use _$onclick_ to simplify the syntax of publishing AppRun events from

```javascript
<button onclick={()=>app.run('+1')}>+1</button>
```

to

```javascript
<button $onclick='+1'>+1</button>
```

Most important, the _$onclick_ directive can trigger the AppRun event lifecycle directly without events. It calls the event handler, then calls the _view_ function, and then renders the virtual DOM.

```javascript
const add = count => count + 1;
const view = count => <button $onclick={add}>
  Clicks: {count}
</button>;
app.start(document.body, 0, view);

```

You can see, because there are no events in this case, we don't need the _update_ object anymore. 

> JSX Event Directives are available in V1.x and V2.x already. We recommend using the event directives going forward to reduce the use of the _update_ object.


## lit-html

In the AppRun V3 release, AppRun will accept lit-html in addition to JSX and HTML string returned from the _view_ function.

> [lit-html](https://lit-html.polymer-project.org) is the DOM rendering technology that lets us write HTML templates using [string literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals).

```javascript
const add = (state, delta) => state + delta;
const view = state => {
  return html`<div>
    <h1>${state}</h1>
      <button @click=${()=>app.run('add', -1)}>-1</button>
      <button @click=${()=>app.run('add', +1)}>+1</button>
    </div>`;
};
app.start(document.body, 0, view, {add});
```
The _html_ in the example above is the string literal from lit-html. The _@click_ is the way to define the _onclick_ event using lit-html.

BTW, We have used the [object shorthand property names](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer): {add} as the _update_ object. 

Following the idea of using the JSX _event directive_ to reduce the use of the _update_ object, what can we do when using lit-html?

## lit-html Event Directive

The good news is that lit-html also has the directive concept so that we can bring the _event directive_ to lit-html. The directive for lit-html is called _run_. 

The example below shows how to use the _run_ directive to trigger AppRun events.

```javascript
const add = (state, delta) => state + delta;
const view = state => {
  return html`<div>
    <h1>${state}</h1>
      <button @click=${run('add', -1)}>-1</button>
      <button @click=${run('add', +1)}>+1</button>
    </div>`;
};
app.start(document.body, 0, view, {add});
```

Also, similar to the JSX event directives, the _run_ directive can trigger the event lifecycle directly without events.

```javascript
const add = (state, delta) => state + delta;
const view = state => {
  return html`<div>
    <h1>${state}</h1>
      <button @click=${run(add, -1)}>-1</button>
      <button @click=${run(add, +1)}>+1</button>
    </div>`;
};
app.start(document.body, 0, view);
```

The _run_ directive will:

* Call the _add_ function
* Call the _view_ function
* Render the HTML element (document.body)

## Live Demo

{% glitch apprun-lit-html-directive %}

> Note: AppRun V3 is available on npm as apprun@next.

Have fun!