@easylibs/progress-form

ProgressForm Library

Introduction

The ProgressForm class provides an elegant solution for creating multi-step forms with a progress bar. It allows users to navigate through different sections of a form efficiently by breaking it down into manageable fieldsets. Each step of the form is displayed one at a time, and users can move forward or backward through the steps using the provided navigation buttons. The progress bar dynamically reflects the user's current position within the form.

Features

• Progressive Form Handling: Easily manage and transition between multiple steps of a form.
• Lazy Loading: Dynamically load form sections as needed, improving performance and user experience.
• Customizable Styles: Adjust the appearance of the form using customizable style options.
• Built-in Validations: Automatically validate form fields on the client side to ensure data integrity.
• Flexible Event Handling: Customize form behavior by hooking into various events during form progression.

Installation

To install the ProgressForm library, use one of the following methods:

Via npm:

npm install @easylibs/progress-form

Via Yarn:

yarn add @easylibs/progress-form

Via pnpm:

pnpm add @easylibs/progress-form

Alternatively, you can include the library directly from a CDN:

Minified:

<script src="https://cdn.jsdelivr.net/npm/@easylibs/progress-form@latest/dist/progress-form.min.js"></script>
<script src="https://unpkg.com/@easylibs/progress-form@latest/dist/progress-form.min.js"></script>

Unminified:

<script src="https://cdn.jsdelivr.net/npm/@easylibs/progress-form@latest/dist/progress-form.js"></script>
<script src="https://unpkg.com/@easylibs/progress-form@latest/dist/progress-form.js"></script>

Usage

Basic Usage with ProgressForm

To create a multi-step form using ProgressForm, you need to structure your HTML with fieldsets. Each fieldset represents a step in the form.

HTML Example:

<form id="progress-form" method="post">
  <div fieldset__parent>
    <div fieldset__container>
      <!-- First Fieldset -->
      <fieldset>
        <label for="name">Name:</label>
        <input type="text" id="name">
        <button type="button" __next__>Next</button>
      </fieldset>
      
      <!-- Second Fieldset -->
      <fieldset>
        <label for="surname">Surname:</label>
        <input type="text" id="surname">
        <button type="button" __prev__>Previous</button>
        <button type="button" __next__>Next</button>
      </fieldset>
      
      <!-- Third Fieldset -->
      <fieldset>
        <label for="sex">Sex:</label>
        <select id="sex">
          <option value="male">Male</option>
          <option value="female">Female</option>
        </select>
        <button type="button" __prev__>Previous</button>
        <button type="button" __next__>Next</button>
      </fieldset>
      
      <!-- Fourth Fieldset -->
      <fieldset>
        <label for="email">Email:</label>
        <input type="email" id="email" name="email">
        <button type="button" __prev__>Previous</button>
        <button type="button" __next__>Next</button>
      </fieldset>
      
      <!-- Fifth Fieldset -->
      <fieldset>
        <label for="password">Password:</label>
        <input type="password" id="password" name="password">
        <button type="button" __prev__>Previous</button>
        <button type="button" id="submitter">Submit</button>
      </fieldset>
    </div>
  </div>
</form>

JavaScript Example:

import { ProgressForm } from "@easylibs/progress-form";

// Select the form element
const form = document.getElementById('progress-form');

// Create a new ProgressForm instance
const progressForm = new ProgressForm(form);

// Initialize the form
progressForm.run();

Customizing Fieldset Movement:

You can adjust the form's appearance and fieldset transitions using the translateX option:

const translateX = -560; // Adjust this value based on your design
progressForm.run({ translateX });

Advanced Usage with LazyProgressForm

When dealing with large forms or dynamic content, LazyProgressForm allows for efficient lazy loading of fieldsets. This means that fieldsets are only loaded as needed, rather than all at once.

HTML Structre:

Just define the first fieldset

<form id="progress-form" method="post">
  <div fieldset__parent>
    <div fieldset__container>
      <!-- First Fieldset -->
      <fieldset>
        <label for="name">Name:</label>
        <input type="text" id="name">
        <button type="button" __next__>Next</button>
      </fieldset>
    </div>
  </div>
</form>

JavaScript Example:

import { LazyProgressForm } from "@easylibs/progress-form";
// Select the form element
const lazyFormElement = document.querySelector('form');

