@livefir/fir

0.3.0 • Public • Published

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/alpinejs@3.x.x/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()"

Package Sidebar

Install

npm i @livefir/fir

Weekly Downloads

29

Version

0.3.0

License

MIT

Unpacked Size

143 kB

Total Files

13

Last publish

Collaborators

  • adnaanx