Skip to content

SPEC.md

Latest commit

 

History

History
74 lines (47 loc) · 2.25 KB

SPEC.md

File metadata and controls

74 lines (47 loc) · 2.25 KB
Raw

Alpatch is an Alpine.js plugin that takes care of the server-communication part of a web application.

Together with Alpine it provides a powerful way to develop web apps.

Alpatch supports both REST and hypertext communication.

Features

  • backend agnostic
  • works well with Alpine
  • small bundle size
  • simple & capable

Reference

Patching (Magics)

Either one magic $patch with methods get(), post(), put(), patch() and delete(), or 5 seperate magics $get(), $post(), $put(), $patch() and $delete().

Magics signature:

$method(url, options = {
    // data that should be collected and sent with the request
    // can be null, HTMLFormElement, 'scope', Object
    data,

    // custom headers
    headers

    // other options (e.g. retry interval, timeout duration, custom abort controller)
})

Those magics will collect data, issue a HTTP request and patch data.

  1. Collection of request data: form elements will be verified and read, Alpine scope will be read, etc.
  2. Serialization of acumulated data into the request body or into url parameter(s) for GET and DELETE requests.
  3. Execution of HTTP request (optional: timeout, retry, abort on visibility change).
  4. Patching the site: merging scope and DOM according to the response.

Patching (Directives):

The directive x-patch serves as a shorthand for the patch magics.

Directive signatur:

<button x-patch:event.method="url"></button>

The directive will attach an event listener to it's element and execute an Alpatch request just like magics do.

Default method: GET Default events: submit for form elements, change for input, select and textarea elements, click for every other tag

Request

Request data is located in the request body or url one or multiple parameter(s). Every alpatch request contains the X-Alpatch-Request header.

Response:

There are a few accepted response content types:

  • text/html HTML that will be patched into the DOM
  • application/json state that will be patched into the scope (or stores)
  • application/alpatch+json a special JSON protocol for Alpatch responses

Navigation

Alpatch provides boost navigation for a SPA expirience.

Anchor and form elements can be modified with the x-boost directive.