//the link to your server to retrieve the other fieldsets. 
//note that you will need to add to each fieldset a class "fieldset{i}" with "i" 
//corresponding to the index of the fieldset. 
//LazyProgressForm will automatically inject the class "fieldset0" to the first fieldset by default.
const url = "https://example.com/fieldset-getter"

// Create a new LazyProgressForm instance
const lazyProgressForm = new LazyProgressForm(lazyFormElement, url);

// Initialize the lazy form with configuration options
lazyProgressForm.lazyRun({
  fieldsetLength: 3,
  progressOptions: {
    translateX: -700
  },
  styleOptions: {
    form: { width: "700px" },
    fieldset: { width: "640px" },
    fieldsetContainer: {
      justifyContent: "null"
    }
  }
})

lazyProgressForm.fetchNextFieldSet({
  spinner: "Loading...",
  shouldRepost: true,
  callbacks:{
    onSuccess(response, index, ...data) {
      console.log({ index, response, data}) // run if request status is 200
    },
    onPreFetch(data, index) {
      console.log({data, index}) // run before fetch call
    },
    onError(error, status, index) {
      console.log({error, status, index}) // run if request status is not a 200 group status exemple:(500, 400 or 300)
    }
  }
})

API Reference

ProgressForm

• constructor(form: HTMLFormElement, enableDefaultCssStyle: boolean = true)

  • Initializes a new ProgressForm instance.
  • form: The HTML form element to be managed.
  • enableDefaultCssStyle: Whether to apply default CSS styles (default: true).

• run(progressOptions?: ProgressFormType, styleOptions?: StyleOptions, preventProgress?: PreventType)

  • Starts the form progression.
  • progressOptions: Configuration for form progression (e.g., transition effects).
  • styleOptions: Custom styles for the form.
  • preventProgress: Conditions under which progression should be prevented.

• next(nextIndex: number, nextTranslateX: number, nextButton?: HTMLElement, progressElement?: HTMLElement, nextProgress?: number)

  • Handles the "Next" button click event.
  • nextIndex: Index of the next fieldset.
  • nextTranslateX: X translation value for the transition.
  • nextButton: The button element that triggered the action.
  • progressElement: Element displaying progress.
  • nextProgress: Progress value.

• prev(prevIndex: number, prevTranslateX: number, prevButton?: HTMLElement, progressElement?: HTMLElement, prevProgress?: number)

  • Handles the "Previous" button click event.
  • prevIndex: Index of the previous fieldset.
  • prevTranslateX: X translation value for the transition.
  • prevButton: The button element that triggered the action.
  • progressElement: Element displaying progress.
  • prevProgress: Progress value.

LazyProgressForm

• constructor(form: HTMLFormElement, url: string, parentTarget?: string)

  • Initializes a new LazyProgressForm instance.
  • form: The HTML form element to be managed.
  • url: URL to fetch fieldsets from.
  • parentTarget: Optional CSS class for the parent container.

• lazyRun(fieldsetLength: number, progressOptions?: ProgressFormType, styleOptions?: StyleOptions)

  • Initializes the lazy loading process.
  • fieldsetLength: Number of fieldsets.
  • progressOptions: Configuration for form progression.
  • styleOptions: Custom styles for the form.

• fetchNextFieldSet(data: FieldSetGetterData)

  • Fetches and displays the next fieldset.
  • data.template: The template for the fieldset.
  • data.spinner: Spinner or loading indicator.
  • data.shouldRepost: Whether to post a fieldset's data when its "next" button is clicked again.
  • data.extraData: Additional data to add to the form at each step
  • data.callbacks

Customization Options

StyleOptions

Customize the appearance of your form using the following options:

• form: Styles for the form element.
• fieldset: Styles for the fieldset elements.
• fieldsetContainer: Styles for the container holding the fieldsets.

ProgressFormType

Configure form progression with these options:

• translateX: X translation value for the transition effect.

PreventType

Define conditions under which form progression should be prevented.

Conclusion

The ProgressForm library offers a powerful and flexible solution for creating dynamic, multi-step forms with a user-friendly progress bar. Whether you need a simple form or a more complex form with lazy loading capabilities, this library provides the tools and customization options to meet your needs.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• GitHub Repository
• npm Package
• Documentation

For more detailed information and examples, please refer to the official documentation and resources provided.