$.udb.upload()

note

This article is about the upload() function of the udb object.

$.udb.upload()

Handles a request for uploading one or more submitted files to the server's file system.

This function allows you to script a fully customised file-upload facility, as opposed to relying on the predefined options of Web Designer's FileUploadControl control class.

One advantage of custom scripting is that you are not restricted to predefined validation rules but instead, you can provide validation rules on-the-fly using runtime variables. One downside of custom scripting is that you cannot offer a drag-drop area to drop files on: the only option you have is to offer a file selection dialog.

note

If not logged in, then this function will return a rejected UdbPromise, which can be handled with a .catch() clause. To processs successful uploads, you should use a .then() clause.

Returns a UdbPromise object.

Syntax

$.udb.upload( *options* )
.then( ([result]) => {
    // ...
})
.catch( (*reason*) => {

}).finally(() => {
    // ...
});

*options*  ::=  {
    [target]:            *target*,
    [extensions]:        *extensions-array*,
    [params]:            *custom-params*,
    [maxSize]:           *max-size*,
    [maxNameLength]:     *max-name-length*,
    [multiple]:          *multiple*,
    [retryLimit]:        *retry-limit*,
    [showDialog]:        *show-result-dialog*,
    [checkFiles]:        *check-files*,
    [submitImmediately]: *submit-immediately*

}

*extensions*            :=  Array[*extension*]
*custom-params*         :=  { name : value, ... }
*max-size*              :=  Number[5]
*max-name-length*       :=  Integer[175]
*multiple*              :=  { [true] | false }
*retry-limit*           :=  Integer[0]
*show-result-dialog*    :=  { [true] | false }
*check-files*           :=  { true   | [false] }
*submit-immediately*    :=  { [true] | false }

Options is a struct that can contain the following items, all of which are optional.

Target is a string representing the (relative) target URI or URL where the uploaded files must be sent to. By default it is the endpoint for the Page Engine Resource defined in Service Definer, i.e. 'fileupload'. Usually this is enough to handle the upload correctly, unless the application uses a completely different (own) method of handling uploaded files.

warning

For security reasons, only use relative URIs or URLs that are in the same domain of the web application. Deviations may result in security risks or in disfunctional upload handling.

Extensions is a string array used to contain the allowed extensions for files to be uploaded. The default is the empty array [], which means that all extensions are allowed.

Custom-params is a JSON struct of name-value pairs that are needed for the upload process on the server. By default, the object is an empty object.

Max-size is a real number, i.e., an integer or a fractional number, indicating in MBs the maximum size for each file allowed for uploading. The default is 5, which means that files with a maximum size of 5MB are allowed.

Max-name-length is an integer indicating the maximum number of characters in the name of the uploaded file(s). The default is 175 characters.

Multiple is a boolean that determines whether or not it is allowed to upload multiple files in 1 operation. By default, multiple file selections are allowed.

Retry-limit is an integer indicating the maximum number of times that an upload request may be attempted again if the first time would fail. The default is 0 times, which means that no repeat attempts are allowed.

Show-result-dialog is a boolean indicating whether a dialog is shown reporting on the result of the file-upload operation. The default is true, which results in no result object being passed to the subsequent .then() clause. If show-result-dialog is set to false, then the .then() clause following the $.udb.upload() call will receive the result details, so that they can be used to create some custom result view with them.

Check-files is a boolean that determines whether the user must explicitly confirm the selected file(s) before they are validated and uploaded. If set to true, a dialog listing the name and size of each selected file is shown first, and validation only proceeds once the user confirms; cancelling discards the selection instead. The default is false, which validates and proceeds straight to the upload without this confirmation step.

Submit-immediately is a boolean that determines whether a file selection, once it has passed validation, is uploaded to the server right away. The default is true. If set to false, the upload is held pending instead of being sent immediately; it is only actually sent when the script later calls $.udb.upload('submit') — passing the literal string 'submit', instead of an options object, submits any pending upload(s) in the current context.

The resulting object has the following syntax:

*result*  ::= {
    *success*:    { true | false }
    *params*:     *options*
    *files*:      *files-details*
}

*files-details*  ::= {
    *uploaded*:     Array[*file*]
    *invalid*:      *rejected-files-details*
}

*rejected-files-details* ::= {
    [ext]:   Array[*file*]
    [name]:  Array[*file*]
    [size]:  Array[*file*]
}

*file* ::=   {
    *file*:    *file-name*,
    *size*:    *file-size*,
    *success*: { true | false},
    [reason]:  *reason-string*
}

The three parameters in the result object will always be present:

• success denotes if the upload in general has been successful. It is true if at least one file was uploaded.

• params contains all the parameters you have passed to the function in its options parameter. Any default values are added as well.

• files contains the details of the files you have selected. This object contains an array of the uploaded files (regardless of success or not), and another object with the details of the files that were rejected before uploading, e.g. because they did not meet any of your restrictions. There are three flavors here:

Name	Description
ext	File rejected by a disallowed extension
name	File rejected by length of name
size	File rejected by being too large

These files will not be included in the uploaded files list. Instead, here you will find files that were uploaded, and processed. If the server also rejected a file, the entry in the uploaded array will contain a reason for the rejection. Otherwise, it will contain just the name and size. The success field shows if the uploaded file was accepted or not.

note

If the upload had failed, then the resulting promise will be a rejected one. Use a .catch() clause to handle these.

Example

$.udb.upload({
    target: 'fileupload',
    extensions: ['pdf', 'doc', 'docx', 'html'],
    maxSize: 10,
    params: {
        SUBJECT_ID: $.udb("SUBJECT").rows('current').cols('ID').val(),
        SUB_TYPE: $.udb("SUBJECT").rows('current').cols('SUBTYPE').val()
    }
})
.then(() => {
    //handle successful upload
})
.catch(() => {
    //deal with rejected upload
});

Related events

Event	Applies to	Occurs when
beforeupload	File upload controls	Before the file-selection dialog for an upload is opened
uploadcomplete	File Upload controls (FileUploadControl)	When the front-end has received a signal from the server that a file upload has completed, whether it succeeded or failed

note

Even though .upload() lets you script a fully customised upload flow instead of using a FileUploadControl placed in Web Designer, it still creates (or reuses) a hidden FileUploadControl instance behind the scenes and calls its show() method, which is what triggers beforeupload and, later, uploadcomplete.