DEXTUploadX5 React

React wrapper package for DEXTUploadX5 multipart and resumable uploads.

This package loads the DEXTUploadX5 browser script through a React provider and exposes ready-to-use React components for the list, grid, tile, and single UI types.

Features

• Provides a DEXTUploadX5Provider that loads dextuploadx5.js
• Exposes React components for list, grid, tile, and single UI modes
• Includes a DX5 helper for accessing the underlying global DX5 object
• Supports React refs for waiting until a DX5 instance is ready
• Includes TypeScript declarations for TypeScript projects
• Keeps react and react-dom as peer dependencies

Requirements

• React 18 or later
• ReactDOM 18 or later
• A licensed DEXTUploadX5 product install available to the browser
• [email protected] requires DEXTUploadX5 4.4.0.0 (beta) or later

Installation

npm install dextuploadx5-react react react-dom

After installation, you must manually copy node_modules/dextuploadx5-react/dist/dx5 to the directory served by your productPath.

For example, if productPath="/dx5/", your application must serve the copied files from /dx5/..., including /dx5/dextuploadx5.js.

If this manual copying process is cumbersome in a Webpack environment, consider using dextuploadx5-react-webpack to help copy and serve the DX5 static files. That package is currently being prepared for npm packaging.

Quick Start

import {
    DEXTUploadX5Provider,
    DEXTUploadX5List
} from "dextuploadx5-react";

export default function App() {
    return (
        <DEXTUploadX5Provider
            authKey={process.env.DX5_AUTHKEY}
            productPath="/dx5/"
        >
			<DEXTUploadX5List
                id="upload1"
				style={{ width: "500px", height: "300px" }}
				onError={(id, code, msg) => {
					console.log(id + " ==> " + code + "\n" + msg);
				}}
                onCreated={(id) => {
                    console.log("DX5 created:", id);
                }}
            />
        </DEXTUploadX5Provider>
    );
}

How It Works

1. DEXTUploadX5Provider writes the DEXTUploadX5 runtime configuration to the browser global scope.
2. The provider loads dextuploadx5.js from productPath.
3. After the global dx5 object is ready, child React components are rendered.
4. Each UI component creates and destroys its own DX5 instance by id.

Components

DEXTUploadX5Provider

Loads the DEXTUploadX5 script before rendering its children.

<DEXTUploadX5Provider
    authKey="..."
    productPath="/dx5/"
>
    {children}
</DEXTUploadX5Provider>

Props

authKey: string

DEXTUploadX5 authentication key.

Required.

productPath?: string

Base path where the DEXTUploadX5 product files are served.

• Default: "/dx5/"
• dextuploadx5.js is loaded from productPath + "dextuploadx5.js"
• You must copy node_modules/dextuploadx5-react/dist/dx5 to the directory served at this path before runtime

fallback?: React.ReactNode

Rendered while the DEXTUploadX5 script is still loading.

children?: React.ReactNode

Rendered after the script is loaded and initialized.

UI Components

The package exports the following UI components:

• DEXTUploadX5List
• DEXTUploadX5Grid
• DEXTUploadX5Tile
• DEXTUploadX5Single

All of them share the same base props and only differ by the fixed DX5 type.

import { DEXTUploadX5Grid } from "dextuploadx5-react";

<DEXTUploadX5Grid
    id="grid1"
    columns={[
        { key: "grade", display: "Grade", width: 40, position: 2 },
        { key: "movie", display: "Movie", width: 80, position: 3, itemAlign: "left", valueAlign: "right" },
        { key: "action", display: "Action", width: 70, position: 4 }
    ]}
/>;

Common Props

id?: string

DX5 instance id.

• Default: "dext5"

lang?: string

DX5 language option.

• Default: "auto"

waitingTime?: number

DX5 load waiting time.

• Default: 10000

progressType?: string

DX5 progress type value.

• Default: "0"

className?: string

style?: React.CSSProperties

hidden?: boolean

Container display props for the rendered wrapper element.

columns?: any[]

