methodgrab / butter.js

A simple way to submit form data over AJAX with minimal changes to markup and backend code.

Butter.js

A simple way to submit form data over AJAX with minimal changes to markup and backend code.

Examples

Basic

$('form').butter({
	onDone: function(data) {
		$('form').hide();
		$('#success').show();
	}
});

Advanced

// Grab the form element
var $form = $('form');

// Initialise Butter
$form.butter();

// Event handlers
$form
	.on('butterSubmit', function(){
		// Something to indicate the form has been submitted
		myLoadingIndicator('show');
	})
	.on('butterComplete', function(){
		// Remove any load indicators, etc.
		myLoadingIndicator('hide');
	})
	.on('butterFail', function(err){
		// Handle any server side error messages
		displayMyFormErrors(err.msg);
	})
	.on('butterDone', function(success){
		// Hide the form and display a success message
		$form.hide();
		$('#success').text(success.msg).show();
	});

Options

Option	Default	Notes
endpoint	form action attribute	Where the form data will be submitted to.
method	form method attribute	POST, GET, etc.
params	{ name: 'ajax', value: true }	Additional parameters added to the request, if you need to differentiate between normal and AJAX requests on the server.
responseType	json	The expected response format. Other options are: xml, script, or html.
onDone	function(data) { Butter.done() }	Called when the $.ajax function receives a valid response.
onFail	function(data) { Butter.fail() }	Called when the $.ajax function receives an invalid response.
onComplete	function(data) { }	Called when the $.ajax function has completed, regardless of the state of the response.

Events

Events are triggered on the elements that are passed to the function.

• butterSubmit - When Butter has been initialised, just before the AJAX request is made.
• butterDone - When a valid response is received
• butterFail - An invalid response is received
• butterComplete - When the AJAX call has received a response, regardless of it's state

All events have data attached to them.

Why Butter?

Because it makes interactions smooth and tastes delicious with Garlic and Parsley.

Copyright & License

Copyright (C) 2014 HeyHuman

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.