@livefir/fir
v0.3.0
Published
Alpinejs plugin for Fir: Fir is a go toolkit to build reactive web interfaces using: Go, html/template and alpinejs.
Downloads
172
Readme
Introduction
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.
Installation
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/[email protected]/dist/cdn.min.js"></script>
</head>See example.
API
The plugin provides event handlers custom magic and directives.
Event handlers
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-todoevent handler returns with a non-error response then re-render the template named todoand send the html to the browser. The event handler utility function $fir.prependEl()picks the returned html from event.detail.htmland 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 ptag. Under the hood, this is how it looks like:
<p @fir:create-todo:error::fir-kxkccoas8d9="$fir.replace()">
{{ fir.Error "create-todo.text" }}
</p>Event states
- 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.
Directives
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 }"Magics
See api.md
Modifiers
.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()"