A collection of jquery plugins to help work with ajax forms and action buttons
HTML JavaScript PHP
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
actions
doc
js
vendor
LICENSE
README.md
form.html
index.html
message.html
table.html

README.md

These few jquery plugins are designed to easily work with "ajax actions". Basically, a set of buttons in a table, that should send POST requests to a server automagically... But also forms with many inputs, textarea or select that you'd like to treat with ajax, in one line of code ;)

jquery.messageBox.js

This litte utility is used to display response or error messages from the server, and which can be used to display any message you want.

Started with JQuery 2.0.1, and using Bootstrap CSS classes | License: Creative Common "CC-BY-SA 4.0"

Note: this plugin is required to use other Polosson's ajax plugins.

Basic usage

First, create a hidden DIV or other HTML block, with id="messageBox", somewhere in your html body.

<div class="alert hide" id="messageBox"></div>

Then, on DOM ready, just use:

$.messageBox({
	"cssClass": "alert-danger",
	"message": "Your error message"
});

When alert-success and alert-warning classes are given, the message box will fade out automatically after 3 seconds. With any other classes (like "alert-info" or "alert-danger"), the message box will stay diplayed until you close it with the close button.

Options

There are 4 options available:

  • identifier : The CSS selector for the div where to initialize the message box (default "#messageBox")
  • cssClass : A CSS class to add to the message box (for design purpose) (default "alert-info")
  • message : The message to display (default "")
  • closeBtn : A string to define the close button (like a button, a span with an icon...) (default "x")
$.messageBox({
	'identifier':	"#messageBox",
	'cssClass':	'alert-info',
	'message':	"Your info message",
	'closeBtn':	"x"
});

Bonus

In this file, there are also 3 jquery ajax-events binded:

  • ajaxStart: Send the last ajax error to $.messageBox
  • ajaxStop: Shows a div with id #ajaxLoader (it must be present in your DOM, you can place it where you want, and put anything you want in it - like a spinning icon, some text...)
  • ajaxError: Hides the #ajaxLoader div.

jquery.ajaxPostForm.js

A jquery plugin to help work with ajax forms.

Started with JQuery 2.0.1, and using Bootstrap CSS classes | License: Creative Common "CC-BY-SA 4.0"

Note: this plugin depends on jquery.messageBox.js.

Basic usage

With a collection of inputs, textareas and selects within a <div> (or other container, like <form> or <section>), you can just add this when DOM is ready:

$('#yourFormDiv').ajaxPostForm();

This div must contain a button or submit input that have the class .submitBtn, and the following data- attributes:

Submit button inline parameters

  • data-destination -> string : Path to the server for the POST request REQUIRED
  • data-action -> string : Name of the action to put in request REQUIRED
  • data-extra-params -> object : Some additionnal parameters to send (optionnal)

Options & callbacks

There are 4 options available:

  • submit : The CSS selector for the submit button (default ".submitBtn")
  • minInputLength : Global minimum length for input or textarea fields (default 4)
  • maxInputLength : Global maximum length for input or textarea fields (0 = no limit) (default 0)
  • extraParams : Global additionnal parameters to send (can be null, to be set by inline 'data-' attributes) (default null)
  • liveValidate : Wether to use live validation, i.e. when key is pressend or input changed (default False)
  • liveValidType : Type of event to listen for live validation (default 'change')

