> For the complete documentation index, see [llms.txt](https://docs.wem.io/platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wem.io/platform/tutorials/building-widgets/basics/5-events.md).

# 5. Events

{% hint style="info" %}
A CSP-compliant version is available for download on the [Examples](/platform/tutorials/building-widgets/examples.md) page.
{% endhint %}

When we talk about widget events, we refer to a unique set of WEMscript that can follow a button click, execute a flowchart, navigate to a navigation item, or refresh the screen. It is also possible to change the view state, which we will discuss in later chapters.

#### Introduction to Events

To introduce events, let's create a small virtual six-sided die that will output a random number between 1 and 6, along with a "Roll again" button that will trigger an event to refresh the screen and display a new random number. Copy and paste the following script, and let's dissect what is happening:

```html
<? register event @RefreshScreen ?>
<div>The six-sided die rolled: <?= Random(1, 6) ?></div>
<div><button onclick="<?attr @RefreshScreen ?>">Roll again</button></div>
```

It is important to inform the WEM runtime that we want to run a specific event by registering it. The `register event` statement does exactly that, and it is mandatory for an event to function properly. Based on the previous chapters, the second line should now be clear regarding its purpose. The third line is interesting and requires some explanation.

Before I explain that, let's create the refresh screen event first:

1. Select the Events tab.
2. Click on "New event."
3. Name it "RefreshScreen."

And that's it! There is no need to write any event code for a refresh screen event. We will delve deeper into this in later chapters. Now, let's continue with the interesting part on line 3:

```html
onclick="<?attr @RefreshScreen ?>"
```

A veteran web developer will recognize the `onclick` attribute. What is interesting is the `<?attr`, which I briefly explained in previous chapters; it is a shorthand for HTML attribute encoding the output. This is important because, without it, we could potentially create invalid HTML. The `@RefreshScreen` is another interesting aspect; it is not a number variable, a boolean, or text, but rather an event. You may wonder how you can output an event. What gets output is JavaScript code that will trigger the `@RefreshScreen` event, and it will look something like this:

```html
<button onclick="Runtime.raiseEvent(...)">Roll again</button>
```

Don't worry; you never have to call the WEM Runtime API directly, as it is abstracted from the widget developer. This is just to illustrate what is happening under the hood. Note that it does not matter where you trigger an event; it could also be in an `ondblclick` attribute, an `onblur` event, or even manually called in JavaScript.

Give it a try! Add the widget to any template and see if luck is on your side!

We've only just begun to explore what you can do with events. In the following chapters, we will delve deeper into the topic.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.wem.io/platform/tutorials/building-widgets/basics/5-events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.