The @livefir/fir
package is a companion alpine.js plugin for the Go library pkg.go.dev/github.com/livefir/fir. Fir is a Go toolkit to build reactive web interfaces using: Go, html/template and alpinejs.
The plugin can be included as a script tag before the alpine.js
include.
<head>
<script
defer
src="https://unpkg.com/@livefir/fir@latest/dist/fir.min.js"></script>
<script
defer
src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>
</head>
See example.
The plugin provides event handlers custom magic and directives.
Fir depends on alpinejs custom event handlers to update the DOM. Event handlers are of the syntax:
<x-on:@>:fir:event-id:event-state<ok|error|pending|done>::template-name<optional>
For e.g,
<div @fir:create-todo:ok::todo="$fir.prependEl()">
{{ range .todos }}
{{ block "todo" . }}
{{end}}
{{end}}
</div>
The expression @fir:create-todo:ok::todo
means that if create-todo
event handler returns with a non-error response then re-render the template named todo
and send the html to the browser. The event handler utility function $fir.prependEl()
picks the returned html from event.detail.html
and prepends it to the current element. For a full list of utiliy functions see section Magics
The ::template-name
binding is optional. It is useful for situations where one needs to re-use a template out-of-band like the example above.
Fir automatically extracts a template from any element which contains html/template actions.
For e.g.
<p @fir:create-todo:error="$fir.replace()">
{{ fir.Error "create-todo.text" }}
</p>
Here Fir automatically extracts a template out of the content of p
tag. Under the hood, this is how it looks like:
<p @fir:create-todo:error::fir-kxkccoas8d9="$fir.replace()">
{{ fir.Error "create-todo.text" }}
</p>
- ok: when OnEvent handler returns a non-error response.
- error: when OnEvent returns an error response.
- pending: client-only for loader states. triggered before the Event is sent to the server.
- done: client-only for loader states. triggered on both ok and error response from the server.
x-fir-mutation-observer
implements the https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver as an
alpine directive. It allows you to observe changes to the DOM and react to them.
e.g.
x-fir-mutation-observer.child-list.subtree="if ($el.children.length === 0) { empty = true } else { empty = false }"
See api.md
.nohtml
modifier tells the server to not send the resultant html to the client. This is useful in cases like these:
@fir:create:ok.nohtml="$el.reset()"
@fir:delete:ok.nohtml="$fir.removeEl()"