There are 3 callbacks available:

  • onSubmit(R) : Invoked when the submit button is pressed. Must return TRUE in order to proceed submit (you can return FALSE, i.e. in case the user don't respect something). R is an object with: R.params -> the request (object) that will be posted, R.message -> The string "Sending request..."
  • onSuccess(R) : Invoked after post request succeeded. R is an object with: R.error -> The string "OK", R.message -> The success message itself (server response)
  • onFail(R) : Invoked when post request failed. R is an object with: R.error -> The string "error", R.message -> The error message itself

Example:

$('#yourFormDiv, #anotherOne').ajaxPostForm({
	'submit': '.submitBtn',
	'minInputLength': 4,
	'maxInputLength': 20,
	'liveValidate': true,
	'liveValidType': 'keyup',
	'extraParams': {
		"happy":"yes",
		"tired":"nope"	// and as many other params as you need
	},
	onValidate: function(problem){
		console.log(problem);
		// the var 'problem' is a string with all problems listed by validate() function.
		// If it's an empty string (""), there is no problem.
		// You can add problems at this point to be displayed if needed.
		return problem;
	},
	onSubmit: function(R){
		console.log(R.params, R.message);
		// Must return TRUE in order to continue.
		return true;	// If returns FALSE, the request won't be sent.
	},
	onSuccess: function(R){
		console.log(R.error, R.message);
	},
	onFail: function(R){
		console.log(R.error, R.message);
	}
});

Fields inline options (data- attributes on form fields)

One option is available to define rules for verification:

data-rules: {"r":(bool),"m":(int),"M":(int),"f":(str)}
	r -> boolean (1 || 0) : Makes the field mandatory if 1
	m -> integer : Minimum length of input or textarear field
	M -> integer : Maximum length of input or textarear field
	f -> string  : Validation type for the field ("email", "password", or "phone")

jquery.ajaxActions.js

A jquery plugin to help work with action buttons in a table of data.

Started with JQuery 2.0.1, and using Bootstrap CSS classes | License: Creative Common "CC-BY-SA 4.0"

Note: this plugin depends on jquery.messageBox.js.

Basic usage

You must create a <table> with:

  • The attributes data-destination="path/to/server" to define the location of the server side action handler, and data-set="table_name" to give the name of the data (i.e. SQL table name)
  • In the <thead>, all <th> must have the following attributes:
    • data-editable="{true or false}" : to tell if these data will be editable
    • data-field="field_name" : to give the data name of the column
    • The column where the action buttons will be must have attribute data-field="__actions"
  • In the <tbody>:
    • each <tr&gt must have the attribute data-row-id="" with the ID of the row.
    • each <td&gt must have the attributes data-field="" that correspond to the data name of the column, and data-value="" which is the current value of the column for this row.
  • The (hidden) <tfoot> must:
    • contain one row with exactly the same structure as one row of the <tbody>, except that the data-value attribute is not needed.
    • the string {{val}} is needed to describe the place where values will be displayed. (i.e. <td data-field="id"># {{val}}</td>) This way you can define custom classes, additionnal strings or html tags surronding the values.
  • All action buttons must have the attributes data-button-action="yourAction". There are 3 predefined actions:
    • "add": To add a row
    • "edit": To edit a row
    • "delete": To delete a row

Then you just have to add this when DOM is ready:

$('#yourTable').ajaxActions();

Example

Here is a basic usage example:

<table data-destination="actions/A_users.php" data-set="users" id="myActionTable">
	<thead>
		<tr>
			<th data-editable="false" data-field="id">ID</th>
			<th data-editable="true"  data-field="name">Name</th>
			<th data-editable="true"  data-field="email">Email</th>
			<th data-editable="false" data-field="__actions">
				Actions <button data-button-action="add">ADD</button>
			</th>
		</tr>
	</thead>
	<tbody>
		<tr data-row-id="1">
			<td data-field="id"	   data-value="1"># 1</td>
			<td data-field="name"  data-value="Polo">User <b>Polo</b></td>
			<td data-field="email" data-value="po@lo.son"><a href="mailto:po@lo.son">po@lo.son</a></td>
			<td data-field="__actions">
				<button data-button-action="edit"  >Edit</button>
				<button data-button-action="delete">Delete</button>
			</td>
		</tr>
	</tbody>
	<tfoot class="hide">
		<tr>
			<td data-field="id"># {{val}}</td>
			<td data-field="name">User <b>{{val}}</b></td>
			<td data-field="email"><a href="mailto:{{val}}">{{val}}</a></td>
			<td data-field="__actions">
				<button data-button-action="edit"  >Edit</button>
				<button data-button-action="delete">Delete</button>
			</td>
		</tr>
	</tfoot>
</table>
<script>
	$(function(){							// Wait for DOM ready
		$('#myActionTable').ajaxActions();	// Plugin initialisation
	});
</script>

More options

Essentially, you can set any action function you need. You simply must be sure that the action name and its function name are the same.

Custom action's functions have 2 parameters available, and 1 global var is available to set:

  • dataSet: the name of the data you specified on the table's data-set attribute
  • rowID: the ID of the row given by the tr's data-row-id attribute The global object variable params is available to define the request to send to the server.

A custom function must return a boolean:

  • TRUE to proceed the ajax call right after the function finish
  • FALSE to proceed later by clicking a data-button-action="submit" button that you create yourself.

Example of simple custom action button:

<table data-destination="actions/A_users.php" data-set="users" id="myActionTable">
	(...)
	<button data-button-action="export">Export a row</button>
	(...)
</table>

Now let's initialize our ajaxActions with a defined "export" method, which defines at the same time the params to pass via POST request:

$('#myActionTable').ajaxActions({
	"export": function(dataSet, rowID){	// custom function for action button "export"
		$.messageBox({"message":"Exporting #"+rowID+" from '"+dataSet+"'..."});
		params["dataSet"] = dataSet, params["rowID"] = rowID;
		return (confirm("Exporting this row to XML file ?"));
	}
});

That's it for now... Have fun!