146 lines
2.7 KiB
Markdown
146 lines
2.7 KiB
Markdown
# Alpine.js Documentation - Magics
|
|
|
|
Magics are special properties that are available inside Alpine expressions. They provide convenient access to common functionality.
|
|
|
|
## [$dispatch](/magics/dispatch)
|
|
|
|
`$dispatch` is a helpful shortcut for dispatching browser events.
|
|
|
|
```
|
|
<div @notify="alert('Hello World!')">
|
|
|
|
|
|
n<button @click="$dispatch('notify')">
|
|
|
|
|
|
nNotify
|
|
|
|
|
|
n</button>
|
|
|
|
|
|
n</div>
|
|
```
|
|
|
|
You can also pass data along with the dispatched event if you wish. This data will be accessible as the `.detail` property of the event:
|
|
|
|
```
|
|
<div @notify="alert($event.detail.message)">
|
|
|
|
|
|
n<button @click="$dispatch('notify', { message: 'Hello World!' })">
|
|
|
|
|
|
nNotify
|
|
|
|
|
|
n</button>
|
|
|
|
|
|
n</div>
|
|
```
|
|
|
|
Under the hood, `$dispatch` is a wrapper for the more verbose API: `element.dispatchEvent(new CustomEvent(...))`
|
|
|
|
**Note on event propagation**
|
|
|
|
Notice that, because of [event bubbling](https://en.wikipedia.org/wiki/Event_bubbling), when you need to capture events dispatched from nodes that are under the same nesting hierarchy, you'll need to use the [`.window`](https://github.com/alpinejs/alpine#x-on) modifier:
|
|
|
|
**Example:**
|
|
|
|
```
|
|
<!-- 🚫 Won't work -->
|
|
|
|
|
|
n<div x-data>
|
|
|
|
|
|
n<span @notify="..."></span>
|
|
|
|
|
|
n<button @click="$dispatch('notify')">Notify</button>
|
|
|
|
|
|
n</div>
|
|
|
|
|
|
n<!-- ✅ Will work (because of .window) -->
|
|
|
|
|
|
n<div x-data>
|
|
|
|
|
|
n<span @notify.window="..."></span>
|
|
|
|
|
|
n<button @click="$dispatch('notify')">Notify</button>
|
|
|
|
|
|
n</div>
|
|
```
|
|
|
|
> The first example won't work because when `notify` is dispatched, it'll propagate to its common ancestor, the `div`, not its sibling, the `<span>`. The second example will work because the sibling is listening for `notify` at the `window` level, which the custom event will eventually bubble up to.
|
|
|
|
### [Dispatching to other components](#dispatching-to-components)
|
|
|
|
You can also take advantage of the previous technique to make your components talk to each other:
|
|
|
|
**Example:**
|
|
|
|
```
|
|
<div
|
|
|
|
|
|
nx-data="{ title: 'Hello' }"
|
|
|
|
|
|
n@set-title.window="title = $event.detail"
|
|
|
|
|
|
n>
|
|
|
|
|
|
nh1 x-text="title"></h1>
|
|
|
|
|
|
n</div>
|
|
|
|
|
|
n<div x-data>
|
|
|
|
|
|
n<button @click="$dispatch('set-title', 'Hello World!')">Click me</button>
|
|
|
|
|
|
n</div>
|
|
|
|
|
|
n<!-- When clicked, the content of the h1 will set to "Hello World!. -->
|
|
```
|
|
|
|
### [Dispatching to x-model](#dispatching-to-x-model)
|
|
|
|
You can also use `$dispatch()` to trigger data updates for `x-model` data bindings. For example:
|
|
|
|
```
|
|
<div x-data="{ title: 'Hello' }">
|
|
|
|
|
|
n<span x-model="title">
|
|
|
|
|
|
n<button @click="$dispatch('input', 'Hello World!')">Click me</button>
|
|
|
|
|
|
n<!-- After the button is pressed, `x-model` will catch the bubbling "input" event, and update title. -->
|
|
|
|
|
|
n</span>
|
|
|
|
|
|
n</div>
|
|
```
|
|
|
|
This opens up the door for making custom input components whose value can be set via `x-model`.
|
|
|
|
Code highlighting provided by [Torchlight](https://torchlight.dev/) |