submit()

Since: Editor 1.0

Submit a form to the server for processing.
Please note - this property requires the Editor extension for DataTables.

Description

Submitting modified data to the server for storage and future retrieval is of course a key building block in Editor. This method provides that ability, submitting the form data that has been initiated using the create(), edit(), remove(), bubble() or inline() methods, and the values input by the user or through the API.

On complete the actions that Editor performs will depend upon the data editing mode of Editor:

DataTables (i.e. the table option was provided in the initialisation):
- Create: A new row will be added to the DataTable with the new data
- Edit (including bubble and inline editing): The data in the existing row will be updated
- Remove: The rows requested for removal will be dropped.
Standalone:
- Edit (including bubble and inline editing): The data in the fields will be updated
- Note that standalone editing can be used with the create and remove actions, but the form data will simply be updated for each, rather than fields being dynamically added or removed from the page, as they would be in a DataTable.

These actions are carried out by Editor automatically and cannot be modified directly through the callback functions or events (although you could alter the updated display if required).

Type

`submit( [ success [, error [, formatData, [ hide ] ] ] ] )`

Submit a configured form to the server for processing.

Parameters:

	Name	Type	Optional
1	`success`	`function`	Yes - default:null
	Callback function that is executed once the form has been successfully submitted to the server and no errors occurred. The function specified is passed in a single parameter, the JSON data returned from the server. This action can also be achieved using the `submitSuccess` event.
2	`error`	`function`	Yes - default:null
	Callback function that is executed if the server reports an error due to the submission (this includes a JSON formatting error should the error return invalid JSON), This action can also be achieved using the `submitError` event.
3	`formatData`	`function`	Yes - default:null
	Callback function that is passed in the data that will be submitted to the server, allowing pre-formatting of the data, removal of data or adding of extra fields. This action can also be achieved using the `preSubmit` event which is generally preferred as it will be applied to all submissions made by Editor, not just this method call.
4	`hide`	`boolean`	Yes - default:true
	When the form is successfully submitted, by default the form display will be hidden - this option allows that to be overridden (`true` to hide the form, `false` to keep it visible). Since Editor 2.4 the form will be left in the same state - i.e. if you were editing a record, you would be able to submit it again without restarting the edit on the row in question, or for row creation the user can quickly enter multiple rows with similar values.

Returns:

DataTable.Editor: Editor instance

Examples

Submit data from a form button:

editor
	.title('Add new record')
	.buttons({
		label: 'Save',
		fn: function () {
			this.submit();
		}
	})
	.create();

Submit without showing the user the form:

editor
	.create(false)
	.set('name', 'Allan')
	.set('access', 'all')
	.submit();

Provide success and error callback methods:

editor
	.create(false)
	.set('name', 'Allan')
	.set('access', 'all')
	.submit(
		function () {
			alert('Form successfully submitted!');
		},
		function () {
			alert('Form  encountered an error :-(');
		}
	);

Add an extra field to the data:

editor
	.title('Add new record')
	.buttons({
		label: 'Save',
		fn: function () {
			this.submit(null, null, function (data) {
				data.extra = 'Extra information';
			});
		}
	})
	.create();

Don't hide the form immediately - change the title and then close the form after a small amount of time:

editor
	.title('Add new record')
	.buttons({
		label: 'Save',
		fn: function () {
			this.submit(
				null,
				null,
				function (data) {
					var that = this;

					this.title('Data successfully added!');

					setTimeout(function () {
						that.close();
					}, 1000);
				},
				false
			);
		}
	})
	.create();