www.dextsolution.com
DEXTUPLOAD
X5
Reference > component

## download

- Version 1.0.0.0 or later

- Explanation

  Start downloading files.

  To download a file, you need to be able to get the path information of the file that exists on the server, using a property of the virtual file.

  By default, only one virtual file can be downloaded. Therefore, only the first file among the targets that match the flag will be downloaded. If you want to download multiple files (supported from 1.1.0.0), set the useMD parameter to true to handle multiple-files-download, and all files matching the flag will be downloaded sequentially.

  The virtual file you want to download must have a server-side address that can be downloaded to the downUrl property. (You can also use the url property from version 1.4.1.0.)

  The destination path must be set using the server's capabilities, so that the Content-Disposition response header value is in the attachment state.

  For file downloads, a HEAD method request is sent to determine if the target exists, and if the HTTP response code is not an error, the download is performed again.

      <script>
        function onDX5Created(id) {
          var dx = dx5.get(id);
          // It is a virtual file that can not be downloaded because there is no download path information.
          dx.addVirtualFile({ vindex: "IDX0001", name: "virtual_file.txt", size: 12345 });
          //  You can download the file because it has a download path.
          dx.addVirtualFile({ vindex: "IDX0003", name: "bridge_509147.jpg", size: 509147, downUrl: "http://domain/path/common-download.do?key=FID0001" });
        }
        function download(id) {
          // Perform to download according to the flag value.
          // AUTO: Download the first virtual file.
          // SELECTED: Download the first selected virtual file.
          // CHECKED: Download the first checked virtual file.
          dx5.get(id).download("AUTO");
        }
        function multidownload(id) {
          // Perform to download according to the flag value.
          // AUTO: Downloads all virtual files.
          // SELECTED: Downloads all selected virtual files.
          // CHECKED: Downloads all checked virtual files.
          dx5.get(id).download("AUTO", true);
        }
      </script>
      <button type="button" onclick="download('component-id');">Single-File-Download</button>
      <button type="button" onclick="multidownload('component-id');">Multiple-Files-Download</button>

  When using the download method, there is a difference from version 1.0.0.0. In the case of single-file-download, in case of 1.0.0.0 version, downUrl is not specified for the target corresponding to the flag value, but downloading is canceled. In 1.1.0.0 version, if the target corresponding to flag value is not specified for downUrl, it finds the next suitable file. Therefore, to download the exact target, we recommend using downloadById instead of download method.

  The multi-file download feature added in version 1.1.0.0 is implemented purely as a browser feature without using plugin technology. Providing a progress window, like a download using a plugin, but because there is a stage where the browser finally stores the file (the product can not participate), messages that query in the browser can be displayed have. In addition, on macOS, we only support Safari browser versions 10.1 and above. And on iOS and iPad, Safari browser version 17 or later supports multi-file downloads (no more than 10 files).

      <script>
        function onDX5Created(id) {
          var dx = dx5.get(id);
          // It is a virtual file that can not be downloaded because there is no download path information.
          dx.addVirtualFile({ vindex: "IDX0001", name: "virtual_file.txt", size: 12345 });
          //  You can download the file because it has a download path.
          dx.addVirtualFile({ vindex: "IDX0003", name: "bridge_509147.jpg", size: 509147, url: "http://domain/path/common-download.do?key=FID0001" });
        }
        function download(id) {
          // Perform to download according to the flag value.
          // AUTO: Downloads all virtual files.
          // SELECTED: Downloads all selectedvirtual files.
          // CHECKED: Downloads all checkedvirtual files.
          dx5.get(id).download("AUTO");
        }
      </script>
      <button type="button" onclick="download('component-id');">Download</button>

- Uses

      // Version 1.1.0.0 or later
      object.download(flag[, useMD]);

- Parameters

  Name | Type | Explanation
  --- | --- | ---
  flag | String | "AUTO", "SELECTED", "CHECKED"
  useMD | Boolean | [Option] If true, perform multiple-files-download; if false, single-file-download is performed.

