React Upload

This document describes the minimum flow required to connect DEXTUploadX5 (hereinafter X5) upload in a React environment. It assumes that the Provider setup and component creation from the Getting Started document are already complete.

The explanation uses Node.js and an Express server as the baseline, but the key point is not a specific framework. The important part is matching the upload URL called by X5 and the server response rules.

Basic upload flow

The basic flow for handling uploads in React is as follows.

• Create DEXTUploadX5List or another X5 UI component.
• After the component is created, specify the upload processing URL. (It can also be set later.)
• The user adds files or folders.
• Call upload() to start sending data to the server.
• The server processes the upload and returns an HTTP 200 response.
• The client handles the result in onUploadCompleted or onError.

Set the upload URL on the client

To run an upload, you must first inform the component of the upload URL. It is common to obtain the component object in onCreated and set the URL there.

import { useState } from "react";
import { DX5, DEXTUploadX5List } from "dextuploadx5-react";

export default function UploadPage() {
  const [version, setVersion] = useState("");

  const handleCreated = (id) => {
    const dx = DX5.get(id);
    dx.setUploadURL("/api/upload");
    setVersion(dx.getVersion());
  };

  const handleError = (id, code, msg) => {
    alert(id + " => " + code + "\n" + msg);
  };

  const handleUploadCompleted = (id, result) => {
    console.log(result);
  };

  return (
    <DEXTUploadX5List
      id="dext5"
      style={{ width: "100%", height: "320px" }}
      onCreated={handleCreated}
      onError={handleError}
      onUploadCompleted={handleUploadCompleted}
    />
  );
}

The upload address is the server path that the component will actually call. Since development and production environments may use different address systems, manage it according to your project environment.

Add files and run upload

After the component is created, you can obtain the object with DX5.get(id) to open the file selection dialog or trigger upload directly.

const handleAddFilesClick = () => DX5.get("dext5")?.openFileDialog();
const handleAddFolderClick = () => DX5.get("dext5")?.openFolderDialog();
const handleUploadClick = () => DX5.get("dext5")?.upload("AUTO");

upload("AUTO") starts uploading based on the items currently added to the list. In actual services, it is commonly connected to button events, form submission events, or save buttons.

Simplest example

import { useState } from "react";
import { DX5, DEXTUploadX5List } from "dextuploadx5-react";

export default function UploadPage() {
  const [version, setVersion] = useState("");
  const isLoaded = version !== "";

  const handleAddFilesClick = () => DX5.get("dext5")?.openFileDialog();
  const handleAddFolderClick = () => DX5.get("dext5")?.openFolderDialog();
  const handleUploadClick = () => DX5.get("dext5")?.upload("AUTO");

  const handleCreated = (id) => {
    const dx = DX5.get(id);
    dx.setUploadURL("/api/upload");
    setVersion(dx.getVersion());
  };

  const handleUploadCompleted = (id, result) => {
    alert("Upload completed.");
  };

  const handleError = (id, code, msg) => {
    alert(id + " => " + code + "\n" + msg);
  };

  return (
    <div>
      <DEXTUploadX5List
        id="dext5"
        style={{ width: "100%", height: "320px" }}
        onCreated={handleCreated}
        onError={handleError}
        onUploadCompleted={handleUploadCompleted}
      />
      <p>DEXTUploadX5 Version: {version}</p>
      <button disabled={!isLoaded} onClick={handleAddFilesClick}>Add files</button>
      <button disabled={!isLoaded} onClick={handleAddFolderClick}>Add folder</button>
      <button disabled={!isLoaded} onClick={handleUploadClick}>Upload</button>
    </div>
  );
}

Process on an Express server

In an Express environment, you can use dextuploadx5-express-handler to process X5 upload requests.

# Server project
npm install express dextuploadx5-express-handler

import express from "express";
import { createDEXTUploadX5Handler } from "dextuploadx5-express-handler";

const router = express.Router();

router.post("/api/upload", createDEXTUploadX5Handler({
  // Final location where files will be stored
  uploadDir: process.env.DEXT_UPLOAD_DIR,
  // Location where temporary files will be stored
  tempDir: process.env.DEXT_TEMP_DIR,
  // Handler called when temporary files are ready
  onComplete: async ({ res, files }) => {
    const results = [];

    for (const file of files) {
      // Move or copy the file from tempDir to uploadDir.
      const saved = await file.save();
      results.push(saved.name);
    }

    res.status(200).type("text/plain; charset=utf-8").send(results.join("\n"));
  }
}));

export default router;

As in the example above, you can determine the save location at the final processing stage and return the response data you need directly. In actual services, the response often includes a file identifier, save path, or related post information.

Server response rules

X5 determines whether an upload request completed successfully based on the HTTP status code. If the upload succeeds on the server, it must return a 200 response.

On the other hand, if there is an internal server error, validation failure, or permission issue, the server should return an appropriate 4xx or 5xx status code.

If the server responds with 200 even though an error occurred, X5 may determine that the upload succeeded.