js-fileexplorer

The FileExplorerFSHelper class contains several protected static methods that implement specific file management actions. These are typically invoked via HandleActions().

Common Action Handlers

Complex Operations

Copying Files

Copying is a multi-stage process to allow for UI progress updates:

1. Initialization (ProcessCopyInitAction): Calculates how many files will be overwritten and sets up progress tracking. Returns a copykey.
2. Execution (ProcessCopyAction): Uses the copykey to perform the actual copy. In multiple-request mode, it runs for a few seconds and returns updated progress information.

Uploading Files

ProcessUploadAction handles both the initialization and the actual upload. It uses the currpath to determine if the newly uploaded entry should be included in the response to update the current view.

For operations like copying or uploading, use CreateProgressTracker to provide visual feedback in the status bar.

Workflow:

1. Call CreateProgressTracker(cancelcallback) to get a tracker object.
2. Periodically update the tracker's properties (e.g., totalbytes, itemsdone, faileditems, queueditems).
3. The status bar automatically updates every second via UpdateProgressText().
4. Call RemoveProgressTracker(tracker, finishmessage) when the operation is complete. If it's the last tracker, you can provide a finishmessage to display.

Tracker Properties:

• totalbytes: Total bytes to transfer.
• itemsdone: Number of successfully processed items.
• faileditems: Number of failed items.
• queueditems: Number of items in the queue.
• showbyterate: Boolean to show byte rate after 3 seconds.
• finishmessage: Message to show in the status bar when the tracker is removed.

const tracker = fe.CreateProgressTracker(() => {
  console.log('User cancelled the operation');
});

// Simulate progress
tracker.totalbytes = 1024 * 1024;
tracker.itemsdone = 5;

// Later, remove it
fe.RemoveProgressTracker(tracker, 'Operation Complete');

The TextareaOverlay class displays a positionable textarea with text selection support. It provides full keyboard, mouse, and touch support, making it suitable for in-place text editing within a file explorer interface.

To use it, instantiate it via new window.FileExplorer.TextareaOverlay(parentelem, options).

options = {
	initvalue: 'hello.txt',
	initselstart: 0,
	initselend: 5,

	onposition: function(textelem) {
		textelem.style.left = 50 + 'px';
		extelem.style.top = 40 + 'px';
		extelem.style.width = 50 + 'px';
		extelem.style.height = Math.min(elem.offsetHeight - 2, elem.scrollHeight - 42, textelem.scrollHeight + 2) + 'px';
	},

	ondone: function(val, lastelem) {
		if (lastelem)  lastelem.focus();
		console.log(val);

		this.Destroy();
	},

	oncancel: function(lastelem) {
		if (lastelem)  lastelem.focus();

		this.Destroy();
	},
};

var textoverlaytest = new window.FileExplorer.TextareaOverlay(elem, options);

The FileExplorerFSHelper class is a server-side PHP helper designed to bridge the FileExplorer JavaScript widget with a physical file system. It handles common server-side actions such as directory listings, file uploads, renaming, moving, and deleting files.

Key Requirements

• Permissions: The directories used for files (e.g., /files/) and thumbnails (e.g., /thumbs/) must be writable by the web server user (e.g., www-data).
• Maintenance: It is recommended to run a nightly cron job to clear out .tmp files (failed/abandoned uploads), old files in the recycling bin, and old thumbnail directories.

Implementation Pattern

To handle file explorer actions, use the FileExplorerFSHelper::HandleActions method. This method requires an action name prefix, a base directory path, and a configuration options array.

<?php
require_once "server-side-helpers/file_explorer_fs_helper.php";

$options = array(
    "base_url" => "https://cubiclesoft.com/myapp/files/",
    "protect_depth" => 1,
    "recycle_to" => "Recycle Bin",
    "temp_dir" => "/tmp",
    "dot_folders" => false,
    "allowed_exts" => ".jpg, .jpeg, .png, .gif, .svg, .txt",
    "allow_empty_ext" => true,
    "thumbs_dir" => "/var/www/myapp/thumbs",
    "thumbs_url" => "https://cubiclesoft.com/myapp/thumbs/",
    "thumb_create_url" => "https://cubiclesoft.com/myapp/?action=file_explorer_thumbnail&xsrftoken=qwerasdf",
    "refresh" => true,
    "rename" => true,
    "file_info" => false,
    "load_file" => false,
    "save_file" => false,
    "new_folder" => true,
    "new_file" => ".txt",
    "upload" => true,
    "upload_limit" => 20000000,
    "download" => "user123-" . date("Y-m-d_H-i-s") . ".zip",
    "download_module" => "",
    "download_module_prefix" => "",
    "copy" => true,
    "move" => true,
    "recycle" => true,
    "delete" => true
);

// Handle actions with prefix 'file_explorer_' in the directory '/var/www/myapp/files'
FileExplorerFSHelper::HandleActions("action", "file_explorer_", "/var/www/myapp/files", $options);
?>

You can extend the widget by registering custom tools. A tool is a function that receives the FileExplorer instance.

Steps to build a tool:

1. Define a function that accepts the fe (FileExplorer) instance.
2. Use fe.AddToolbarButton(cssClass, label) to add a button to the UI.
3. Listen for the update_tool event to manage the button's enabled/disabled state based on the current folder context and selection.
4. Listen for the destroy event to clean up event listeners.
5. Register the tool using window.FileExplorer.RegisterTool(groupIndex, ToolClass).

Example: A simple Delete tool implementation

(function() {
	var FileExplorerTool_Delete = function(fe) {
		if (!(this instanceof FileExplorerTool_Delete)) return new FileExplorerTool_Delete(fe);

		if (!fe.hasEventListener('delete') && !fe.settings.tools.delete) return;

		var enabled = false;
		var node = fe.AddToolbarButton('fe_fileexplorer_folder_tool_delete', fe.Translate('Delete (Del)'));

		var ClickHandler = function(e) {
			if (e.isTrusted && enabled) fe.DeleteSelectedItems(!e.shiftKey);
		};

		node.addEventListener('click', ClickHandler);

		var UpdateToolHandler = function(currfolder, attrs) {
			var prevenabled = enabled;
			enabled = (!currfolder.waiting && (!('canmodify' in attrs) || attrs.canmodify) && fe.GetNumSelectedItems());

			if (preenabled !== enabled) {
				if (enabled) node.classList.remove('fe_fileexplorer_disabled');
				else node.classList.add('fe_fileexplorer_disabled');
				fe.ToolStateUpdated();
			}
		};

		fe.addEventListener('update_tool', UpdateToolHandler);

		var DestroyToolHandler = function() {
			node.removeEventListener('click', ClickHandler);
		};

		fe.addEventListener('destroy', DestroyToolHandler);
	};

	window.FileExplorer.RegisterTool(1, FileExplorerTool_Delete);
})();

The file explorer uses a custom event system to manage the lifecycle of file uploads. You can listen for these events to integrate with your own backend or UI.

init_upload

Triggered when an upload process is being initialized. Arguments:

• startuploadcallback: A function (process) => void where process is true to proceed or a string error message to fail.
• fileinfo: The object containing file metadata and progress.
• uploadqueuestarted: Timestamp of when the first upload in the queue started.

upload_done

Triggered when a file upload is successfully completed. Arguments:

• finalizecallback: A function (success, entry) => void used to finalize the entry in the UI.
• fileinfo: The object containing the file metadata.

upload_error

Triggered when an upload fails. Arguments:

• fileinfo: The object containing the file metadata.
• error: The error object/event.