## downloadById

- Version 1.0.0.0 or later

- Explanation

  Download a virtual file corresponding to a given unique ID.

  To download a file, you need to be able to get the path information of the file that exists on the server, using the properties of the virtual file.

  The virtual file to be downloaded must have a downloadable server-side address set in the downUrl attribute (as of version 1.4.1.0, this can also be done with the url attribute).

      <script>
        function onDX5Created(id) {
          var dx = dx5.get(id);
          // It is a virtual file that can not be downloaded because there is no download path information.
          dx.addVirtualFile({ vindex: "IDX0001", name: "virtual_file.txt", size: 12345 });
          // You can download the file because it has a download path.
          dx.addVirtualFile({ vindex: "IDX0003", name: "bridge_509147.jpg", size: 509147, downUrl: "http://domain/path/common-download.do?key=FID0001" });
        }
        function download(id) {
          var dx = dx5.get(id);
          // Select the second virtual file.
          var itemId = dx.getItemId(1);
          dx.downloadById(itemId);
        }
      </script>
      <button type="button" onclick="download('component-id');">Download</button>

  The download path uses a server-side component, which must have a Content-disposition response header value of attachment.

  In addition, a HEAD method request is sent to determine if the target exists, and the download is performed again if the HTTP response code is not an error.

      <script>
        function onDX5Created(id) {
          var dx = dx5.get(id);
          // It is a virtual file that can not be downloaded because there is no download path information.
          dx.addVirtualFile({ vindex: "IDX0001", name: "virtual_file.txt", size: 12345 });
          // You can download the file because it has a download path.
          dx.addVirtualFile({ vindex: "IDX0003", name: "bridge_509147.jpg", size: 509147, url: "http://domain/path/common-download.do?key=FID0001" });
        }
        function download(id) {
          var dx = dx5.get(id);
          // Select the second virtual file.
          var itemId = dx.getItemId(1);
          dx.downloadById(itemId);
        }
      </script>
      <button type="button" onclick="download('component-id');">Download</button>

- Uses

      component.downloadById(id);

- Parameters

  Name | Type | Explanation
  --- | --- | ---
  id | String | Unique ID of the virtual file to download

## downloadByIdToHD

- Version 2.0.0.0 or later

- Explanation

  Download the virtual file corresponding to the given unique ID using the HD application.

  To download a file, you need to be able to get the path information of the file that exists on the server, using the properties of the virtual file.

  The virtual file must have a server-side address that can be downloaded to the url property.

  Starting with version 1.4.1.0, you can use two properties: downUrl and url.

      <script>
          function onDX5Created(id) {
              var dx = dx5.get(id);
              // It is a virtual file that can not be downloaded because there is no download path information.
              dx.addVirtualFile({ vindex: "IDX0001", name: "virtual_file.txt", size: 12345 });
              // You can download the file because it has a download path.
              dx.addVirtualFile({ vindex: "IDX0003", name: "bridge_509147.jpg", size: 509147, url: "http://domain/path/common-download.do?key=FID0001", chunkSize: 10 });
          }
          function download(id) {
              var dx = dx5.get(id);
              // Select the second virtual file.
              var itemId = dx.getItemId(1);
              dx.downloadByIdToHD(itemId);
          }
      </script>
      <button type="button" onclick="download('component-id');">Download</button>

  When downloading using the HD application, the file can be forcibly downloaded regardless of whether the content-disposition response header of the server for the download request is attachement or inline.

  When an item with the same name as the download target already exists, the developer can use the callback function (duplicated) to add (override) or ignore this item.

      var dx = dx5.get(id);
      // Select the second virtual file.
      var itemId = dx.getItemId(1);
      dx.downloadByIdToHD(itemId, function (fileName) {
          if (confirm(fileName + " exists already. Do you want to add though?")) {
              // return 0; If you do not have a return value, add an item regardless of the duplicate.
          } else {
              // Ignore.
              return 1;
          }
      });

  The internal processing method according to the return value is as follows.

  - 1: Do not add an item.
  - 2: Add an item, which is automatically added without any callback calls for subsequent duplicate events.
  - 3: Do not add an item, and duplicate events are automatically ignored without callback calls.
  - Other values: Add an item.

