Coffeekraken-s-ajax-form-component NPM

Coffeekraken s-ajax-form-component

Provide a simple and declarative way to send a form through ajax with a success/error display mecanism built in.

Features

Simple declarative way to send a form through ajax
Keep track of the form status through simple loading, error and success attributes
Display the success/error message easily
Many more...

Table of content

Install

npm install coffeekraken-s-ajax-form-component --save

Get Started

First, import the component into your javascript file like so:

import SAjaxFormComponent from 'coffeekraken-s-ajax-form-component'

Then simply use it inside your html like so:

<form is="s-ajax-form" action="..." method="POST">
	<div s-ajax-form-success>
		Your message has been sent successfuly
	</div>
	<div s-ajax-form-error>
		Something went wrong...
	</div>
	<!-- your form here... -->
</form>

Form status

When your form is bein/has been sent with success, or maybe not, it will take one a another attribute depending on the state. Here's the two attributes:

loading: When the form is currently sending data
success: When the form has been sent with success
error: When the form has not been sent correctly

Display state timeout

You can specify a timeout in order to automatically remove the state attributes by using the state-timeout property like so:

<form is="s-ajax-form" state-timeout="4000" ...>
</form>

This will make the error or success attribute to be removed 4 seconds after the form submission.

Success/error message display mecanism

The webcomponent integrate a simple but powerful way to handle the success/error display of your form. This mecanism start with two attributes that you can add to any HTMLElement that will hold the success/error message. Here's the two attributes:

s-ajax-form-success: Put this attribute on the element that (will) hold your success message
s-ajax-form-error: Put this attribute on the element that (will) hold your error message

When the form has been sent, depending on the response status, the form will be in success or error state. The according HTMLElement will then have the active attribute on itself.

If the form has been sent with success, the s-ajax-form-success HTMLElement will have the active attribute.
If the form has not been sent properly, the s-ajax-form-error HTMLElement will have the active attribute.

Here's a simple example:

<form is="s-ajax-form" action="..." method="POST">
	<div s-ajax-form-success>
		Your message has been sent successfuly
	</div>
	<div s-ajax-form-error>
		Something went wrong...
	</div>
	<!-- your form here... -->
</form>

Inject success/error message from the response

Let's consider our server response like so:

{
	"status": "OK",
	"code": 200,
	"message": "Your message has been sent"
}

You can then tell your s-ajax-form-success HTMLElement to display the message response property by setting it like so:

<form is="s-ajax-form" ...>
	<div s-ajax-form-success="message" timeout="4000"></div>
	<!-- your form here... -->
</form>

When our form has been sent with success, the component will take the s-ajax-form-success attribute value and use it as a path inside our response to get the text to inject inside the HTMLElement itself before display it.

The same principle goes for the s-ajax-form-error HTMLElement

Display timeout

Each s-ajax-form-success and s-ajax-form-error HTMLElement support a timeout attribute that tells the component how many times to display the reply. Here's a simple example:

<form is="s-ajax-form" ...>
	<div s-ajax-form-success timeout="4000">
		Your message has been sent.
	</div>
	<div s-ajax-form-error timeout="6000">
		Something went wrong...
	</div>
	<!-- your form here... -->
</form>

If you don't specify any timeout, the default value will be the stateTimeout property described above.

Browsers support

IE / Edge	Firefox	Chrome	Safari
IE11+	last 2 versions	last 2 versions	last 2 versions

As browsers are automatically updated, we will keep as reference the last two versions of each but this component can work on older ones as well.
The webcomponent API (custom elements, shadowDOM, etc...) is not supported in some older browsers like IE10, etc... In order to make them work, you will need to integrate the corresponding polyfill.

Contribute

This is an open source project and will ever be! You are more that welcomed to contribute to his development and make it more awesome every day. To do so, you have several possibilities:

Who are Coffeekraken

We try to be some cool guys that build some cool tools to make our (and yours hopefully) every day life better.

License

The code is available under the MIT license. This mean that you can use, modify, or do whatever you want with it. This mean also that it is shipped to you for free, so don't be a hater and if you find some issues, etc... feel free to contribute instead of sharing your frustrations on social networks like an asshole...