A handy control for quick and easy uploading of a file or a set of files.

SimpleVault control

Related sample:  Form. All DhxForm Inputs

Related sample:  Form. Simple Vault

Adding SimpleVault

You can easily add a SimpleVault control during initialization of a form:

var form = new dhx.Form("form_container", {
    rows: [
            type: "simpleVault",
            label: "files",
            labelInline: true,
            labelWidth: "50px",


You can provide the following attributes in the configuration object of a SimpleVault:

  • type - (string) the type of a control, set it to "simpleVault"
  • name - (string) the name of a control
  • id - (string) the id of a control, auto-generated if not set
  • value - (array) sets the default list of loaded files. Each file object can contain the following properties:
    • id - (string) mandatory, the id of the file
    • status - (string) optional, the status of the file ("queue", "inprogress", "uploaded", or "failed")
    • progress - (number) optional, the progress of the file upload
    • link - (string) optional, the path to the uploaded file on a server. In order to download files from SimpleVault to the computer, file objects must have the link attribute specified with the path to their location on the server.
    • request - (object) optional, an XMLHttpRequest object sent to server when an upload begins
    • path - (string) optional, the path to the file on the computer starting from the name of the folder (in case a folder with files is added)
    • name - (string) optional, the name of the file including the extension (for adding files from a server)
    • size - (number) optional, the size of the file in bytes (for adding files from a server)
  • width - (string) the width of a control
  • height - (string) the height of a control
  • css - (string) adds style classes to a control
  • disabled - (boolean) defines whether a control is enabled (false) or disabled (true)
  • required - (boolean) defines whether a control is required
  • hidden - (boolean) defines whether a control is hidden
  • label - (string) specifies a label for a control
  • labelWidth - (string|number) sets the width of the label of a control
  • hiddenLabel - (boolean) invisible label that will be used to identify the input on the server side
  • labelPosition - (string) defines the position of a label: "left"|"top"
  • helpMessage - (string) adds a help message to a control
  • preMessage - (string) a message that contains instructions for interacting with the control
  • successMessage - (string) a message that appears in case of successful validation of the control value
  • errorMessage - (string) a message that appears in case of error during validation of the control value
  • gravity - (boolean) arranges form controls evenly throughout the container, depending on the direction of layout ("cols" or "rows"), true by default
  • fieldName - (string) optional, sets the name of the file field in the form data that is sent to the server. By default takes its value from the value of the name property, or, if not specified, from the id attribute.
  • params - (object) optional, adds extra parameters for sending an XMLHttpRequest
  • singleRequest - (boolean) defines whether files are sent in one request, false by default
  • target - (string) mandatory, sets an URL to the server-side script that will process file upload

Working with SimpleVault

You can manipulate a SimpleVault control by using methods (events) of the object returned by the getItem() method.

For example, you can get the value of the control:

var value = form.getItem("simpleVault_id").getValue();

List of the control methods:

  • clear() - clears a value of a SimpleVault control
  • clearValidate() - clears validation of a SimpleVault control
  • disable() - disables a SimpleVault control on a page
  • enable() - enables a disabled SimpleVault control
  • getValue(): any[] - gets the current value of a SimpleVault control
  • hide() - hides a SimpleVault control
  • isDisabled(): boolean - checks whether a SimpleVault control is disabled
  • selectFile() - opens the dialog for selecting a new file (files) for adding to Vault
  • send() - sends a POST request for file upload to a server-side URL (the request URL is specified by the target property). The method can take one optional parameter:
    • params - (object) an object with additional parameters for a request
  • setValue(value: array) - sets value for a SimpleVault control
        "id": "image",
        "name": "image.png",
        "link": "/backend/upload/files/image.png",
        "status": "uploaded",
  • show() - shows a SimpleVault control on the page
  • validate(): boolean - validates a SimpleVault control. Returns the result of validation: true, if a control is valid, otherwise - false

List of the control events:

  • BeforeUploadFile - fires before file upload begins. The event takes one parameter:
    • file - (object) the file object
form.getItem("simpleVault_id").events.on("BeforeUploadFile", function(file) {
    console.log("BeforeUploadFile", file);
    return true;

Returning false from the event handler will prevent file uploading.

  • UploadBegin - fires when file upload begins. The event takes one parameter:
    • files - (array) the array of files to be uploaded
form.getItem("simpleVault_id").events.on("UploadBegin", function(files) {
    console.log("UploadBegin", files);
  • UploadComplete - fires when upload is completed. The event takes one parameter:
    • files - (array) file objects that were uploaded
form.getItem("simpleVault_id").events.on("UploadComplete", function(files) {
    console.log("UploadComplete", files);

The event fires independent of the upload result (fail or success).

  • UploadFail - fires if the file upload failed. The event takes one parameter:
    • file - (object) the file object
form.getItem("simpleVault_id").events.on("UploadFail", function(file) {
  • UploadProgress - fires on each percent of files uploading. The event takes one parameter:
    • progress - (number) the current percent of files uploading, a number from 0 to 100
form.getItem("simpleVault_id").events.on("UploadProgress", function(progress) {
    console.log("UploadProgress", progress);

Using DataCollection API

You can manipulate a SimpleVault control with the help of the DataCollection API.

For example, you can remove one or all files from the list. To do that, you need to apply the remove, or removeAll method of DataCollection to the object returned by the getItem() method as follows:


Check the full list of Data Collection API.

Uploading files

You can read about uploading files into a SimpleVault control in the related article.

Back to top