- Uses

      component.downloadByIdToHD(id[, duplicated]);

- Parameters

  Name | Type | Explanation
  --- | --- | ---
  id | String | Unique ID of the virtual file to download
  duplicated | Function | [Optional] A callback function that is called when an item with the same name as the download target already exists.

## downloadToHD

- Version 2.0.0.0 or later

- Explanation

  Use the HD application to start downloading multiple files.

  To download a file, you need to be able to get the path information of the file that exists on the server, using the properties of the virtual file.

  The virtual file you want to download must have a server-side address that can be downloaded to the url property.

  Starting with version 1.4.1.0, you can use two properties: downUrl and url.

      <script>
          function onDX5Created(id) {
              var dx = dx5.get(id);
              // It is a virtual file that can not be downloaded because there is no download path information.
              dx.addVirtualFile({ vindex: "IDX0001", name: "virtual_file.txt", size: 12345 });
              // You can download the file because it has a download path.
              dx.addVirtualFile({ vindex: "IDX0003", name: "bridge_509147.jpg", size: 509147, url: "http://domain/path/common-download.do?key=FID0001", chunkSize: 10 });
          }
          function download(id) {
              // Perform to download according to the flag value.
              // AUTO: Download virtual files.
              // SELECTED: Download selected virtual files.
              // CHECKED: Download checked virtual files.
              dx5.get(id).downloadToHD("AUTO");
          }
      </script>
      <button type="button" onclick="download('component-id');">Download</button>

  If you want to process uploads with the "AUTO" parameter value without special code processing, you can use the btnDownloadToHDAuto property value at the time of component creation to bind automatically.

      <button id="btn-download" type="button">Download</button>
      <script>
          dx5.create({
              ...,
              // The file download function is automatically binded.
              btnDownloadToHDAuto: "btn-download"
          });
      </script>

  In addition to the btnDownloadToHDAuto property, you can use btnDownloadToHDSelected, btnDownloadToHDChecked.

  When an item with the same name as the download target already exists, the developer can use the callback function (duplicated) to add (override) or ignore this item.

      var dx = dx5.get(id);
      dx.downloadToHD("AUTO", function (fileName) {
          if (confirm(fileName + " exists already. Do you want to add though?")) {
              // return 0; if there is no return, add an item regardless of duplicate.
          } else {
              // Ignore.
              return 1;
          }
      });

  The internal processing method according to the return value is as follows.

  - 1: Do not add an item.
  - 2: Adds an item, which is automatically added without any callback calls for subsequent duplicate events.
  - 3: Do not add an item, and duplicate events are automatically ignored without callback calls.
  - Other values: Add an item.

  You can not apply a callback function for duplicate processing when you bind to a button automatically.

- Uses

      component.downloadToHD(flag[, duplicated]);

- Parameters

  Name | Type | Explanation
  --- | --- | ---
  flag | String | "AUTO", "SELECTED", "CHECKED"
  duplicated | Function | [Optional] A callback function that is called when an item with the same name as the download target already exists.

## getDownloadPathOfHD

- Version 2.0.0.0 or later

- Explanation

  Returns the download path set in the HD application.

      dx.getDownloadPathOfHD(function (path) {
        console.log(path);
      });

  Most of the methods that will be used when using HD applications perform asynchronous operations internally. Because the task is asynchronous, the thread will not wait until the return value is received, and you must use the callback function to get the result of the request.

- Uses

      component.getDownloadPathOfHD(success);

- Parameters

  Name | Type | Explanation
  --- | --- | ---
  success | Function | It is a callback function that can get the download path value.

## setDownloadPathOfHD

- Version 2.0.0.0 or later

