Skip to content

Options

Jump to bottom Edit New page
Davit Barbakadze edited this page Nov 12, 2013 · 45 revisions

Table of Contents

## Required Options Plupload has only two required options: [browse_button](#browse_button) and [url](#url). The rest is optional. If any of these is missing, initialization will result in `Error` event with the code of `plupload.INIT_ERROR`. ### browse_button _Required_

Almost any DOM element can be turned into a file dialog trigger, but usually it is either a button, actual file input or an image. Value for the option can be either a DOM element itself or it's id.

### url _Required_

Url of the server-side upload handler that will accept the files, do some security checks and finally move them to a destination folder. Might be relative or absolute.

## Filters ### filters _Default:_ `{}`

Plupload comes with several built-in filters that provide a way to restrict a selection (or perhaps an upload) of files that do not meet specific requirements. These are:

It is also possible to define custom file filters.

### filters.mime_types _Default:_ `[]`

By default any file type can be picked from file selection dialog (which is obviously a rarely desired case), so by supplying a mime_types filter one can constrain it to only specific file types.

For example to allow only images and zip archives:

filters: {
	mime_types : [
		{ title : "Image files", extensions : "jpg,gif,png" },
		{ title : "Zip files", extensions : "zip" }
	]
}

title property will be used as a title for the filter, where supported.

Official format for the accept attribute, where one can supply comma-separated list of mime types, is also supported (but the former one is recommended):

filters: {
	mime_types : "image/*,application/zip"
}

Unfortunately browsers do not always interpret this option consistently (especially in html5 runtime). For example, no matter what, Firefox will still allow to select any file type by default and optionally provide a file filters at the bottom of the selection dialog. In addition to this there are differences in the interpretation of the accept attribute of input[type="file"] itself, for more information check: "Although I specify file extension in filters, I still cannot pick it up in file dialog or drag and drop, why?" entry from our FAQ.

### filters.max_file_size

Default: 0 (unlimited)

By default, file of any size is allowed to the queue. But it is possible to constrain it from the top with the max_file_size filter. It accepts numeric or formatted string values, e.g.: 204800 or "204800b" or "200kb".

If violated, triggers Error event with the code of plupload.FILE_SIZE_ERROR.

### filters.prevent_duplicates

Default: false

If set to true the Plupload will not allow duplicates. Duplicates are detected by matching file's name and size.

If violated, triggers Error event with the code of plupload.FILE_DUPLICATE_ERROR.

## Control the Request ### headers

A way to pass custom HTTP headers with each upload request. The option is simple set of key/value pairs of header names and their values.

  • Not supported by html4 runtime.
  • Requires special operational mode in case of flash and silverlight runtimes.
### multipart _Default:_ `true`

Whether to send the file as multipart/form-data (default) or binary stream. The latter case is not supported by html4 and is a bit troublesome in flash runtime. It also requires a special care on server-side. Here's an excerpt from our bundled upload.php for example:

<?php
...
if (!$in = @fopen("php://input", "rb")) {
	die('{"jsonrpc" : "2.0", "error" : {"code": 101, "message": "Failed to open input stream."}, "id" : "id"}');
}
...
  • Not supported by html4 runtime.
  • flash runtime requires the file to be read in memory first.
### multipart_params

Additional multipart fields to be passed along with each upload request. Each field can be represented by simple key/value pair or some nested arrays and/or objects. For example:

multipart_params: {
	one: '1',
	two: '2',
	three: '3',
	object: {
		four: '4',
		five: '5'
	},
	array: ['6', '7', '8']
}
### max_retries

Default: 0 (no retries)

If max_retries is greater than 0, upload will be retried that many times every time there is plupload.HTTP_ERROR detetcted. Be it complete file or a single chunk.

## Chunk Plupload has a built-in support for chunking: file is split into chunks and uploaded part by part, and then reassembled back to complete file on the server-side. Obviously that requires some [additional care](#send_chunk_number) from upload handler (see below).

For more information see: "When to use chunking and when not?" from our FAQ.

## Useful Options ### multi_selection _Default_: `false`

By default, Plupload lets you select only one file from the browse dialog at a time. Setting multi_selection to true, will allow you to select multiple.

However, this option is not compatible with html4 runtime and will effectively exclude it from the list of potential runtime candidates (even if it is in the list, it will not be used).

## Notable Options ### runtimes `"html5,flash,silverlight,html4"` Usually you do not even need to care about this optionBy default, Plupload will try `html5` first. ### file_data_name `"file"` Value of `file_data_name` will be used as the name for the actual file field in multipart request. So that in PHP, for example, you will be able to access it through: `$_FILES["file"]`. If for some reason you need it to be named differently, you can do it here.
Add a custom footer

Table of Contents

Clone this wiki locally