Skip to content

Options

Jump to bottom Edit New page
Davit Barbakadze edited this page Nov 13, 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 detected. 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 on the server. Obviously that requires some [additional work on server side](https://github.com/moxiecode/plupload/wiki/Chunking).

The whole concept of chunking might be a bit confusing - when you should use it and when you shouldn't, etc. We have the entry in our FAQ about this.

### chunk_size

Default: 0 (disabled)

The size of each chunk in bytes. The value can be a number or a string with byte suffix, e.g.: 204800 or "204800b" or "200kb".

You can read more about the chunking and the way to handle it on server-side in our dedicated entry - here.

## Client-Side Image Resize ### resize

Disabled by default

Images can be downsized on client-side, mainly to save the bandwidth. Perfect solution for thumbs, avatars and such. Currently not recommended for images sensible to quality drop.

  * [width](#resize.width) _Defaults to original width of the image_
  * [height](#resize.height) _Defaults to original height of the image_
  * [quality](#resize.quality) `90`
  * [crop](#resize.crop) `false`
  * [preserve_headers](#resize.preserve_headers) `true`
## Useful Options ### multi_selection _Default_: `true`

This option allows you to select multiple files from the browse dialog. It is enabled by default, but not possible in some environments and runtimes. For example iOS7 (being an ugly update in general) brought the buggiest Safari since like version 1.0, where selection of the multiple files doesn't trigger the onchange event at all (let us know if it is fixed by the time you are reading this). So we had to forcefully disable it there (#905). Also html4 runtime by it's very nature is not compatible with multi_selection option being set to true, so it's disabled there as well.

### required_features

By default Plupload will try to use the runtime that fits the requested configuration the best. But sometimes you might want to hint it to choose only a runtime that fulfills specific requirements and provides particular functionalities. That where required_features option comes in handy.

required_features is of mixed type, it can be a comma-separated string of features to take into account. Or - an object of key/value pairs, where the key represents the required feature and the value must be fulfilled by the runtime in question. Or it can be simply set to true and then the configuration itself will be translated into a corresponding set of features that the selected runtime must have to fulfill the expectations. Without it Plupload will simply consider the options in the configuration (like chunk_size or resize) as optional - in other words fulfilled only when they can be fulfilled by the selected runtime. When required_features are set, runtimes that do not have appropriate capabilities will simply be ignored.

The list of supported features as well as the whole topic in more detail is available - here.

### unique_names

Default: false

When set to true, will generate an unique file name for the uploaded file and send it as an additional argument - name. This argument can then be used by the server-side upload handler to save the file under that name.

## Optional ### runtimes _Default: `"html5,flash,silverlight,html4"`_

Comma separated list of upload runtimes to try. In most cases you do not even need to care about this option. By default, Plupload will try what it thinks is best for your configuration. Or if there are no special requirements it will take html5 first and only if it fails proceed to flash or silverlight or legacy html4, until it finds a runtime that works. If none is compatible, Plupload will fail with the Error event of plupload.INIT_ERROR.

You only need to provide this option if you want to change the order in which runtimes will be tried, or want to exclude some of them at all.

### file_data_name

Default "file"

Value of file_data_name will be used as the name for the 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 pass a different value for file_data_name.

### container

Defaults to a parent node of browse_button

DOM element that will be used as a container for the Plupload html structures. By default an immediate parent of the browse_button element is used. If for some reason such behaviour is undesirable you can pass an id of a specific DOM element or the DOM element itself as the value for the container option.

Sometimes you might want to hide the browse_button after files are selected and some users tend to hide the parent container, which effectively hides the Plupload structures as well. For flash and silverlight runtimes this is equal to disabling, since due to security concerns those runtimes cannot not operate when they are not visible. In such cases better use disableBrowse() instead.

### flash_swf_url

Default: "js/Moxie.swf"

The url of the Flash component, required by the flash runtime. It will fail, if the component is not found or cannot be loaded within a sane amount of time and Plupload will try the next runtime in the list. You do not need to set this option manually if you are using default file structure.

### silverlight_xap_url

Default: "js/Moxie.xap"

The url of the Silverlight component, required by the silverlight runtime. It will fail, if the component is not found or cannot be loaded within a sane amount of time and Plupload will try the next runtime in the list. You do not need to set this option manually if you are using default file structure.

If this paragraph looks like a copy/paste of the flash_swf_url description it's because it - is.

Add a custom footer

Table of Contents

Clone this wiki locally