- Explanation

  Set the download path.

      // If you start with a drive string, the absolute path is set.
      dx.setDownloadPathOfHD("c:\\temp");
      // Starting with the <home> string, the subpath relative to user folder is set.
      dx.setDownloadPathOfHD("<home>\\temp");
      // Starting with the <doc> string, the subpath relative to document folder is set.
      dx.setDownloadPathOfHD("<doc>\\temp");
      // Starting with the <desktop> string, the subpath relative to desktop folder is set.
      dx.setDownloadPathOfHD("<desktop>\\temp");
      // Starting with the <downloads> string, the subpath relative to download folder is set. (Supported from version 2.5.0.0)
      dx.setDownloadPathOfHD("<downloads>\\temp");

  If you change the download path and want to know the change immediately, you should use the callback function (success).

      dx.setDownloadPathOfHD("<doc>\\temp", function (path) {
        console.log(path);
      });

  Most of the methods that will be used when using HD applications perform asynchronous operations internally. Asynchronous operation is performed, so the thread does not wait until the operation result is received, and the callback function must be used to receive the result of the request.

- Uses

      component.setDownloadPath(path[, success]);

- Parameters

  Name | Type | Explanation
  --- | --- | ---
  path | String | Download path
  Value | Explanation
  --- | ---
  Start with drive string for Windows | Absolute path
  Start with <home> | Subpath relative to user folder
  Start with <doc> | Subpath relative to document folder
  Start with <desktop> | Subpath relative to desktop folder
  Start with <downloads> | (Supported from version 2.5.0.0) Subpath relative to download folder
  success | Function | [Optional] This is a callback function that can obtain the changed download path value.

## getDownloadStatus

- Version 1.0.0.0 or later

- Explanation

  Returns an object with current download status information.

  When the file is used in the process of downloading, the upload status information can be obtained.

  Using this function, the returned object does not have a different value depending on the time, but has only the copied value of the state at the time of the function call.

  To get a continuous change in the downloading process, you should use a function such as setTimeout.

      function toggleDownloadStatus(isBegin) {
        function downloadProgress() {
          var dx = dx5.get("dext5"),
              out = document.getElementById("downstatus-value"),
              status = dx.getDownloadStatus();
          out.innerHTML = "" +
            "name: " + status.currentName + "<br/>" +
            "speed: " + status.totalSpeed + "(sec)<br/>" +
            "count(completed/total): " + status.completeCount + "/" + status.totalCount + "<br/>" +
            "current rate: " + status.currentRate + " % <br/>" +
            "current size(received/total): " + status.currentReceiveSize + "/" + status.currentSize + " (bytes)<br/>" +
            "current time(past/remained): " + status.currentTime + "/" + status.remainedCurrentTime + "<br/>" +
            "total rate: " + status.totalRate + " % <br/>" +
            "total size(received/total): " + status.totalReceiveSize + "/" + status.totalSize + " (bytes)<br/>" +
            "total time(past/remained): " + status.totalTime + "/" + status.remainedTotalTime + "<br/>" +
            "";
          if (window.isDownloading === true) {
            setTimeout(downloadProgress, 1000);
          }
        }
        window.isDownloading = isBegin;
        if (isBegin) downloadProgress();
      }

- Uses

      status = component.getDownloadStatus();

- Return

  An object with download transfer status values.

  The following is a description of the properties of the object.

  Name | Type | Explanation
  --- | --- | ---
  totalSize | Number | The total size to download
  totalCount | Number | The number of files to download
  totalReceiveSize | Number | The total size of downloaded files
  completeCount | Number | The number of downloaded files
  currentName | String | The name of file being downloaded
  currentSize | Number | The size of the file being downloaded
  currentReceiveSize | Number | The size of the file that is being downloaded
  totalRate | Number | The download rate (percentage)
  totalSpeed | Number | The download speed (bytes/sec)
  totalTime | Number, String | The whole download time (msec)
  currentTime | Number, String | The time (msec) of current file
  remainedTotalTime | Number, String | The remaining time (msec) of all files
  remainedCurrentTime | Number, String | The remaining time (msec) of current file