Used by DEXTUploadX5Grid to create DX5 grid columns after the component is created.

Event Props

Supported event props include:

• onError
• onCreated
• onBeforeItemsAdd
• onItemAdding
• onItemsAdded
• onBeforeItemsDelete
• onItemDeleting
• onItemsDeleted
• onItemSelect
• onItemCheck
• onItemDoubleClick
• onUploadBegin
• onUploadItemStart
• onUploadItemEnd
• onUploadStopped
• onUploadCompleted
• onDownloadBegin
• onDownloadItemStart
• onDownloadItemEnd
• onDownloadStopped
• onDownloadCompleted
• onPreview
• onColumnDataBinding
• onColumnDataDisplaying
• onCompressWaitingBegin
• onCompressWaitingCompleted
• onCompressWaitingStopped
• onDragAndDrop

Typical onCreated Usage

Most applications can treat onCreated as the primary point where the DX5 instance becomes available.

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

function Example() {
    const [version, setVersion] = useState("");

    const handleCreated = (id) => {
        const dx = DX5.get(id);
        setVersion(dx.getVersion());
    };

    return (
        <>
            <DEXTUploadX5List
                id="upload2"
                onCreated={handleCreated}
            />
            <div>DEXTUploadX5 Version: {version}</div>
        </>
    );
}

Simple File Upload Example

The following example shows a minimal upload flow. When the component is created, onCreated marks the DX5 instance as ready. After that, the user can open the file dialog, and the selected files are uploaded by calling setUploadURL() and upload("AUTO").

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

function SimpleUpload() {
    const [ready, setReady] = useState(false);

    const handleCreated = (id) => {
        const dx = DX5.get(id);
        setReady(!!dx);
    };

    const handleAddFilesClick = () => {
        DX5.get("dext5")?.openFileDialog();
    };

    const handleUploadClick = () => {
        const dx = DX5.get("dext5");
        if (!dx || !dx.hasUploadableItems()) return;

        dx.setUploadURL(DX5.canonicalize("/api/upload"));
        dx.upload("AUTO");
    };

    return (
        <>
            <DEXTUploadX5List
                id="dext5"
                style={{ width: "500px", height: "300px" }}
                onCreated={handleCreated}
                onError={(id, code, msg) => {
                    console.error(id, code, msg);
                }}
                onUploadCompleted={(id, result) => {
                    console.log("Upload completed:", id, result);
                }}
            />
            <button disabled={!ready} onClick={handleAddFilesClick}>
                Add files
            </button>
            <button disabled={!ready} onClick={handleUploadClick}>
                Upload
            </button>
        </>
    );
}

DX5 Helper

The exported DX5 object wraps the global dx5 runtime.

Available methods:

• DX5.get(id)
• DX5.create(options)
• DX5.delete(id)
• DX5.canonicalize(path)

Notes

• This package is a React wrapper only. The actual DEXTUploadX5 product files must be hosted separately.
• DEXTUploadX5 itself is not distributed through npm, so its required version is documented here instead of package.json.
• [email protected] supports DEXTUploadX5 4.4.0.0 (beta) or later.
• After installing the package, manually copy node_modules/dextuploadx5-react/dist/dx5 to the location served by productPath.
• If that setup is inconvenient in a Webpack project, dextuploadx5-react-webpack can be used as a helper package to automate DX5 static resource handling. It is currently being prepared for npm packaging.
• DEXTUploadX5Provider must be mounted before rendering DX5-dependent components.
• The package is intended for browser environments and does not run the DX5 runtime on the server.

History

Compatibility

| dextuploadx5-react | Minimum DEXTUploadX5 version | | --- | --- | | 0.0.1 | 4.4.0.0 (beta) |

0.0.1

• Initial package release

License

This package is free to use, including commercial use. Modification for internal use is allowed. Redistribution of modified versions is prohibited. DEXTUploadX5 itself is a commercial product and is not free to use under the same terms as DEXTUploadX5 React.

See the LICENSE file for full terms.