Register | Sign in

Tutorial | Creating a form using the API

In this tutorial we'll see how to use the API to create an Editor instance, using the API rather than the fields initialisation options and built in TableTools button extensions. The advantage of being comfortable using the API to manipulate Editor is that it opens a wide range of dynamic options such as adding and removing fields from the table as you need. This tour of the API is intended to give you that confidence and the knowledge to work with the Editor API and then progress to using the API documentation to take your Editor designs to the next level.

The table shown below is the one that we will be working toward building in this tutorial. Note that the Edit and Delete controls are inline with the table - working with the API you have the option of using virtually any interaction method you wish to implement, rather than being constrained to the built in options.

Browser Rendering engine Platform(s) Engine version CSS grade Edit Delete
Browser Rendering engine Platform(s) Engine version CSS grade Edit Delete

Initialising the DataTable and Editor

Let's start by initialising our DataTable with an Ajax source for the data source that uses objects (see the DataTables blog on mDataProp for more information about using JSON data sources with DataTables). This is done as follows - note the use of sDefaultContent to create the Edit and Delete HTML for the table:

$('#example').dataTable( {
	"sAjaxSource": "/release/DataTables/extras/Editor/examples/php/browsers.php",
	"aoColumns": [
		{ "mDataProp": "browser" },
		{ "mDataProp": "engine" },
		{ "mDataProp": "platform" },
		{ "mDataProp": "version", "sClass": "center" },
		{ "mDataProp": "grade", "sClass": "center" },
		{
			"mDataProp": null, 
			"sClass": "center",
			"sDefaultContent": '<a href="" class="editor_edit">Edit</a>',
			"bSortable": false,
			"bSearchable": false
		},
		{
			"mDataProp": null, 
			"sClass": "center",
			"sDefaultContent": '<a href="" class="editor_remove">Delete</a>',
			"bSortable": false,
			"bSearchable": false
		}
	]
} );

Next we want to create our Editor instance and assign the fields that will be present in the form. In keeping with our use of the API, rather than using the fields initialisation option, we use the add API method. This method, along with the clear method, allows the fields presented in the form to be dynamically changed. We don't make use of that in this example, but you could imagine a case where the 'create' form shows additional fields compared to the 'edit' form, or depending on the data to be edited, different fields could be dynamically added and removed from the form.

var editor = new $.fn.dataTable.Editor( {
	"ajaxUrl": "/release/DataTables/extras/Editor/examples/php/browsers.php",
	"domTable": "#example"
} );

editor.add( [ 
	{
		"label": "Browser:",
		"name": "browser"
	}, {
		"label": "Rendering engine:",
		"name": "engine"
	}, {
		"label": "Platform:",
		"name": "platform"
	}, {
		"label": "Version:",
		"name": "version"
	}, {
		"label": "CSS grade:",
		"name": "grade"
	}
] );

Add new rows

To add new rows to the table we can use the create API method, attached to the HTML 'add' button that is above our table using standard jQuery events. The create method has three parameters that can be passed to it: 1. the title for the form, 2. button definitions that will be displayed and 3. the option to show the form or not. We'll use the first two parameters here to firstly state that the form being shown is an 'add' form, making it clear to the end user what is happening, and the second parameter to put a button at the bottom of the form that will allow the end user to submit the data to the server.

The button options of Editor apply to the three primary API methods (create, edit and remove) and allow you to provide some advanced interaction controls (or very simple ones if you wish!). In this case we are simply going to attach a submit action to our button, but we could readily have a cancel button (using the close API method), or an option to add the row and then show another add form (for entering multiple items quickly). The options available for the buttons are defined in the buttons documentation.

$('button.editor_create').on('click', function (e) {
	e.preventDefault();

	editor.create(
		'Create new record',
		{
			"label": "Add",
			"fn": function () {
				editor.submit()
			}
		}
	);
} );

Edit rows

