450 |
451 |
452 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | Folder and File Explorer
2 | ========================
3 |
4 | A zero dependencies, customizable, pure Javascript widget for navigating, managing (move, copy, delete), uploading, and downloading files and folders or other hierarchical object structures on any modern web browser. Choose from a MIT or LGPL license.
5 |
6 | [](https://cubiclesoft.com/demos/js-fileexplorer/demo.html)
7 |
8 | [Live Demo](https://cubiclesoft.com/demos/js-fileexplorer/demo.html) | [The making of this widget](https://cubicspot.blogspot.com/2020/06/building-complex-javascript-widgets.html)
9 |
10 | Experience a clean, elegant presentation of folders and files in a mobile-friendly layout that looks and feels great on all devices. CubicleSoft File Explorer is easily connected to any web application that needs to manage hierarchical objects (folders and files, database records, or even JSON, XML, etc).
11 |
12 | Check out a working product that uses this widget: [PHP File Manager and Editor](https://github.com/cubiclesoft/php-filemanager)
13 |
14 | [](https://cubiclesoft.com/donate/) [](https://cubiclesoft.com/product-support/github/)
15 |
16 | If you use this project, don't forget to donate to support its development!
17 |
18 | Features
19 | --------
20 |
21 | * Clean, elegant presentation of folders and files in a mobile-friendly layout.
22 | * Zero dependencies. No other libraries required!
23 | * Can handle displaying thousands of files in a folder.
24 | * Full keyboard, mouse, and touch support. Secure from fake/simulated keyboard, mouse, and touch events.
25 | * Keyboard shortcuts. Lots of keyboard shortcuts.
26 | * Folder history tracking and navigation. Optionally navigate through folder history in the widget using the back and forward buttons on the mouse.
27 | * Customizable toolbar.
28 | * Create new files and folders.
29 | * Easily rename and delete/recycle files and folders.
30 | * Double-click/tap or press Enter to open items in your application-defined manner.
31 | * Powerful file and folder selection tools. Selection boxes with variable-speed scrolling on desktop browsers.
32 | * Multi-select checkboxes on touch devices. Can be enabled for non-touch devices too.
33 | * Cut/Copy/Paste items using: Keyboard shortcuts, mouse right-click menu, or toolbar buttons.
34 | * Cut/Copy/Paste items between compatible widget instances...even across different web browsers!
35 | * Drag-and-drop support between compatible widget instances.
36 | * Drag-and-drop bulk uploading support directly from the OS for both files and folders.
37 | * Drag-and-drop direct URL downloading support (Chromium only).
38 | * Chunked file upload support.
39 | * Download files and folders via a toolbar button.
40 | * Items can be displayed as a thumbnail image, including folders. Thumbnails are intelligently bulk loaded in the background using a custom lazy loader.
41 | * Items can have detailed tooltips, overlays, size information, etc.
42 | * Automatic item sorting (can be disabled per folder).
43 | * Provides useful feedback on the status bar - items in a folder, number selected, active upload information, etc.
44 | * Can easily be connected to a WebSocket backend (e.g. [Data Relay Center](https://github.com/cubiclesoft/php-drc)) to efficiently watch for folder updates.
45 | * Event-handler style callbacks. Way more callbacks than you'll probably need.
46 | * Plenty of automation possibilities too via the extensive [FileExplorer API](docs/file_explorer.md).
47 | * Multilingual support.
48 | * And much, much more.
49 |
50 | Getting Started
51 | ---------------
52 |
53 | To use this widget, you should be quite comfortable with writing both client-side Javascript and secure server-side code. Client-side Javascript is never a proper defense mechanism for proper server-side security and assume someone will try to break into your server by sending bad folder and file paths to the server to read/write data they shouldn't have access to.
54 |
55 | Also note that this widget only provides the client-side (web browser) portion of the equation. You will need to supply your own server-side handlers (e.g. PHP) but that's the comparatively easy part.
56 |
57 | With those caveats out of the way, download/clone this repo, put the `file-explorer` directory on a server, and add these lines to your page to load the widget core:
58 |
59 | ```html
60 |
61 |
62 | ```
63 |
64 | Next, create an instance of the FileExplorer class inside a closure for security reasons:
65 |
66 | ```html
67 |
68 |
69 |
125 | ```
126 |
127 | That code will produce a less-than-exciting 'Loading...' view and also doesn't show the toolbar since there are no event listeners for the tools (yet):
128 |
129 | 
130 |
131 | The next step is to connect the widget to the backend server. There are many ways to do that. The widget instance itself exports the [PrepareXHR class](docs/prepare_xhr.md) to make AJAX calls. Or you could use a framework specific mechanism of your choice (jQuery, Vue, whatever) or talk to a WebSocket server or whatever makes sense for your application. The entries returned from the server should ideally be compatible with [Folder.SetEntries](docs/folder.md#foldersetentriesnewentries).
132 |
133 | If using PHP on a server and this widget will reflect a physical file system on the same server, there is the useful [FileExplorerFSHelper PHP class](docs/file_explorer_fs_helper.md) that can simplify connecting the widget to the backend server:
134 |
135 | ```php
136 | "https://yoursite.com/yourapp/files/",
141 | "protect_depth" => 1, // Protects base_dir + additional directory depth.
142 | "recycle_to" => "Recycle Bin",
143 | "temp_dir" => "/tmp",
144 | "dot_folders" => false, // Set to true to allow things like: .git, .svn, .DS_Store
145 | "allowed_exts" => ".jpg, .jpeg, .png, .gif, .svg, .txt",
146 | "allow_empty_ext" => true,
147 | "thumbs_dir" => "/var/www/yourapp/thumbs",
148 | "thumbs_url" => "https://yoursite.com/yourapp/thumbs/",
149 | "thumb_create_url" => "https://yoursite.com/yourapp/?action=file_explorer_thumbnail&xsrftoken=qwerasdf",
150 | "refresh" => true,
151 | "rename" => true,
152 | "file_info" => false,
153 | "load_file" => false,
154 | "save_file" => false,
155 | "new_folder" => true,
156 | "new_file" => ".txt",
157 | "upload" => true,
158 | "upload_limit" => 20000000, // -1 for unlimited or an integer
159 | "download" => true,
160 | "copy" => true,
161 | "move" => true,
162 | "delete" => true
163 | );
164 |
165 | FileExplorerFSHelper::HandleActions("action", "file_explorer_", "/var/www/yourapp/files", $options);
166 | ```
167 |
168 | Once entries are populating in the widget, various bits of navigation functionality should start working. The widget is starting to come to life but is mostly read only. Let's add an `onrename` handler so users can press F2 or click on the text of a selected item to rename the item:
169 |
170 | ```js
171 | // Note: 'entry' is a copy of the original, so it is okay to modify any aspect of it, including 'id'.
172 | onrename: function(renamed, folder, entry, newname) {
173 | var xhr = new this.PrepareXHR({
174 | url: '/yourapp/',
175 | params: {
176 | action: 'file_explorer_rename',
177 | path: JSON.stringify(folder.GetPathIDs()),
178 | id: entry.id,
179 | newname: newname,
180 | xsrftoken: 'asdfasdf'
181 | },
182 | onsuccess: function(e) {
183 | var data = JSON.parse(e.target.response);
184 | console.log(data);
185 |
186 | // Updating the existing entry or passing in a completely new entry to the renamed() callback are okay.
187 | if (data.success) renamed(data.entry);
188 | else renamed(data.error);
189 | },
190 | onerror: function(e) {
191 | console.log(e);
192 | renamed('Server/network error.');
193 | }
194 | });
195 |
196 | xhr.Send();
197 | },
198 | ```
199 |
200 | A lot is going on here. When the user finishes renaming an item, `onrename` is called, which hands the request off to an AJAX request to the server to handle. During this operation, the textarea is marked read only and the busy state on the folder is enabled. When the AJAX operation completes, it must call `renamed()` to let the widget know that the operation has been completed and indicate success by passing in a compatible entry object - either a modified `entry` or a new entry from the server. On failure, a boolean of false or a string that is passed to renamed() to be used as part of the error message displayed to the user.
201 |
202 | The above examples and documentation should be enough to get the ball rolling. Most event handler callbacks utilize a similar approach: Receive an event callback, make a server call or two, and finally call the completion callback function with the result of the operation. Callbacks always have the 'this' context as the FileExplorer instance.
203 |
204 | See a complete, functional implementation of all of the important callbacks in the [FileExplorerFSHelper PHP class](docs/file_explorer_fs_helper.md) documentation. It's an excellent starting point when utilizing the FileExplorerFSHelper class.
205 |
206 | FileExplorer Options
207 | --------------------
208 |
209 | The `options` object passed to the FileExplorer class accepts the following options:
210 |
211 | * group - An optional string containing a group name. When specified, this must be a unique string that indicates a compatible widget backend to allow cross-widget drag-and-drop and cut/copy/paste to function properly. When not specified, the instance receives a group name unique to the instance that disables the aforementioned cross-widget features.
212 | * alwaysfocused - A boolean that indicates whether or not the widget's appearance never loses focus (Default is false). This only affects visual appearance and does not stop onfocus/onblur event callbacks from firing.
213 | * capturebrowser - A boolean that indicates whether or not to capture the hardware back and forward mouse buttons when the mouse is hovering over the widget (Default is false). Read the 'Known Limitations' section before enabling this feature.
214 | * messagetimeout - An integer containing the number of milliseconds to show short-lived messages in the status bar (Default is 2000).
215 | * displayunits - A string containing one of 'iec_windows', 'iec_formal', or 'si' to specify what units to use when displaying file sizes to the user (Default is 'iec_windows').
216 | * adjustprecision - A boolean indicating whether or not to adjust the final precision when displaying file sizes to the user (Default is true).
217 | * initpath - An optional array of arrays containing the initial path segments to set. Each path segment is an array consisting of `[id, value, attrs]`. This path is passed to [FileExplorer.SetPath](docs/file_explorer.md#fileexplorer-setpath).
218 | * onfocus(e) - An optional callback function that is called when the widget or one of its components receives focus.
219 | * e - The browser event object that triggered the event.
220 | * onblur(e) - An optional callback function that is called when the widget loses focus. This callback can be used to hide or `Destroy()` the widget instance if it is used in a popup overlay. Note that `onblur` will not fire if the window itself loses focus - only if the widget loses focus to another element on the page.
221 | * e - The browser event object that triggered the event.
222 | * onrefresh(folder, required) - An optional callback function that is called when a folder refresh should happen.
223 | * folder - A Folder instance to refresh.
224 | * refresh - A boolean indicating that the refresh is required for the widget to function properly.
225 | * onselchanged(folder, selecteditemsmap, numselecteditems) - An optional callback function that is called whenever the user changes the item selections. Rarely used.
226 | * folder - The current Folder instance.
227 | * selecteditemsmap - The internal selecteditemsmap object. Do not modify.
228 | * numselecteditems - An integer containing the number of selected items in the selecteditemsmap.
229 | * onrename(renamed, folder, entry, newname) - An optional callback function that is called when the user renames an item.
230 | * renamed(entry) - A callback function to call upon completion of renaming or on failure.
231 | * folder - The Folder in which the entry to rename is in.
232 | * entry - The entry to rename.
233 | * newname - A string containing the name that was entered by the user.
234 | * onopenfile(folder, entry) - An optional callback function that is called when the user double-clicks/taps on an item.
235 | * folder - The Folder that the entry to open is in.
236 | * entry - The entry to open.
237 | * tools - An optional object containing key-value pairs where the value is a boolean that indicates whether or not to show the tool and the keys are: new_folder, new_file, upload, download, copy, paste, cut, delete, item_checkboxes. Most toolbar tools show up automatically when an onhandler is defined and override any "don't show" setting. The only tool that doesn't show as a result of a handler being defined is 'item_checkboxes'.
238 | * onnewfolder(created, folder) - An optional callback function that is called when the user clicks the New Folder icon or presses Ctrl + Ins.
239 | * created(success) - A callback function to call upon completion of creating a new folder or on failure.
240 | * folder - The Folder in which to create a new folder.
241 | * onnewfile(created, folder) - An optional callback function that is called when the user clicks the New File icon or presses Ins.
242 | * created(success) - A callback function to call upon completion of creating a new file or on failure.
243 | * folder - The Folder in which to create a new file.
244 | * oninitupload(startupload, fileinfo, queuestarted) - An optional callback function that is called when the user clicks the Upload icon or presses Ctrl + U.
245 | * startupload(fileinfo, process) - A callback function to call upon completion of initializing the upload or on failure. The 'process' option can be used to tell the callback to process the upload itself or skip it if it was handled in the callback (e.g. creating an empty directory). When 'process' is a string, it is treated as an error message to display to the user.
246 | * fileinfo - The file information object of the file to initialize for uploading.
247 | * queuestarted - An integer containing a UNIX timestamp of when the current upload queue was started. Can be useful to pass to a server that can use the value to copy files that are going to be overwritten to a recycling bin folder before the overwrite happens.
248 | * onfinishedupload(finalize, fileinfo) - An optional callback function that is called when the upload finishes successfully. Can be used to finalize an uploaded file on a server (e.g. move from a temporary directory to its final location).
249 | * finalize(success, entry) - A callback function to call upon completion of finalizing the upload or on failure. The 'entry' parameter is an optional Folder entry to set in the current folder.
250 | * fileinfo - The file information object of the file upload to finalize.
251 | * onuploaderror(fileinfo, e) - An optional callback function that is called when the upload fails. Can be used to remove an associated temporary file that was created during initialization.
252 | * fileinfo - The file information object of the file upload that had an error.
253 | * e - An optional error event object (not all failure conditions include this parameter).
254 | * concurrentuploads - An integer containing the maximum number of concurrent uploads to perform simultaneously (Default is 4).
255 | * oninitdownload(startdownload, folder, ids, entries) - An optional callback function that is called when the user clicks the Download icon. Since browsers don't do well with downloading a lot of individual files, it is recommended that folders and files be sent from the server in a single, compressed file format (e.g. ZIP).
256 | * startdownload(xhroptions) - A callback function to call upon completion of preparing the download or on failure. When an object is passed for xhroptions, it must be a set of options compatible with [PrepareXHR](docs/prepare_xhr.md).
257 | * folder - The Folder in which the ids are located.
258 | * ids - An array containing the selected entry IDs to download.
259 | * entries - An array containing the selected entries to download.
260 | * ondownloadstarted(options) - An optional callback function that is called when the download has started.
261 | * options - The xhroptions object passed to startdownload().
262 | * ondownloaderror(options) - An optional callback function to that is called if the download failed to start.
263 | * options - The xhroptions object passed to startdownload().
264 | * ondownloadurl(result, folder, ids, name) - An optional synchronous callback function that is called when a user starts a drag operation or cuts/copies one or more selected items. This applies a DownloadURL MIME type to the content. This allows for dragging/pasting folders and files out of the browser and onto the desktop. Currently only supported in Chromium browsers and may not use asynchronous methods like AJAX to calculate the URL.
265 | * result - An object that should have 'name' and 'url' strings assigned to it.
266 | * folder - The Folder in which the ids are located.
267 | * ids - An array containing the selected entry IDs to download.
268 | * entry - The first folder entry in the associated IDs list. Can be used to set the 'name' of the file.
269 | * oncopy(copied, srcpath, srcids, destfolder) - An optional callback function that is called when the user copies folders/files from one folder to another.
270 | * copied(success, entries) - A callback function to call upon completion of copying the folders and files or on failure. The 'entries' should contain the successfully copied entries to add regardless of success/failure.
271 | * srcpath - An array of arrays representing the source path of the IDs.
272 | * srcids - An array of entry IDs in the source path to copy.
273 | * destfolder - A Folder to which the entries are to be copied. Note that the destination folder may be the same as the source, in which case the server may choose to copy the files to new files with different names or reject the request.
274 | * onmove(moved, srcpath, srcids, destfolder) - An optional callback function that is called when the user moves folders/files from one folder to another.
275 | * moved(success, entries) - A callback function to call upon completion of moving the folders and files or on failure. The 'entries' should contain the successfully moved entries to add regardless of success/failure.
276 | * srcpath - An array of arrays representing the source path of the IDs.
277 | * srcids - An array of entry IDs in the source path to move.
278 | * destfolder - A Folder to which the entries are to be moved. Note that the destination folder may be the same as the source, in which case the server should reject the request.
279 | * ondelete(deleted, folder, ids, entries, recycle) - An optional callback function that is called when the user deletes folders/files.
280 | * deleted(success) - A callback function to call upon completion of the deletion operation.
281 | * folder - The Folder in which the ids/entries are located.
282 | * ids - An array containing the selected entry IDs to delete.
283 | * entries - An array containing the selected entries to delete.
284 | * recycle - A boolean hinting at whether to send items to a recycling bin (Delete) or permanently delete them (Shift + Delete). The server is free to ignore this parameter and do whatever makes the most sense.
285 | * langmap - An object containing translation strings. Support exists for most of the user interface (Default is an empty object).
286 |
287 | The [Live Demo](https://cubiclesoft.com/demos/js-fileexplorer/demo.html) utilizes nearly all of the available callbacks. The [Live Demo source code](demo.html) was designed so as keep this documentation to a minimum and to provide decent example usage without incurring AJAX calls.
288 |
289 | Making Custom Tools
290 | -------------------
291 |
292 | While most of the widget is not really intended to be modified externally, the toolbar is designed to be extensible. Building a new tool involves:
293 |
294 | * An icon to display and an associated CSS class.
295 | * Some Javascript that handles clicks and possibly a keyboard shortcut.
296 | * Being efficient. The toolbar buttons are updated regularly via toolbar events that fire from FileExplorer.
297 | * Cleaning up when the 'destroy' event fires.
298 | * Registering the new tool with the registered tools.
299 |
300 | The simplest approach to developing a new tool is to look at the existing tools. However, the Delete tool is fairly simple and short:
301 |
302 | ```js
303 | (function() {
304 | // Tools receive the FileExplorer instance as the only option passed to the tool.
305 | var FileExplorerTool_Delete = function(fe) {
306 | if (!(this instanceof FileExplorerTool_Delete)) return new FileExplorerTool_Delete(fe);
307 |
308 | // Do not create the tool if deleting is disabled.
309 | if (!fe.hasEventListener('delete') && !fe.settings.tools.delete) return;
310 |
311 | var enabled = false;
312 |
313 | // Register a toolbar button with File Explorer.
314 | var node = fe.AddToolbarButton('fe_fileexplorer_folder_tool_delete', fe.Translate('Delete (Del)'));
315 |
316 | // Handle clicks.
317 | var ClickHandler = function(e) {
318 | if (e.isTrusted && enabled) fe.DeleteSelectedItems(!e.shiftKey);
319 | };
320 |
321 | node.addEventListener('click', ClickHandler);
322 |
323 | // Efficiently handle toolbar updates - only adding/removing the disabled class if it is different from its previous state.
324 | var UpdateToolHandler = function(currfolder, attrs) {
325 | var prevenabled = enabled;
326 |
327 | enabled = (!currfolder.waiting && (!('canmodify' in attrs) || attrs.canmodify) && fe.GetNumSelectedItems());
328 |
329 | if (prevenabled !== enabled)
330 | {
331 | if (enabled) node.classList.remove('fe_fileexplorer_disabled');
332 | else node.classList.add('fe_fileexplorer_disabled');
333 |
334 | // Notify File Explorer that the state was updated.
335 | // When the event callback finishes, it will know that there is some work to do.
336 | fe.ToolStateUpdated();
337 | }
338 | };
339 |
340 | fe.addEventListener('update_tool', UpdateToolHandler);
341 |
342 | // Cleanly handle the destroy event.
343 | var DestroyToolHandler = function() {
344 | node.removeEventListener('click', ClickHandler);
345 | };
346 |
347 | fe.addEventListener('destroy', DestroyToolHandler);
348 | };
349 |
350 | // Register the tool in the second group of tools (0-based).
351 | window.FileExplorer.RegisterTool(1, FileExplorerTool_Delete);
352 | })();
353 | ```
354 |
355 | Some additional comments were added to the code above to aid in understanding what is going on. There are more complex tools to look at in the FileExplorer source code (e.g. FileExplorerTool_Download). The Class Documentation section below will be quite useful when developing a custom tool.
356 |
357 | For custom tools, you might want to prefix custom settings object keys with something like a company abbreviation so the likelihood of a naming conflict is reduced.
358 |
359 | One good idea for a custom tool might be a HTML embed tool. If a user selects a single item and clicks the embed tool, the clipboard receives some HTML code that can be pasted into another website to embed the item into a post.
360 |
361 | Class Documentation
362 | -------------------
363 |
364 | * [FileExplorer class](docs/file_explorer.md) - The core FileExplorer class + tools. Does most of the heavy-lifting. Exported as `window.FileExplorer`.
365 | * [DebounceAttributes class](docs/debounce_attributes.md) - Debounces/throttles attribute changes. More efficient than most debounce functions that rely on events.
366 | * [PrepareXHR class](docs/prepare_xhr.md) - A basic and convenient wrapper around a XMLHttpRequest (XHR) object.
367 | * [ImageLoader class](docs/image_loader.md) - A multi-queue delayed image loader that only loads images when it is told to. Also exported as `window.FileExplorer.ImageLoader` for reusability purposes.
368 | * [PopupMenu class](docs/popup_menu.md) - Displays a popup menu of items. Used for Recent Locations and path segment expansion. Full keyboard, mouse, and touch support. Also exported as `window.FileExplorer.PopupMenu` for reusability purposes.
369 | * [TextareaOverlay class](docs/textarea_overlay.md) - Displays a positionable textarea with optional text with text selection. Full keyboard, mouse, and touch support. Also exported as `window.FileExplorer.TextareaOverlay` for reusability purposes.
370 | * [Folder class](docs/folder.md) - Tracks the contents of a single folder in the mapped folders of the FileExplorer class. The Folder class cannot be instantiated except from within the FileExplorer but instances of this class can be accessed primarily via callbacks from FileExplorer.
371 | * [FileExplorerFSHelper class](docs/file_explorer_fs_helper.md) - PHP server-side helper class to simplify interacting with server-local, physical file systems.
372 |
373 | Known Limitations
374 | -----------------
375 |
376 | CubicleSoft File Explorer is a complex piece of software written in Javascript. As with every complex piece of software written in Javascript, there are going to be problems with certain combinations of OS + device + web browser for a garden variety of reasons. Web browsers have lots of bugs and the specifications that browsers follow don't cover all edge cases, which leaves things open to interpretation for the browser vendor. What follows are known limitations of the widget due to conditions beyond nearly everyone's direct control and most of the listed problems have reasonable workarounds. Please do not open issues on the issue tracker for these items unless you actually solve them.
377 |
378 | * Some devices and web browsers lack HTML 5 drag-and-drop support, notably any browser on iOS as the iOS webview implementation lacks support. It is NOT recommended to use a [polyfill](https://github.com/Bernardo-Castilho/dragdroptouch) with this widget to support HTML 5 drag-and-drop. There are several situations where a drag-and-drop polyfill will probably break certain touch-based features of this widget and/or break native drag-and-drop elsewhere. Instead, use the cut/copy/paste feature on devices/browsers where HTML 5 drag-and-drop is not natively supported.
379 |
380 | * The right-click context menu for cut/copy/paste can cause the main UI area to get stuck on some platforms until a click or keyboard event is registered, notably Mac OSX. There is a near-invisible textarea overlay that captures right-click events for cut/copy/paste operations but it doesn't always go away until a second mousedown/keyup event is registered. This happens because there is no such thing as an 'exitcontextmenu' event to detect that the context menu has closed and all known methods for detection are hacks. The solution is to either put up with the extra click or just not use right-click and use keyboard shortcuts or the toolbar buttons instead.
381 |
382 | * There is extremely limited "file paste" support from OS file systems into the widget. Raw image data that is stored on the clipboard (e.g. right-click on an image in a website then click Copy) can be pasted into the widget and it will be uploaded but files from the OS itself do not drop. Here's a [Chromium bug that's been open since 2013](https://bugs.chromium.org/p/chromium/issues/detail?id=316472) about the issue and has received almost no attention other than duplicates being merged into it. Dragging and dropping files from the OS into the browser is the most feature-complete file transfer mechanism available to date.
383 |
384 | * The iframe-based downloading method requires initiating a second request to the server for the same content. This kind of hack has to be done because there is no web browser event available to know that page navigation was cancelled when the download starts. The XHR request terminates as soon as it receives its first 'progress' event, usually in the first few KB and it assumes the iframe form submission equivalent, which started before the XHR request, completed in a similar amount of time and has started downloading the file. It is recommended that download requests that take more than a few seconds to process on the server (e.g. generating a compressed file) be run separately and the generated file stored on the server somewhere prior to calling `startdownload(fileinfo)` in the client so that both the form and XHR requests return quickly, the download begins, and the iframe is removed all within a few seconds.
385 |
386 | * The hardware back/forward mouse button capture logic modifies browser history. There is no way to capture the hardware mouse buttons except to modify browser history so that there are three distinct history push states (back, current, forward) while hovering over the widget and using mouseenter/mouseleave to enable/disable the back/forward button capture. There are a couple of extremely difficult to track down bugs as well. The first bug is that the `window.history.scrollRestoration` of the real page sometimes gets stuck on `manual` instead of being restored to `auto`, which causes page reload jumping issues and also causes Edge to jump during scrolling. That bug only seems to show up if lots of reloads happen. The second bug is the page the widget is on occasionally completely messes up the parent pushState and the widget decides it needs to back up too far in the history stack and ends up leaving the page altogether. I have no idea what causes either bug to occur. Also, during development of this specific feature, Firefox literally crashed a half-dozen times. Since browser history is modified, which may conflict with other software, the hardware back/forward mouse button capture feature is disabled by default. It is a pretty cool feature when it works.
387 |
--------------------------------------------------------------------------------
/docs/file_explorer.md:
--------------------------------------------------------------------------------
1 | FileExplorer Class
2 | ==================
3 |
4 | The FileExplorer class is exported to the global `window` object and is core widget for File Explorer. `window.FileExplorer` also exports several internal classes and functions that can be useful for building custom features.
5 |
6 | See the main documentation in thie repository for example, common usage and use-cases for the class. This documentation focuses on the public functions and information available for each instance of the FileExplorer class.
7 |
8 | FileExplorer(parentelem, options)
9 | ---------------------------------
10 |
11 | Category: Constructor
12 |
13 | Parameters:
14 |
15 | * parentelem - A DOM node to append the root of the File Explorer widget to.
16 | * options - An object containing options to use to construct the widget.
17 |
18 | Returns: A Javascript function hierarchy.
19 |
20 | This function sets up a new File Explorer widget instance. The 'new' keyword is required in order to use it correctly. See the repository README to see a list of all options that can be passed in.
21 |
22 | FileExplorer.settings
23 | ---------------------
24 |
25 | Category: Settings
26 |
27 | The `settings` object contains the settings for the instance. Changing the settings after creating the instance will have little to no effect and changing them is not recommended. The settings are made public mostly so that tools can set up and trigger appropriate callbacks.
28 |
29 | FileExplorer.Translate(str)
30 | ---------------------------
31 |
32 | Category: Internationalization
33 |
34 | Parameters:
35 |
36 | * str - A string to translate using `FileExplorer.settings.langmap`.
37 |
38 | Returns: A replacement string, if available.
39 |
40 | Thie function is called whenever an internal string will be displayed to a user to find a replacement string in the language map object.
41 |
42 | FileExplorer.FormatStr(format, ...)
43 | -----------------------------------
44 |
45 | Category: Internationalization
46 |
47 | Parameters:
48 |
49 | * format - A string containing matching placeholders for `{0}`, `{1}`, etc. for the rest of the parameters
50 |
51 | Returns: A formatted string with placeholders replaced with values from the other input parameters.
52 |
53 | This function is usually used in conjunction with Translate() to perform more complex multilingual string transformations that require multiple parameters to create.
54 |
55 | FileExplorer.EscapeHTML(text)
56 | -----------------------------
57 |
58 | Cateogry: Strings
59 |
60 | Parameters:
61 |
62 | * text - A string to sanitize for safe insertion into HTML.
63 |
64 | Returns: A HTML-safe string.
65 |
66 | This function escapes input content for insertion into HTML.
67 |
68 | FileExplorer.GetDisplayFilesize(numbytes, adjustprecision, units)
69 | -----------------------------------------------------------------
70 |
71 | Category: Files
72 |
73 | Parameters:
74 |
75 | * numbytes - An integer containing the number of bytes to convert for display.
76 | * adjustprecision - A boolean indicating whether or not to adjust the final precision when displaying file sizes to the user.
77 | * units - A string containing one of 'iec_windows', 'iec_formal', or 'si' to specify what units to use when displaying file sizes to the user.
78 |
79 | Returns: A string containing a displayable file size.
80 |
81 | This function converts an integer into a file size string (e.g. 1024 becomes 1 KB).
82 |
83 | FileExplorer.SetNamedStatusBarText(name, text, timeout)
84 | -------------------------------------------------------
85 |
86 | Category: Status bar
87 |
88 | Parameters:
89 |
90 | * name - A string containing the status bar segment name to target for the message.
91 | * text - A string containing the text to display. Should be escaped with EscapeHTML() to avoid issues.
92 | * timeout - An integer containing the number of milliseconds to show the message (Default is infinite).
93 |
94 | Returns: Nothing.
95 |
96 | This function updates a named segment in the status bar with the specified text.
97 |
98 | When a timeout is specified, the message shows until the timeout or another message replaces it. A message with a timeout may also momentarily hide other messages such that it fits on the screen.
99 |
100 | There are three predefined segments: folder, selected, message. The first two should only be used by the widget. The third (message) should be used primarily for messages that timeout. Other segments can be added as needed.
101 |
102 | FileExplorer.CreateProgressTracker(cancelcallback)
103 | --------------------------------------------------
104 |
105 | Category: Status bar
106 |
107 | Parameters:
108 |
109 | * cancelcallback - A function to call if the user clicks the cancel button.
110 |
111 | Returns: An object containing a progress tracker.
112 |
113 | This function registers a new progress tracker and returns it. This allows for long-running operations to take place while providing regular visual feedback (e.g. copying files). If a cancel callback is supplied, the user can cancel running operations by clicking the cancel button.
114 |
115 | Each tracker contains the following options:
116 |
117 | * started - A UNIX timestamp of when the object was created (Default is Date.now()).
118 | * totalbytes - An integer containing the number of bytes transferred/moved (Default is 0).
119 | * showbyterate - A boolean indicating whether or not to show the byte rate after 3 seconds (Default is false).
120 | * uploading - A boolean of false (if not uploading) or an integer that contains how many items are actively being uploaded (Default is false).
121 | * queueditems - An integer containing the number of known items in the queue (Default is 0).
122 | * queuesizeunknown - A boolean indicating whether or not the actual size of the queue is unknown (Default is false). This is useful when the actual queue size is unknown but some number of items (queueditems) is known.
123 | * itemsdone - An integer containing the number of items that have been processed successfully (Default is 0).
124 | * faileditems - An integer containing the number of items that did not process successfully (Default is 0).
125 | * cancelcallback - A function to call when the user clicks the cancel button (Default is null).
126 | * finishmessage - A string containing the message to display in the status bar when the trackers is done (Default is ''). Useful for showing 'Copying done' or 'Deletion stopped'.
127 |
128 | These options are intended to be updated on a regular basis. UpdateProgressText() is automatically called every second until no trackers are left.
129 |
130 | FileExplorer.UpdateProgressText()
131 | ---------------------------------
132 |
133 | Category: Status bar
134 |
135 | Parameters: None.
136 |
137 | Returns: Nothing.
138 |
139 | This function updates the progress area of the status bar with the combined information of all trackers. When a tracker exists, this function is automatically called every second until no trackers are left.
140 |
141 | FileExplorer.RemoveProgressTracker(tracker, finishmessage)
142 | ----------------------------------------------------------
143 |
144 | Category: Status bar
145 |
146 | Parameters:
147 |
148 | * tracker - An object containing a progress tracker.
149 | * finishmessage - An optional string that contains the message to display if this is the last progress tracker (Default is false).
150 |
151 | Returns: Nothing.
152 |
153 | This function removes a progress tracker. If it is the last progress tracker, the status bar is left alone until an action takes place (mouse move, keyboard event, or touch) and is removed about one second after an action takes place. This allows a user to see the final result if they stepped away for a moment.
154 |
155 | FileExplorer.addEventListener(eventname, callback)
156 | --------------------------------------------------
157 |
158 | Category: Events
159 |
160 | Parameters:
161 |
162 | * eventname - A string containing a name of a FileExplorer event to listen to.
163 | * callback - A function to call when the event fires.
164 |
165 | Returns: Nothing.
166 |
167 | This function presents a familiar function for registering for custom events emitted by FileExplorer.
168 |
169 | Known events:
170 |
171 | * tool_[event] - Reserved for tool-specific events.
172 | * blur - Dispatched when the widget is blurred.
173 | * focus - Dispatched when the widget is focused.
174 | * update_tool - Dispatched when a tool needs to update in response to changes in the current folder.
175 | * open_file - Dispatched when a user double-clicks/taps on one or more selected items.
176 | * selections_changed - Dispatched when the selections in the current folder change.
177 | * refresh_folder - Dispatched when it is time to refresh a specific folder (not necessarily the current folder).
178 | * navigated - Dispatched when navigation takes place.
179 | * history_changed - Dispatched whenever the history stack changes.
180 | * move - Dispatched when moving items.
181 | * copy - Dispatched when copying items.
182 | * upload_error - Dispatched when an upload fails (after all retry attempts fail) or one of the files or directories on the system is invalid/unreadable.
183 | * upload_done - Dispatched when an upload completes successfully.
184 | * update_upload_fileinfo - Dispatched when preparing the XHR request for an upload chunk.
185 | * init_upload - Dispatched when initializing an upload.
186 | * get_download_url - Dispatched when a drag-and-drop or copy/cut operation occurs to get the information needed to build a DownloadURL (Chromium only).
187 | * keydown - Dispatched when the user presses a key. Primarily used by tools.
188 | * rename - Dispatched when the user renames an item.
189 | * delete - Dispatched when the user deletes/recycles an item.
190 | * destroy - Dispatched when the Destroy() function is called.
191 |
192 | Most of these events have equivalents in the settings object and associated callbacks will automatically be registered as event listeners during initialization.
193 |
194 | FileExplorer.removeEventListener(eventname, callback)
195 | -----------------------------------------------------
196 |
197 | Category: Events
198 |
199 | Parameters:
200 |
201 | * eventname - A string containing a name of a FileExplorer event to stop listening to.
202 | * callback - A function containing a registered callback to remove.
203 |
204 | Returns: Nothing.
205 |
206 | This function presents a familiar function for unregistering from custom events emitted by FileExplorer.
207 |
208 | FileExplorer.hasEventListener(eventname)
209 | ----------------------------------------
210 |
211 | Category: Events
212 |
213 | Parameters:
214 |
215 | * eventname - A string containing a name of a FileExplorer event to check.
216 |
217 | Returns: A boolean of true if there are event listeners for the specified event, false otherwise.
218 |
219 | This function checks for the existence of an event and whether or not there are any listeners registered for the event.
220 |
221 | FileExplorer.ClearSelectedItems(ignorebusy, skipuiupdate)
222 | ---------------------------------------------------------
223 |
224 | Category: Item selection
225 |
226 | Parameters:
227 |
228 | * ignorebusy - An internal boolean that bypasses the busy folder check. Do not use.
229 | * skipuiupdate - An internal boolean that bypasses updating the toolbar and status bar. Do not use.
230 |
231 | Returns: Nothing.
232 |
233 | This function clears all existing selections. The various boolean options should not be used by external callers (i.e. just call the function like `fe.ClearSelectedItems()`).
234 |
235 | FileExplorer.SelectAllItems(skipuiupdate)
236 | -----------------------------------------
237 |
238 | Category: Item selection
239 |
240 | Parameters:
241 |
242 | * skipuiupdate - An internal boolean that bypasses updating the toolbar and status bar. Do not use.
243 |
244 | Returns: Nothing.
245 |
246 | This function selects all items. The skipuiupdate option should not be used by external callers (i.e. just call the function like `fe.SelectAllItems()`).
247 |
248 | FileExplorer.SelectItemsFromLastAnchor(ignorebusy, skipuiupdate)
249 | ----------------------------------------------------------------
250 |
251 | Category: Item selection
252 |
253 | Parameters:
254 |
255 | * ignorebusy - An internal boolean that bypasses the busy folder check. Do not use.
256 | * skipuiupdate - An internal boolean that bypasses updating the toolbar and status bar. Do not use.
257 |
258 | Returns: Nothing.
259 |
260 | This function selects all items from the internal anchor position to the currently focused element. The various boolean options should not be used by external callers (i.e. just call the function like `fe.SelectItemsFromLastAnchor()`).
261 |
262 | FileExplorer.SetSelectedItems(ids, keepprev, skipuiupdate)
263 | ----------------------------------------------------------
264 |
265 | Category: Item selection
266 |
267 | Parameters:
268 |
269 | * ids - An array containing item IDs to select.
270 | * keepprev - A boolean that controls whether or not to clear previously selected items (Default is false).
271 | * skipuiupdate - An internal boolean that bypasses updating the toolbar and status bar. Do not use.
272 |
273 | Returns: Nothing.
274 |
275 | This function sets the selected items in the current folder with the specified item IDs. It clears previous selections by default. The skipuiupdate option should not be used by external callers.
276 |
277 | FileExplorer.ToggleItemSelection(elem, ignorebusy, skipuiupdate)
278 | ----------------------------------------------------------------
279 |
280 | Category: Item selection
281 |
282 | Parameters:
283 |
284 | * elem - A string containing an item ID or a DOM node of an item to toggle selection. External callers should use the item ID string method.
285 | * ignorebusy - An internal boolean that bypasses the busy folder check. Do not use.
286 | * skipuiupdate - An internal boolean that bypasses updating the toolbar and status bar. Do not use.
287 |
288 | Returns: Nothing.
289 |
290 | This function toggles selection of a single item. The various boolean options should not be used by external callers (i.e. just call the function like `fe.ToggleItemSelection(elem)`).
291 |
292 | FileExplorer.GetNumSelectedItems()
293 | ----------------------------------
294 |
295 | Category: Selected items
296 |
297 | Parameters: None.
298 |
299 | Returns: An integer containing the number of selected items.
300 |
301 | This function returns the number of currently selected items in the current folder.
302 |
303 | FileExplorer.GetSelectedFolderEntries()
304 | ---------------------------------------
305 |
306 | Category: Selected items
307 |
308 | Parameters: None.
309 |
310 | Returns: An array containing the selected folder entries.
311 |
312 | This function returns the currently selected entries in the current folder.
313 |
314 | FileExplorer.GetSelectedItemIDs()
315 | ---------------------------------
316 |
317 | Category: Selected items
318 |
319 | Parameters: None.
320 |
321 | Returns: An array containing the IDs of the currently selected items.
322 |
323 | This function returns just the IDs of the currently selected items in the current folder.
324 |
325 | FileExplorer.IsSelectedItem(id)
326 | -------------------------------
327 |
328 | Category: Selected items
329 |
330 | Parameters:
331 |
332 | * id - A string containing an ID to check for currently selected status.
333 |
334 | Returns: A boolean of true if the item associated with the ID is selected, false otherwise.
335 |
336 | This function returns whether or not the item associated with the ID is selected.
337 |
338 | FileExplorer.OpenSelectedItems()
339 | --------------------------------
340 |
341 | Category: Selected item actions
342 |
343 | Parameters: None.
344 |
345 | Returns: Nothing.
346 |
347 | This function triggers an open event for each selected non-folder item. If a single folder is selected among all selected items, this function will also trigger navigation to that folder.
348 |
349 | FileExplorer.RenameSelectedItem()
350 | ---------------------------------
351 |
352 | Category: Selected item actions
353 |
354 | Parameters: None.
355 |
356 | Returns: Nothing.
357 |
358 | This function starts a rename operation if there is exactly one selected item and at least one 'rename' event listener. The UI shows a textarea over the existing text with the item name contained within it. If the name is modified, event listeners are called to handle the rename operation.
359 |
360 | FileExplorer.DeleteSelectedItems(recycle)
361 | -----------------------------------------
362 |
363 | Category: Selected item actions
364 |
365 | Parameters:
366 |
367 | * recycle - A boolean indicating whether or not the selected items should move to a recycling bin.
368 |
369 | Returns: Nothing.
370 |
371 | This function starts a delete operation of selected items if there is at least one 'delete' event listener. The 'recycle' option can be passed to and utilized by event handlers to optionally move items to a recycling bin instead of permanently deleting items off the server. A cron job could be used to automatically clean up items in a recycling bin folder after they have been in there for a week.
372 |
373 | FileExplorer.SetFocusItem(id, updateanchor)
374 | -------------------------------------------
375 |
376 | Category: Focused item
377 |
378 | Parameters:
379 |
380 | * id - A string containing an item ID to focus or a boolean of false to clear focus.
381 | * updateanchor - A boolean that indicates whether or not to update the anchor position for later Shift key selections.
382 |
383 | Returns: Nothing.
384 |
385 | This function sets/clears the focused item. When there is no focused item, focus reverts to the scroll region. The anchor position, which is used when holding down the Shift key, can be updated at the same time.
386 |
387 | FileExplorer.ScrollToFocusedItem()
388 | ----------------------------------
389 |
390 | Category: Focused item
391 |
392 | Parameters: None.
393 |
394 | Returns: Nothing.
395 |
396 | This function scrolls the scroll region so that the focused item is fully visible.
397 |
398 | FileExplorer.GetFocusedItem()
399 | -----------------------------
400 |
401 | Category: Focused item
402 |
403 | Parameters: None.
404 |
405 | Returns: The DOM node containing the focused item or a boolean of false if not set.
406 |
407 | This function returns the internal DOM node of the focused item. When the focused item is not set, it returns false.
408 |
409 | FileExplorer.GetFocusedItemID()
410 | -------------------------------
411 |
412 | Category: Focused item
413 |
414 | Parameters: None.
415 |
416 | Returns: A string containing the folder item ID of the focused item or a boolean of false if the focused item is not set.
417 |
418 | This function returns the folder item ID of the focused item. When the focused item is not set, it returns false. While it is possible to get the ID directly from a DOM node, it is not recommended.
419 |
420 | FileExplorer.HasItemFocus()
421 | ---------------------------
422 |
423 | Category: Focused item
424 |
425 | Parameters: None.
426 |
427 | Returns: A boolean of true if there is a set focused item and it is also the `document.activeElement`, false otherwise.
428 |
429 | This function returns whether or not the set focused item is also the currently focused item in the browser DOM.
430 |
431 | FileExplorer.HasFocus(itemsonly)
432 | --------------------------------
433 |
434 | Category: Focus
435 |
436 | Parameters:
437 |
438 | * itemsonly - A boolean that can restrict the return value to the folder items area (Default is false).
439 |
440 | Returns: A boolean of true if the widget or items currently have focus.
441 |
442 | This function determines whether the currently focused `document.activeElement` is part of the folder items area when `itemsonly` is true or part of the widget otherwise (navigation, path segments, toolbar, etc).
443 |
444 | FileExplorer.Focus(itemsonly, alwaysfocus)
445 | ------------------------------------------
446 |
447 | Category: Focus actions
448 |
449 | Parameters:
450 |
451 | * itemsonly - A boolean that indicates focus should be for the folder items area only (Default is false).
452 | * alwaysfocus - A boolean that indicates that focus should always take place (Default is false). Do not use.
453 |
454 | Returns: Nothing.
455 |
456 | This function focuses on the items area if `itemsonly` is true, the widget otherwise. If the widget/items region already has focus, nothing happens unless `alwaysfocus` is set to true. The second parameter is only useful for stealing keyboard focus away from, for example, the hidden clipboard capture overlay, which shares the same DOM root as the the main items region.
457 |
458 | Folder.GetPathIDs(path)
459 | -----------------------
460 |
461 | Category: Path information
462 |
463 | Parameters:
464 |
465 | * path - An array of arrays that defines a path.
466 |
467 | Returns: An array of path IDs.
468 |
469 | This function iterates over the path and constructs an array of path IDs. The return value is intended to be useful for sending the path of a folder to a server.
470 |
471 | FileExplorer.IsValidPath(path)
472 | ------------------------------
473 |
474 | Category: Path
475 |
476 | Parameters:
477 |
478 | * path - An array of arrays that defines a path.
479 |
480 | Returns: A boolean if the array structure looks correct, false otherwise.
481 |
482 | This function checks an input path array for validity. Used by SetPath() to prevent invalid structures from being used.
483 |
484 | FileExplorer.SetPath(newpath)
485 | -----------------------------
486 |
487 | Category: Path actions
488 |
489 | Parameters:
490 |
491 | * newpath - An array of arrays that defines the path to set.
492 |
493 | Returns: Nothing.
494 |
495 | This function performs a path change operation, setting the path to the new path, adding to the history/navigation stack, triggering folder refreshes, and updating the DOM. For most use-cases, using the 'initpath' option gets things started without needing to call this function directly.
496 |
497 | If the calculated new path key is identical to the current path key, the current folder is refreshed in-place without modifying the history stack.
498 |
499 | FileExplorer.GetMappedFolderFromPath(path)
500 | ------------------------------------------
501 |
502 | Category: Mapped folders
503 |
504 | Parameters:
505 |
506 | * path - An array of arrays that defines a path.
507 |
508 | Returns: An object containing a Folder instance if the path is mapped, a boolean of false otherwise.
509 |
510 | This function returns the Folder object associated with a path if it is in the folder map. A folder is placed into the internal widget folder map when it is referenced by a path segment somewhere in the history stack. During the lifetime of the widget, mapped folders can come and go. It is not safe to access a mapped folder reference beyond the lifetime of a function callback.
511 |
512 | FileExplorer.GetCurrentFolder()
513 | -------------------------------
514 |
515 | Category: Mapped folders
516 |
517 | Parameters: None.
518 |
519 | Returns: The current Folder object that is associated with the DOM.
520 |
521 | This function returns the current Folder object that is associated with the DOM. Updating the entries in this object triggers event callbacks within the widget that reflect in DOM updates.
522 |
523 | FileExplorer.IsMappedFolder(folder)
524 | -----------------------------------
525 |
526 | Category: Mapped folders
527 |
528 | Parameters:
529 |
530 | * folder - A valid Folder object instance.
531 |
532 | Returns: A boolean of true if the object is in the folder map, false otherwise.
533 |
534 | This function checks the folder map to see if the input object is a mapped folder. It actually first compares the input object with the current folder for efficiency and then falls back to walking through the folder map to find a match. When using asynchronous logic, it is possible for a folder to be removed from the folder map before the asynchronous action completes (e.g. the user navigates to another folder during an operation).
535 |
536 | FileExplorer.RefreshFolders(forcecurrfolder)
537 | --------------------------------------------
538 |
539 | Category: Mapped folder actions
540 |
541 | Parameters:
542 |
543 | * forcecurrfolder - A boolean indicating whether or not to ignore the 5 minute refresh timer for the current folder (Default is false).
544 |
545 | Returns: Nothing.
546 |
547 | This function triggers refresh events for folders in the folder map that were last refreshed over 5 minutes ago.
548 |
549 | FileExplorer.HistoryBack(e)
550 | ---------------------------
551 |
552 | Category: Navigation actions
553 |
554 | Parameters:
555 |
556 | * e - An optional browser event object to call preventDefault() on.
557 |
558 | Returns: Nothing.
559 |
560 | This function navigates back through the history stack one level.
561 |
562 | FileExplorer.HistoryForward(e)
563 | ------------------------------
564 |
565 | Category: Navigation actions
566 |
567 | Parameters:
568 |
569 | * e - An optional browser event object to call preventDefault() on.
570 |
571 | Returns: Nothing.
572 |
573 | This function navigates forward through the history stack one level.
574 |
575 | FileExplorer.NavigateUp(e)
576 | --------------------------
577 |
578 | Category: Navigation actions
579 |
580 | Parameters:
581 |
582 | * e - An optional browser event object to call preventDefault() on.
583 |
584 | Returns: Nothing.
585 |
586 | This function navigates up one path segment level.
587 |
588 | FileExplorer.CreateNode(tag, classes, attrs, styles)
589 | ----------------------------------------------------
590 |
591 | Category: Miscellaneous exports
592 |
593 | Parameters:
594 |
595 | * tag - A string containing the tag to use for the new DOM node.
596 | * classes - An optional string or array of strings containing classes to assign to the new DOM node.
597 | * attrs - An optional object of key-value pairs to assign to attributes of the new DOM node.
598 | * styles - An optional object of key-value pairs to assign to styles of the new DOM node.
599 |
600 | Returns: A newly created, detached DOM node.
601 |
602 | This function creates a new DOM node with classes, attributes, and styles. Can be useful for building some custom tools.
603 |
604 | FileExplorer.DebounceAttributes
605 | -------------------------------
606 |
607 | Category: Miscellaneous exports
608 |
609 | See: [DebounceAttributes Class](docs/debounce_attributes.md)
610 |
611 | FileExplorer.PrepareXHR(options)
612 | --------------------------------
613 |
614 | Category: Miscellaneous exports
615 |
616 | See: [PrepareXHR Class](docs/prepare_xhr.md)
617 |
618 | FileExplorer.GetElements()
619 | --------------------------
620 |
621 | Category: Miscellaneous exports
622 |
623 | Parameters: None.
624 |
625 | Returns: The internal elems object for the widget.
626 |
627 | This function returns the internal elements object for use with certain tools. While element keys are not likely to change, there is no guarantee as this is an internal structure.
628 |
629 | FileExplorer.GetScrollLineHeight()
630 | ----------------------------------
631 |
632 | Category: Miscellaneous exports
633 |
634 | Parameters: None.
635 |
636 | Returns: An integer containing the pixel count line height of a 1em unstyled character to be used for scroll calculations.
637 |
638 | This function returns the precalculated value of the pixel count line height of a 1em unstyled character to be used for scroll calculations. This is used, for example, to convert a vertical mouse wheel event into a horizontal scroll of the correct amount in the path segment bar.
639 |
640 | FileExplorer.ShowClipboardPasteBox()
641 | ------------------------------------
642 |
643 | Category: Miscellaneous exports
644 |
645 | Parameters: None.
646 |
647 | Returns: Nothing.
648 |
649 | This function shows the clipboard paste box. Used by the paste tool.
650 |
651 | FileExplorer.HideClipboardPasteBox(e)
652 | -------------------------------------
653 |
654 | Category: Miscellaneous exports
655 |
656 | Parameters:
657 |
658 | * e - An optional browser event object to compare the target of for focus handling.
659 |
660 | Returns: Nothing.
661 |
662 | This function hides the clipboard paste box and removes event handlers.
663 |
664 | FileExplorer.ProcessFilesAndUpload(targettype, targetnode, dt)
665 | --------------------------------------------------------------
666 |
667 | Category: Miscellaneous exports
668 |
669 | Parameters:
670 |
671 | * lasttype - A string containing one of 'currfolder', 'path', or 'item'. External callers should use 'currfolder'.
672 | * lastnode - A DOM node for 'path' or 'item' types or null.
673 | * dt - A DataTransfer object instance containing 'items' and/or 'files' arrays.
674 |
675 | Returns: Nothing.
676 |
677 | This function processes the incoming data transfer files/folders and starts uploading them to the specified target. With some minor effort, it is possible to upload a Blob instance from outside the widget to the current folder using this function (e.g. save an image from a canvas element).
678 |
679 | The 'path' type requires pointing at a valid DOM node in the path segment region. The 'item' type requires pointing at a valid folder item DOM node. These types are mostly internal for handling drag-and-drop operations.
680 |
681 | FileExplorer.StartOperationIndicator()
682 | --------------------------------------
683 |
684 | Category: Miscellaneous exports
685 |
686 | Parameters: None.
687 |
688 | Returns: Nothing.
689 |
690 | This function starts a wait indicator when hovering over the widget for up to 15 seconds or until `StopOperationIndicator()` is called, whichever comes first. This function is refcounted, so equal numbers of Start/Stop calls need to be made to stop the indicator.
691 |
692 | FileExplorer.StopOperationIndicator()
693 | -------------------------------------
694 |
695 | Category: Miscellaneous exports
696 |
697 | Parameters: None.
698 |
699 | Returns: Nothing.
700 |
701 | This function reduces the refcount of StartOperationIndicator() by 1. When it reaches 0, the wait indicator class is removed.
702 |
703 | FileExplorer.DispatchToolEvent(eventname, params)
704 | -------------------------------------------------
705 |
706 | Category: Tool events
707 |
708 | Parameters:
709 |
710 | * eventname - A string containing a name of a tool event to dispatch.
711 | * params - A single option or an array of options to pass to callbacks.
712 |
713 | Returns: Nothing.
714 |
715 | This function dispatches a tool event. It should only be called by registered toolbar tools.
716 |
717 | FileExplorer.addToolEventListener(eventname, callback)
718 | ------------------------------------------------------
719 |
720 | Category: Tool events
721 |
722 | Parameters:
723 |
724 | * eventname - A string containing a name of a tool event to listen to.
725 | * callback - A function to call when the event fires.
726 |
727 | Returns: Nothing.
728 |
729 | This function presents a familiar function for registering for custom events emitted by toolbar tools.
730 |
731 | Most events have equivalents in the settings object and associated callbacks will automatically be registered as event listeners during initialization.
732 |
733 | FileExplorer.removeToolEventListener(eventname, callback)
734 | ---------------------------------------------------------
735 |
736 | Category: Tool events
737 |
738 | Parameters:
739 |
740 | * eventname - A string containing a name of a tool event to stop listening to.
741 | * callback - A function containing a registered callback to remove.
742 |
743 | Returns: Nothing.
744 |
745 | This function presents a familiar function for unregistering from custom events emitted by FileExplorer.
746 |
747 | FileExplorer.hasToolEventListener(eventname, callback)
748 | ------------------------------------------------------
749 |
750 | Category: Tool events
751 |
752 | Parameters:
753 |
754 | * eventname - A string containing a name of a tool event to check.
755 |
756 | Returns: A boolean of true if there are event listeners for the specified tool event, false otherwise.
757 |
758 | This function checks for the existence of a tool event and whether or not there are any listeners registered for the event.
759 |
760 | FileExplorer.ToolStateUpdated()
761 | -------------------------------
762 |
763 | Category: Tool notifications
764 |
765 | Parameters: None.
766 |
767 | Returns: Nothing.
768 |
769 | This function is used by tools to let the FileExplorer class instance know that at least one tool has toggled between enabled/disabled states and it should adjust tabIndex attributes and element focus as needed.
770 |
771 | FileExplorer.AddToolbarButton(classname, title)
772 | -----------------------------------------------
773 |
774 | Category: Toolbar
775 |
776 | Parameters:
777 |
778 | * classname - A string containing a class name to use for the toolbar button.
779 | * title - A string containing a title to use for the button (tooltip).
780 |
781 | Returns: The created DOM node.
782 |
783 | This function is used by tools to add a toolbar button during setup of the tool.
784 |
785 | FileExplorer.Destroy()
786 | ----------------------
787 |
788 | Category: Destructor
789 |
790 | Parameters: None.
791 |
792 | Returns: Nothing.
793 |
794 | This is a hefty function that tears down the entire widget. Calling other functions except IsDestroyed() after this function will result in an error or undefined behavior. Given the nature of the widget, it might make more sense to hide it and show it again later if it is needed rather than destroying it so users aren't forced to constantly navigate to specific paths.
795 |
796 | FileExplorer.IsDestroyed()
797 | --------------------------
798 |
799 | Category: Destructor
800 |
801 | Parameters: None.
802 |
803 | Returns: A boolean that indicates whether or not Destroy() was called.
804 |
805 | This function tracks whether or not an instance has been destroyed.
806 |
--------------------------------------------------------------------------------