## openDownloadPathDialogOfHD

- Version 2.0.0.0 or later

- Explanation

  To change the download folder of the HD application, open the folder selection dialog window.

  Because you download multiple files, you need to set the download location before downloading.

  If you do not change the download location, the default location (The DEXTUploadX5 HDM folder in Document folder) is used.

      function changePath(id) {
        var dx = dx5.get(id);
        dx.openDownloadPathDialogOfHD();
      }

  The openDownloadPathDialogOfHD method is used to give the user a chance to select a download path.

  If the download path changes, you can use the callback function to get the modified path.

      function changePath(id) {
        var dx = dx5.get(id);
        dx.openDownloadPathDialogOfHD(function (path) {
          console.log(path);
        });
      }

- Uses

      component.openDownloadPathDialogOfHD([success]);

- Parameters

  Name | Type | Explanation
  --- | --- | ---
  success | Function | [Optional] A callback function that is called when the download path changes.

## getOptionsOfHD

- Version 2.4.0.0 or later

- Explanation

  Returns the option information set in the HD application as a callback function.

      dx.getOptionsOfHD(function (option) {
        // The option parameter is a JSON object that contains option information for the HD application.
      });

  The options object is:

      {
      	// If the file is added, the HD program automatically activates.
      	autoActivation: true,
      	// If the file is added, the HD program automatically starts to download.
      	autoDownload: true,
      	// If a file is deleted, its temporary file will be deleted too.
      	deleteTemporary: false,
      	// If some files are being stopped downloading, they will be started to download when the HD program activates.
      	resumeDownload: true,
      	// Options that is maintained even if the program is closed
      	saveStatus: {
      		// waiting or stopped item
      		waitStop: true,
      		// the item that is been downloading
      		downloading: true,
      		// the item that completed
      		complete: true,
      		// the item that occurred some error
      		error: true
      	}
      }

- Uses

      component.getOptionsOfHD(success);

- Parameters

  Name | Type | Explanation
  --- | --- | ---
  success | Function | Callback function with HD option object as parameter

## setOptionsOfHD

- Version 2.4.0.0 or later

- Explanation

  Sets options for HD applications at once.

      dx.setOptionsOfHD({
      	autoActivation: true,
      	autoDownload: true,
      	deleteTemporary: false,
      	resumeDownload: true,
      	saveStatus: {
      		waitStop: true,
      		downloading: true,
      		complete: true,
      		error: true
      	}
      }, function () { ... });

- Uses

      component.setOptionsOfHD(option[, success]);

- Parameters

  Name | Type | Explanation
  --- | --- | ---
  option | Object | It is an object of type JSON which has option value of application.
      {
      	// If the file is added, the HD program automatically activates.
      	autoActivation: true,
      	// If the file is added, the HD program automatically starts to download.
      	autoDownload: true,
      	// If a file is deleted, its temporary file will be deleted too.
      	deleteTemporary: false,
      	// If some files are being stopped downloading, they will be started to download when the HD program activates.
      	resumeDownload: true,
      	// Options that is maintained even if the program is closed
      	saveStatus: {
      		// waiting or stopped item
      		waitStop: true,
      		// the item that is been downloading
      		downloading: true,
      		// the item that completed
      		complete: true,
      		// the item that occurred some error
      		error: true
      	}
      }
  success | Function | [Option] Callback function with HD option object as parameter

## setAutoActivationOptionOfHD

- Version 2.4.0.0 or later

- Explanation

  Sets the value of automatic activation option.

  Auto activation refers to switching the HD application program to the active state when the file item to be downloaded is added in the HD application program. If this value is true, the hidden application is shown in windowed mode.

      // Change the auto-enable option to true.
      dx.setAutoActivationOptionOfHD(true, function () {
          ...
      });

- Uses

      component.setAutoActivationOptionOfHD(value[, success]);

