modo.Uploader

This provides a file upload element where the user can pick one or multiple files from his harddrive to get them uploaded to a server.

Please note that you need to use serverside scripts to utilize this element. The modo.Uploader element will send the file(s) in the POST field file.

File uploads can be processed by either the "classic" POST transfer (with an invisible iframe), or via AJAX, which adds progress reporting to the process. The classic approach is more robust, but won't give you any information about the uploads' progress.

Constructor

modo.Uploader(params)modo.Uploader

The following list of parameters can be used in the params object, passed to the constructor. Parameters in [brackets] are optional.

Property	Description
target	URL where the file upload should be sent to
[label]	Label for the upload button. Defaults to Upload.
[mimeFilter]	Will be passed to the incorporated <input type="file"> element to limit the mimetype of the pickable file(s)
[autostart]	Should the upload start immediately after a file has been chosen? Defaults to false
[ajax]	Set this to true to send the files via AJAX and not with the classic iframe approach. If the browser does not support AJAX file uploads, the setting will be ignored. Defaults to false
[multiple]	Allow the user to select multiple files to be uploaded. Defaults to false
[className]	A string with custom CSS classes to apply to the generated DOM element
[dataAttributes]	A object with attributes to assign to the generated DOM element. Omit the "data-" part. So for example {count: 1} becomes data-count="1" on the DOM element.
[el]	The jQuery enhanced DOM element to be generated. If nothing is set, a standard DIV container will be created. If you want to use a different DOM element, pass a jQuery generated DOM element to this parameter.
[showEffect]	The default show effect for the element. See associated property description. Default: null
[hideEffect]	The default hide effect for the element. See associated property description. Default: null

Properties

Inherited Properties from modo.Element

elObject

Contains the jQuery enhanced DOM Node of this modoJS element.

modoIdNumber

Contains a internally given, numeric ID for this element.

visibleBool

Will be set by .show() and .hide(). Access this property to check the current visibility of the element.

showEffectobject

Set a default show effect (like the options you can pass to the show() / hide() methods.

Example:

element.showEffect = {
    effect: 'slideDown',
    effectArgs: ['fast']
};

hideEffectobject

Define a default hide effect instead of a simple, instant hide.

Methods

clear(options)this

Call this to clear any selection a user has been made before. Pass {silent: true} as options parameter to avoid triggering the clear event.

getFiles()fileList

Returns a list of files, the user has selected before.

upload()this

Will manually trigger the upload of any selected files. Needs to be called, if autostart has not been set to true in the constructor.

setStatus(value)this

This will set the status label of the upload element to the given string. You can use this to display information about the upload progress.

setTarget(url)this

Overwrite the target URL where the files should be uploaded against.

enable()this

Enables the button to capture clicks. Removes the CSS-Class mdo-disabled from its DOM element. Triggers the Backbone Event "enabled".

disable()this

Disables the button to not capture any clicks. Adds the CSS-Class mdo-disabled to its DOM element. Triggers the Backbone Event "disabled".

Inherited Methods from modo.Element

setFlexible([value])this

Pass either true or false to this value to make the element stretch inside a modo.FlexContainer element.

show(options)this

Make the connected DOM object visible and trigger the Backbone Event "show".

You can control the way the element is shown by passing an object of options.

Example:

element.show({
    effect: 'slideDown',
    effectArgs: ['fast']
});

hide()this

Make the connected DOM object invisible and trigger the Backbone Event "hide".

You can control the hide effect the same way as with the show() method.

addClass(classname, doPrefix)this

Will add another class name to the DOM element. The class name will be automatically prefixed (i.e. with mdo-) if doPrefix = true (default).

removeClass(classname, doPrefix)this

Will remove a class name from the DOM element. The class name will be automatically prefixed.

addClassTemporary(classname, timeout, doPrefix)this

Helps with adding a classname temporarily to the object. Just call this method and after the specified amount of time, the added class(es) will be removed.

---

Note: All modoJS Objects are extended with all methods of the Backbone.Events class.

---

Events

change

Triggered, when the user has selected one or more files.

The first event parameter is a list of the selected files.

clear

Triggered, when the users file selection has been cleared through the call of clear().

upload:start

Triggered when the upload has begun.

upload:progress

Triggered whenever a progress has been made on the file upload. Only being triggered if the element has been created passing ajax = true to the constructor.

The event parameter is an object containing information about the upload progress:

{
    total: 123153453453 //total bytes
    loaded: 80849283423 //uploaded bytes until now
    percent: 65.6492214844 //calculated percentage of the file upload
}

upload:finish

Triggered when the uploader is done sending the file(s) to the server.

The first event parameter is the response text, received from the server.

upload:error

Triggered when an error has occured while sending the files. Only being triggered if the element has been created passing ajax = true to the constructor.

The first event parameter is the response text, received from the server.

enabled

Triggered, when the button has been enabled through enable().

disabled

Triggered, when the button has been disabled through disable().

Inherited Events from modo.Element

show

Triggered, when the object has been displayed through show()

hide

Triggered, when the object has been hidden through hide()

CSS Classes

mdo-uploader

Applied on the element itself.

mdo-uploader-button

Applied to the button element (additionally to the default .mdo-button class) the user can click on to select a file.

mdo-uploader-status

Applied to the status label next to the button that should display additional information during the upload.

mdo-uploader-uploading

Applied to the element itself, while an upload is in progress.

mdo-uploader-selected

Applied to the element itself, when a file selection currently exists.

mdo-disabled

Applied when the element has been disabled through disable(). Will be removed after a call to enable().

Inherited CSS Classes from modo.Element

mdo-element

Basic class that will be applied to every element that extends modo.Element.

mdo-flexible

Will be applied to every modo element where setFlexible(true) has been called upon.