DataTables logo
≡

uploadMany

Since: Editor 1.5

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

Description

The uploadMany field is very similar to its singular partner, upload, but allows multiple files to be uploaded and assigned in a single field. This can be useful for cases where you might have multiple supporting documents for a single field - for example photos for an article or PDF case documents.

The UI presented to the end user allows them to upload one or more files at a single time, through either a drag-and-drop interface, or a standard file selection dialogue. Files assigned to the field's value (which must be an array of file identifiers) are shown in a display list below the upload control, and the display option (detailed below) can be used to tell the field how they should be rendered (this could be a file name, file size, image, icon, etc). Files can be added to the field's value at a time, including after the row's initial creation, and also removed individually using a x button presented next to each item's rendered display.

The file upload is performed asynchronously to the main form - i.e. as soon as a file is selected it is immediately uploaded to the server and the field adds 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) to its own array of value. This array of field values is then submitted as part of the standard form.

The uploadMany field type is supported on the server-side by the Upload (PHP | .NET) and mjoin (PHP | .NET) classes available in Editor's standard libraries. 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. array value - Array of file identifiers 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.

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 two parameters. First, 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. Second, the number of the file being added, counting from zero (the first file is number 0, the second will be number 0, etc.).

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.uploadMany 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 processing property of i18n.field.uploadMany if not provided as part of the field's configuration object.

limit

Limit the number of files that can be uploaded using this control. The default of 0 means unlimited. When the defined limit is reached the upload button and drag area are removed from the form. If the user deletes some files from the list, allowing space for new files to be uploaded, the upload button and drag area will automatically reappear.

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.uploadMany 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.uploadMany 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.uploadMany 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 uploadMany field type that displays images:

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

Disable drag and drop - show a file name:

new DataTable.Editor({
	ajax: 'php/press.php',
	table: '#press',
	fields: [
		{
			label: 'Supporting documents:',
			name: 'docs[].id',
			type: 'uploadMany',
			display: function (val) {
				return table.file('files', fileId).fileName;
			},
			dragDrop: false,
			clearText: 'Remove file'
		}
		// additional fields...
	]
});

Listen for an upload event:

new DataTable.Editor({
	ajax: 'php/staff.php',
	table: '#staff',
	fields: [
		{
			label: 'Images:',
			name: 'files[].id',
			type: 'uploadMany',
			display: function (val) {
				return '<img src="' + table.file('files', fileId).webPath + '"/>';
			}
		}
		// additional fields...
	]
});
$(editor.field('files[].id').input()).on('upload.editor', function (e, val) {
	console.log('Images field has changed value', val);
});

Related

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

Events
Options