beforeupload

note

This article is about the beforeupload UDB event handler.

beforeupload

The beforeupload event may be called from web pages developed in Web Designer and processed by a USoft page engine service.

Event	Applies to	Occurs when
beforeupload	File upload controls	Before the file-selection dialog for an upload is opened

This event is triggered by the FileUploadControl class, from its show() method, on the control's own element. show() is called whenever an upload cycle is initiated (for example via the public udbUpload() action), and it triggers beforeupload only if the control is mounted and the user is logged in — before the file-selection dialog is opened.

See also uploadcomplete, which fires much later, after the server confirms that a file has actually been uploaded.

Purpose

You can use this event restrictively to keep the user from starting an upload if some precondition is not satisfied.

How to use

Find or create an Event Listener object with Event Type = beforeupload. Event Listeners are in the Web Designer Controls catalog:

Insert the event listener into the file upload control. Insert a callClientScript action into the event listener. Use this action's Script property to code the behaviour that you want to see when the event occurs. For example, for restrictive action, a typical pattern is to specify the condition under which you want the upload to be prevented, block processing, and give an error message in an alert box. This pattern looks like this:

if ( *condition-not-satisfied* ) {
  options.success = false;
  alert( *message* );
}

You are implicitly associating the event with an event handler function. This function has an options parameter. For available options, see the Options section at the end of this help topic:

function(*event*, *options*){ ... }

Or you can create the event handler more explicitly by attaching a jQuery handler on the control's element.

Options

When the event occurs, the following event handler function is called. You can use this function's options parameter in your event scripting.

function( *event*, *options* )

*event*     ::=  jQuery.Event
*options*   ::=  *event-options*

*event-options*   ::=  {
     success:  *success*,
     params:   *params*
}

*success*  ::=  { [true] | false }

Event contains the run-time details of the triggered event, of the event type stated above.

This syntax means that you can access an option by scripting

options.*option*

Success is true by default. If you set success to false in your handler, processing is interrupted: the upload is cancelled and the file-selection dialog never opens.

Params is the params object that was passed into the control's show() call, typically shaped like { props: { checkFiles, ...upload configuration, ...caller-supplied options } }.