DataTables logo
≡

upload

Since: Editor 1.5

Single file upload field.
Please note - this property requires the Editor extension for DataTables.

Description

The ability to upload files is an important element in complex forms and data structures. The upload field type provides that ability to Editor by presenting an file upload control to the end user, giving them the option of uploading a single file for the field (the uploadMany field type allows multiple files to be assigned to a single field)

The file upload is performed asynchronously to the main form - i.e. as soon as a file is selected, either via drag-and-drop or a standard file selection control, it is immediately uploaded to the server and the field will take a value that identifies the file (typically this is a database id for a row containing information about the file, but can also be any other identifying data such as a file name). This field value is then submitted as part of the standard form.

The upload field type is supported on the server-side by the Upload class available in Editor's standard libraries (PHP | .NET). Please refer to the documentation for those libraries for how to configure the server-side scripts.

Additionally, an overview of how to configure the upload field types on the client-side is available in the Editor manual. The remaining documentation here is concerned solely with detailing the options available for this field type.

Events

This field type can trigger the following events from the input element (field().input()):

  • upload.editor - Upload complete event - this should be used in place of a change event for this field type. The following parameters are passed in to the event handler:
    1. object event - The event object
    2. Any value - File identifier from the server - normally a primary key value or a file name.

Options

This field type supports the following options (in addition to the default options):

ajax

Ajax URL or DataTable.AjaxOptions configuration object that should be used for the Ajax request to upload a file. If this is property is not give, the value from ajax is used.

As of Editor 1.9 the ajax option can be used as a function allowing complete control over how the data is handled and sent to the server. This also allows fully client-side control of the data - e.g. processing an image in Javascript and submitting to the server as part of the actual form.

As of Editor 3, the ajax.replacements option will operate with this option when used as an object. The action parameter passed in will be upload.

ajaxData

A function that can be used to add additional data that will be submitted to the server with the upload Ajax request. The function is given three parameters:

  1. A single parameter - a FormData object. Use append() to add data to this object.
  2. The File object for the file being uploaded (since 1.9.1)
  3. The file index number being uploaded, for when multiple files are selected (since 1.9.1).

attr

  • Type: object
  • Default: Unset
  • Since: 1.9.1

Set HTML attributes on the input element. This is an object of attribute name / value pairs that are applied to the input element for the field.

clearText

Enable the clear button and set the text to show in the button. When set users will have the ability to click the button which results in the field's value being cleared (i.e. set to be an empty string). When not set, the clear button is not shown and there is no ability to clear the field's value.

This value will default to the clear property of i18n.field.upload if not provided (since 2.4.0).

display

Function which is used to display information about the file that is currently selected by the field's value. This function should return HTML that is shown in the Editor form to describe the file to the end user. It can be a simple descriptive piece of text (a file name for example) or render HTML such as an img tag.

The function is given a single parameter: The value of the field - additional information about the file can be found from the file() method, assuming that database information was given for the Upload class on the server-side - see the upload manual for details.

dragDrop

Enable / disable the drag and drop area allowing uses to drag files from their operating system into Editor. File are automatically uploaded when dropped.

dragDropText

Text to show in the drag and drop area.

Since 2.4.0, this value will default to the dragDrop property of i18n.field.upload if not provided as part of the field's configuration object.

fileReadText

Text shown when a file is being read before it is uploaded. This text will only be visible for large files when the read takes a noticeable amount of time.

Since 2.4.0, this value will default to the uploading property of i18n.field.upload if not provided as part of the field's configuration object.

noFileText

Text to show when no file has been set for the field's value.

Since 2.4.0, this value will default to the noFile property of i18n.field.upload if not provided as part of the field's configuration object.

processingText

  • Type: string
  • Default: Unset
  • Since: 1.7.1

Text shown after the upload of the file has completed, while the server is processing the data. The text will return to uploadText when the processing has finished.

Since 2.4.0, this value will default to the processing property of i18n.field.upload if not provided as part of the field's configuration object.

uploadText

Text shown in the upload file button. This is really an input type="file" input control, but styled to look like a button.

Since 2.4.0, this value will default to the choose property of i18n.field.upload if not provided as part of the field's configuration object.

Methods

This field type does not support any additional methods over the default methods.

Examples

Display an upload field type that displays an image:

new DataTable.Editor({
	ajax: 'php/staff.php',
	table: '#staff',
	fields: [
		{
			label: 'Image:',
			name: 'image',
			type: 'upload',
			display: function (val) {
				return '<img src="' + table.file('files', fileId).webPath + '"/>';
			}
		}
		// additional fields...
	]
});

Disable drag and drop, and enable clearing current value:

new DataTable.Editor({
	ajax: 'php/press.php',
	table: '#press',
	fields: [
		{
			label: 'Press release PDF:',
			name: 'pdf',
			type: 'upload',
			display: function (val) {
				return table.file('files', fileId).fileName;
			},
			dragDrop: false,
			clearText: 'Remove file'
		}
		// additional fields...
	]
});

Listen for an upload event:

var editor = new DataTable.Editor({
	ajax: 'php/staff.php',
	table: '#staff',
	fields: [
		{
			label: 'Image:',
			name: 'image',
			type: 'upload',
			display: function (val) {
				return '<img src="' + table.file('files', fileId).webPath + '"/>';
			}
		}
		// additional fields...
	]
});

$(editor.field('image').input()).on('upload.editor', function (e, val) {
	console.log('Image field has changed value', val);
});

Related

The following options are directly related and may also be useful in your application development.

Events
Options