https://github.com/blynx/form-sequence

A rocaesque custom element to fetch and interact with remote forms
https://github.com/blynx/form-sequence

forms progressive-enhancement roca

Last synced: 11 months ago
JSON representation

A rocaesque custom element to fetch and interact with remote forms

• Host: GitHub
• URL: https://github.com/blynx/form-sequence
• Owner: blynx
• License: mit
• Created: 2020-02-14T21:29:30.000Z (over 6 years ago)
• Default Branch: master
• Last Pushed: 2023-01-06T02:32:52.000Z (over 3 years ago)
• Last Synced: 2025-02-06T02:34:30.185Z (over 1 year ago)
• Topics: forms, progressive-enhancement, roca
• Language: JavaScript
• Homepage:
• Size: 893 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 6
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# form-sequence

A rocaesque custom element to interactively transclude remote forms: Progressively enhance your multi-page-multi-step-forms.

- [form-sequence](#form-sequence)

    - [Demo](#demo)

    - [Usage](#usage)

        - [Basics](#basics)

        - [Attributes](#attributes)

        - [Events](#events)

        - [Configuration](#configuration)

        - [Methods](#methods)

        - [Styling Hints](#styling-hints)

## Demo

Clone repo, then `npm install && npm run demo`. Browse to the url which gets displayed (usually http://localhost:3000)

## Usage

### Basics

1. Set the capture attribute

2. Set the form attribute

3. Listen to the return event and decide what to do finally

1, 2 - Wrap the starting point of your form with the form-sequence element: (Optionally) apply the id of the wrapped anchor to the `capture` attribute so the click gets intercepted. And (optionally) supply names or ids to the `form` attribute. If nothing is supplied to each, or the attributes are just left out, the first occuring anchor inside the `` or the first form on succeeding pages is chosen.  

Instead of changing to the next page, the page gets loaded in the background and the desired form gets transcluded here.

Example:

    

      Edit Something

    

The remote form could look like this

    

      

      cancel

      

    

3 - You will most probably need to listen to the return event that gets fired after the last step. It will provide the response object as well as the response url object.

    document.querySelector("form-sequence").addEventListener("return", e => {

      // reload page to reflect eventual state change

      window.location.href = e.detail.url.href

    })

### Attributes

- `capture` (optionally)  

  Provide the ids or names of the entry point element. Single entries or comma separated lists are valid. E.g. `my-link` or `my-link, alternate-link`.

- `form` (optionally)  

  The ids or names of the forms which are going to get transcluded. Single entries or comma separated lists are valid. E.g. `my-form` or `my-form, other-form, fallback-form`.

- `cancel` (optionally)  

  If the form has something like a cancel action to go back, you can put the ids/names of that element here to be able to "undo" the transclusion. A list is possible here, too.

### Events

You can listen to some events which get fired during the process cycle: 

- `return`: Called when the process finishes.  

  __The crucial one.__ You most likely need to listen to this event to handle the final step of your form process. It provides the response object as well as the response url object in the event details.

- `done`: Called after each step.  

  No details provided.

- `success`: Called after each successful step.  

  No details provided.

  

- `error`: Called when an error occurs.  

  No details provided.

### Configuration

[...]

### Methods

Some methods of the element might be useful:

- `close`: Close/reset this form-sequence element.

- `closeAll`: Close/reset all form-sequence elements of that page.

### Styling Hints

After the form has been transcluded, the markup in the form-sequence element will look like this:

    

      
Eit Something

      


        Edit Something

      

      


        ... your remote form

      

    


Have a look into `demo/style.css`. There you will find style definitions, some of which you'll likely want to apply to your app:

    // Hide the (retained) entry point element

    form-sequence [origin] {

      display: none;

    }

    // style the inserted heading element

    form-sequence [role="heading"] { ... }

    // clearfix, to be sure

    form-sequence::after {

      display: block;

      content: "";

      clear: both;

    }