- Parameters

  Name | Type | Explanation
  --- | --- | ---
  value | Boolean | true, false
  success | Function | [Optional] Callback function that is called when the value changes successfully

## setAutoDownloadOptionOfHD

- Version 2.4.0.0 or later

- Explanation

  Sets the value of the automatic download option.

  The automatic download means downloading the HD application program directly when the file item to be downloaded is added in the HD application program.

      //  Change the auto-download option to true.
      dx.setAutoDownloadOptionOfHD(true, function () {
          ...
      });

- Uses

      component.setAutoDownloadOptionOfHD(value[, success]);

- Parameters

  Name | Type | Explanation
  --- | --- | ---
  value | Boolean | true, false
  success | Function | [Optional] Callback function that is called when the value changes successfully

## setDeleteTemporaryOptionOfHD

- Version 2.4.0.0 or later

- Explanation

  Sets the option to delete temporary files.

  Deleting temporary files means deleting the temporary files when deleting download items from the application. After you start downloading a file, there is always a temporary file if the download is not completed.

      // Change the delete-temporary-files option to true.
      dx.setDeleteTemporaryOptionOfHD(true, function () {
          ...
      });

- Uses

      component.setDeleteTemporaryOptionOfHD(value[, success]);

- Parameters

  Name | Type | Explanation
  --- | --- | ---
  value | Boolean | true, false
  success | Function | [Optional] Callback function that is called when the value changes successfully

## setResumeDownloadOptionOfHD

- Version 2.4.0.0 or later

- Explanation

  Sets the download (again) option value.

  Re-downloading When a program is terminated with the item that has not been completely downloaded and the program is run again, the unfinished target file is automatically downloaded.

      // Change the re-download option to true.
      dx.setResumeDownloadOptionOfHD(true, function () {
          ...
      });

- Uses

      component.setResumeDownloadOptionOfHD(value[, success]);

- Parameters

  Name | Type | Explanation
  --- | --- | ---
  value | Boolean | true, false
  success | Function | [Optional] Callback function that is called when the value changes successfully

## setSaveStatusOptionOfHD

- Version 2.4.0.0 or later

- Explanation

  Sets the retention target option value after termination.

  The end point after termination refers to the item to be maintained when the program is executed again after the end of the program.

      // Change the targets to keep after finishing.
      dx.setSaveStatusOptionOfHD(15, function () {
          ...
      });

  If the downloading value (2) is missing, the item to be automatically downloaded is not retained because there is no item affected by the re-downloading option setting again.

- Uses

      component.setSaveStatusOptionOfHD(value[, success]);

- Parameters

  Name | Type | Explanation
  --- | --- | ---
  value | Number | It is one of 0 to 15, equal to the sum of the objects listed in the table below. That is, if all objects are summed up, it becomes 15.
  Value | Target | Explanation
  --- | --- | ---
  1 | waitStop | Items waiting or stopped
  2 | downloading | Items being downloaded
  4 | complete | Completed download
  8 | error | Item with errors
  success | Function | [Optional] Callback function that is called when the value changes successfully

## stopDownloading

- Version 1.1.0.0 or later

- Explanation

  Stops downloading.

  DEXTUploadX5 does not have a button or GUI element to stop downloading itself.

  Instead, it provides a function that allows you to stop using a script.

      <button type="button" onclick="stop('component-id');">Stop</button>
      <script>
      function stop(id) {
        dx5.get(id).stopDownloading();
      }
      </script>

  You can use the btnStopDownloading property at the time of component creation to bind automatically.

      <button id="btn-stop-downloading" type="button">Stop</button>
      <script>
        dx5.create({
          ...,
          // The download stop function is automatically binded.
          btnStopDownloading: "btn-stop-downloading"
        });
      </script>

  Only multi-file download operations can be aborted. If the target is downloaded using downloadById or the download icon, using the stopDownloading function will not interrupt the operation.

- Uses

      component.stopDownloading();