@easylibs/progress-form
v2.8.38
Published
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 d
Downloads
53
Readme
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
).
- Initializes a new
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.
- Initializes a new
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 stepdata.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
For more detailed information and examples, please refer to the official documentation and resources provided.