The edit option we implement here is very similar to the create action above, but in this case we use the edit method. The edit method takes one extra parameter, compared to the create method - the TR row to be edited. We get this from the jQuery event handler that is assigned to the link tags with a class of "editor_edit" using the parents method of jQuery. We also have our title and button definition as defined before:

$('#example').on('click', 'a.editor_edit', function (e) {
	e.preventDefault();

	editor.edit(
		$(this).parents('tr')[0],
		'Edit record',
		{
			"label": "Update",
			"fn": function () { editor.submit(); }
		}
	);
} );

Delete rows

To delete rows we use the remove method. Again this method takes the TR element we wish to act upon and button options. One option that the API presents here is that you can delete the row without asking the end user for confirmation of their action, simply by instructing remove to not display the Editor form (fourth parameter given as false) and then calling the submit method to immediately submit the form. However, in our example here we do ask for user confirmation. Note also the use of the message method to display a confirmation message to the end user in the Editor pane. The message method can be used at any time to show information to the end user about the form, not just when deleting an item.

$('#example').on('click', 'a.editor_remove', function (e) {
	e.preventDefault();

	editor.message( "Are you sure you want to remove this row?" );
	editor.remove(
		$(this).parents('tr')[0],
		'Delete row', 
		{
			"label": "Update",
			"fn": function () {
				editor.submit()
			}
		}
	);
} );

Putting it all together

Combining our Javascript into a jQuery document ready function we have the code that follows, and produces the table at the top of this page.

As you have seen, the Editor API can be used to produce highly configurable, dynamic forms quickly and and easily!

$(document).ready(function() {
	// Create the form
	var editor = new $.fn.dataTable.Editor( {
		"ajaxUrl": "/release/DataTables/extras/Editor/examples/php/browsers.php",
		"domTable": "#example"
	} );

	editor.add( [ 
		{
			"label": "Browser:",
			"name": "browser"
		}, {
			"label": "Rendering engine:",
			"name": "engine"
		}, {
			"label": "Platform:",
			"name": "platform"
		}, {
			"label": "Version:",
			"name": "version"
		}, {
			"label": "CSS grade:",
			"name": "grade"
		}
	] );

	// New record
	$('button.editor_create').on('click', function (e) {
		e.preventDefault();

		editor.create(
			'Create new record',
			{
				"label": "Add",
				"fn": function () {
					editor.submit()
				}
			}
		);
	} );

	// Edit record
	$('#example').on('click', 'a.editor_edit', function (e) {
		e.preventDefault();

		editor.edit(
			$(this).parents('tr')[0],
			'Edit record',
			{
				"label": "Update",
				"fn": function () { editor.submit(); }
			}
		);
	} );

	// Delete a record
	$('#example').on('click', 'a.editor_remove', function (e) {
		e.preventDefault();

		editor.message( "Are you sure you want to remove this row?" );
		editor.remove(
			$(this).parents('tr')[0],
			'Delete row', 
			{
				"label": "Update",
				"fn": function () {
					editor.submit()
				}
			}
		);
	} );

	// DataTables init
	$('#example').dataTable( {
		"sAjaxSource": "/release/DataTables/extras/Editor/examples/php/browsers.php",
		"aoColumns": [
			{ "mDataProp": "browser" },
			{ "mDataProp": "engine" },
			{ "mDataProp": "platform" },
			{ "mDataProp": "version", "sClass": "center" },
			{ "mDataProp": "grade", "sClass": "center" },
			{
				"mDataProp": null, 
				"sClass": "center",
				"sDefaultContent": '<a href="" class="editor_edit">Edit</a>',
				"bSortable": false,
				"bSearchable": false
			},
			{
				"mDataProp": null, 
				"sClass": "center",
				"sDefaultContent": '<a href="" class="editor_remove">Delete</a>',
				"bSortable": false,
				"bSearchable": false
			}
		]
	} );
} );