Nowadays, everyone seems to think dropping a folder is somehow optional. They all have given up on the File API “Directories and System” (except Google which at least implemented it). I have to admit, I clearly don’t understand because in the ECM world, that just a must-have feature…

Anyway, since this is something our users are expecting, especially since there are used to it with the Workplace XT (via the applet), we had to find a workaround. Actually we found two which are quite complementary. One is using the Chrome Directories and System API, which really allows a true folder drop, but way better than Workplace XT since it’s applet free and therefore mobile supported. The other is supported by all browsers and requires the user to only zip the folder and drop the zip. It’ is only 1 second extra work for the user instead of the hours it would have to spend to create all the folder hierarchy manually and upload files folder by folder. This seems like a good alternative and again, it is supported by every brother.

Let’s present these two workarounds quickly. I won’t explain the whole implementation since it might get quite complex but instead, I will explain how to address the problem.

1. Supported by all browser, zip and drop

This is the easiest way I came up for the user, it only requires the user to zip the folder and drop it. Then it acts like a normal add. How does it work?

That actually not so hard, the unzipping is done entirely by the client (browser) in JavaScript, I’m using the zip,js library (great work from Gildas Lormeau by the way). That way we finally use a bit the client resources and not overload the server. I get all entries, which give me Blob object,. From the filename and the Blob, I can build W3C File API object as given by a classic drop which I will use to do the add. I also give the Wizard the path within the object because it needs to create the directory.

This is actually not so hard, what is a lot harder is implementing the Add Wizard able to add multiple files from different types without being a nightmare for the user (The built-in Add Wizard of ICN allows only one File Type at a time if you associated several entry templates). Also this Wizard needs to be able to create/re-use folders to place documents in the same folder they were in the zip. That the part is too much work and I won’t explain it. You can actually see what it’s like in the video, the wizard classifies by most relevant Entry Template, then generic one if there is none for the File Type, or no Entry template if there is none associated on the folder. The good thing is that when you have this wizard, you can also use it for the Chrome drop folder or any other multi-add operation.

Implementation details:

First you need to find the right entry point to hook up the ICN behavior and replace it with your smart drop. I did that in two points:

• When dropping external files on the content pane (right pane)
• When dropping external files on a Tree node (left pane)

Here is how to hook up this two entry points

aspect.around(DndFromDesktopAddDoc.prototype, "displayDialog", function (originalFunction) {
    return function (files, targetItem, teamspace, defaultClass) {
        // Here you can overwrite the behavior of when ICN is displaying the
        // standard Add Document Wizard for the files to drop
        // Basically you would check if the file is a unique zip, and launch your
        // Smart wizard instead of the basic one
    };
});
aspect.around(Tree.prototype, "onExternalDrop", function (original) {
    return function (evt) {
        // Here you can overwrite the behavior of when ICN is displaying the
        // standard Add Document Wizard for the files to drop
        // Basically you would check if the event's files (evt.dataTransfer.files) contains
        // a unique zip, and launch your Smart wizard instead of the basic one
    };
});

Then you need to check if you got only one zip file dropped, and if it is, deflate the zip file, build File object from the Blob and the entry name, and call your wizard with that:

aspect.around(DndFromDesktopAddDoc.prototype, "displayDialog", function (originalFunction) {
    return function (files, targetItem, teamspace, defaultClass) {
        if (files && files.length > 0) {
            if (this.addContentItem) {
                this.addContentItem.destroyRecursive();
            }
            outerThis.processFiles(files, targetItem, this);
        }
    };
});

aspect.around(Tree.prototype, "onExternalDrop", function (original) {
    return function (evt) {

        if (evt.dataTransfer.files.length > 0) {

            if (!outerThis.isSingleZip(evt.dataTransfer.files)) {
                return original.apply(this, [evt]);
            }

            // This is for us
            evt.preventDefault();
            evt.stopPropagation();
            var targetItem = this._getExternalDropTargetItem(evt),
                files = evt.dataTransfer.files;
            if (targetItem && this._eventHasFiles(evt) && this._numberWithinMaxDocToAdd(files)) {
                var success = lang.hitch(this, function () {
                    if (this.addContentItem) {
                        this.addContentItem.destroyRecursive();
                    }

                    if (targetItem.isInstanceOf(ecm.model.Favorite)) {
                        targetItem = targetItem.item;
                    }

                    outerThis.processFiles(files, targetItem, this);

                });
                if (targetItem.isInstanceOf && targetItem.isInstanceOf(ecm.model.Favorite) && !targetItem.item) {
                    targetItem.retrieveFavorite(lang.hitch(this, function (obj) {
                        if (!this._dndModel.hasPrivilegeToAddTo(targetItem)) {
                            this._dndModel.addCannotDropErrorMessage(targetItem.item.name);
                        } else {
                            this._verifyCanAddFiles(evt.dataTransfer.files).then(success, this._verifyCanAddFilesFailure);
                        }
                    }));
                } else {
                    this._verifyCanAddFiles(evt.dataTransfer.files).then(success, this._verifyCanAddFilesFailure);
                }
            }
            return false;
        }

    };
});

With the processFiles function actually doing the conversion form the zip files to W3C files:

processFiles: function (files, targetItem, originalThis) {
    var readyToProceed = new Deferred();

    // Here we are droping one archive (zip), unzip all and build the files from it
    if (files.length == 1 && files[0].name.indexOf('.zip', files[0].name.length - ".zip".length) !== -1) {
        // We convert the entries from the zip in files
        this.getEntries(files[0]).then(lang.hitch(this, function (entries) {
            var waitForAll = [], newEntries = [], i;
            for (i = 0; i < entries.length; i++) {
                if (!entries[i].directory) {
                    var def = new Deferred();
                    waitForAll.push(def);
                    this.getEntryFile(entries[i], def).then(function (res) {
                        var file = new File([res.blob], res.entry.filename);
                        file.displayname = res.entry.filename;
                        file.folderpath = res.entry.filename.substring(0, res.entry.filename.lastIndexOf("/"));
                        console.log('path set to: ' + file.folderpath);
                        newEntries.push(file);
                        res.def.resolve();
                    });
                }
            }

            all(waitForAll).then(function () {
                files = newEntries;
                readyToProceed.resolve();
            });
        }));

    } else {
        readyToProceed.resolve();
    }

    readyToProceed.then(lang.hitch(originalThis, function () {

        // Check the number of item since ICN could check because it thinks it's only one file
        if (ecm.model.desktop && ecm.model.desktop.maxNumberDocToAdd < files.length) {
            ecm.model.desktop.addMessage(Message.createErrorMessage("add_document_too_many_items_error", [
                ecm.model.desktop.maxNumberDocToAdd,
                files.length
            ]));
            return;
        }
        // Display the Wizard
        this.addContentItem = new MultiDocWizard({
            checkin: false,
            repository: targetItem.repository,
            parentFolder: targetItem
        });
        this.addContentItem.show(files);
    }));
},
getEntries: function (file) {
    var res = new Deferred();
    zip.createReader(new zip.BlobReader(file), function (zipReader) {
        zipReader.getEntries(function (entries) {
            res.resolve(entries);
        });
    }, null);
    return res.promise;
},
getEntryFile: function (entry, def) {
    var res = new Deferred();
    var writer = new zip.BlobWriter();
    entry.getData(writer, function (blob) {
        res.resolve({
            'entry': entry,
            'blob': blob,
            'def': def
        });
    }, null);
    return res.promise;
}

 

2. Using the Chrome Drop folder

Thanks Chrome! At least you are progressing on this topic because no one seems to care… They implemented the File API Directories and System, which allow writing folder when the user drop it, without extra permission (well the user drop it so I guess he knows 🙂 ). Then you can read all entries, all sub-subfolders and get from those entries the W3C File object. Then you add as extra data on the file the path within the repository since it will be use by the Wizard to add the file in the right subfolder. Then give all that to your magical Wizard and you’re done.

Here is a demo:

Implementation details:

And for those who are interested by the implementation, here are some details. First, as for the zip drop, you need to find the right entry point to hook up the ICN behavior and replace it with your smart drop. I did that in two points:

• When dropping external files on the content pane (right pane)
• When dropping external files on a Tree node (left pane)

However this time we need to catch the drop sooner than for the zip on the content pane because we want to override the error message saying we can not drop folder. Here is how to hook up this two entry points

aspect.around(DndFromDesktop.prototype, "onExternalDrop", function (originalFunction) {
    return function (evt) {
        if (evt.dataTransfer && evt.dataTransfer.items &&
                evt.dataTransfer.items.length &&
                evt.dataTransfer.items[0].webkitGetAsEntry() &&
                evt.dataTransfer.items[0].webkitGetAsEntry().isDirectory) {

            // Get the webit entry
            var entry = evt.dataTransfer.items[0].webkitGetAsEntry();

            // Get all files in the folder
            var allFiles = [];
            outerThis.readDir(entry, allFiles).then(lang.hitch(this, function () {

                // Check if number is not over limit
                if (ecm.model.desktop && ecm.model.desktop.maxNumberDocToAdd < allFiles.length) {
                    ecm.model.desktop.addMessage(Message.createErrorMessage("add_document_too_many_items_error", [
                        ecm.model.desktop.maxNumberDocToAdd,
                        allFiles.length
                    ]));
                    return;
                }
                // Launch the Add Wizard with the files in the folder
                var row = this._getExternalDropTargetRow(evt);
                var rowItem = row ? row.item() : null;
                var targetItem = this._getTargetItem(rowItem);
                this.addContentItem = new MultiDocWizard({
                    checkin: false,
                    repository: targetItem.repository,
                    parentFolder: targetItem
                });
                this.addContentItem.show(allFiles);
            }));

        } else {
            // This is not a single folder, run normal drop
            originalFunction.apply(this, [evt]);
        }

    };
});


aspect.around(Tree.prototype, "onExternalDrop", function (original) {
    return function (evt) {

        if (evt.dataTransfer.files.length > 0) {

            // If we are dropping a single zip, deal with it, if not acall original so other strageties
            // can deal with it (ChromeDrop or if not standard drop using MultiDocWizard)
            if (!outerThis.isChromeDrop(evt)) {
                return original.apply(this, [evt]);
            }

            // This is for us
            evt.preventDefault();
            evt.stopPropagation();

            // Get the webit entry
            var entry = evt.dataTransfer.items[0].webkitGetAsEntry();

            // Get all files in the folder
            var allFiles = [];
            outerThis.readDir(entry, allFiles).then(lang.hitch(this, function () {

                // Check if number is not over limit
                if (ecm.model.desktop && ecm.model.desktop.maxNumberDocToAdd < allFiles.length) {
                    ecm.model.desktop.addMessage(Message.createErrorMessage("add_document_too_many_items_error", [
                        ecm.model.desktop.maxNumberDocToAdd,
                        allFiles.length
                    ]));
                    return;
                }
                // Launch the Add Wizard with the files in the folder
                var targetItem = this._getExternalDropTargetItem(evt);
                this.addContentItem = new MultiDocWizard({
                    checkin: false,
                    repository: targetItem.repository,
                    parentFolder: targetItem
                });
                this.addContentItem.show(allFiles);
            }));
        }

    };
});

Then, you need to convert the webkit entry into an array of files to give to your wizard. That’s what does the readDir function. Here is the code of this function.

/**
 * Read en entry and resolve when the file has been added to the allFiles array
 * @param entry the webkit entry
 * @ allFiles {@File[]} the array of file where add the file
 * @return Promise a promise resolving when the file has been added to the array
 */
readFile: function (entry, allFiles) {
    var res = new Deferred();
    entry.file(lang.hitch(this, function (file) {
        file.folderpath = entry.fullPath.substring(0, entry.fullPath.lastIndexOf("/"));
        file.displayname = entry.fullPath;
        allFiles.push(file);
        res.resolve();
    }));
    return res.promise;
},
/**
 * Read en entry which is a directory, returns all contains files (recursively) in the allFiles array
 * and resolve when it's done
 * @param entry the webkit entry
 * @ allFiles {@File[]} the array of file where add the file
 * @return Promise a promise resolving when all files have been added to the array
 */
readDir: function (entry, allFiles) {
    var res = new Deferred();
    var dirReader = entry.createReader();

    this.readEntries(dirReader, allFiles).then(function () {
        res.resolve();
    });

    return res.promise;
},
/**
 * Read one directory reader, returns all contains files (recursively) in the allFiles array
 * and resolve when it's done
 * @param dirReader the directory reader
 * @ allFiles {@File[]} the array of file where add the file
 * @return Promise a promise resolving when all files have been added to the array
 */
readEntries: function (dirReader, allFiles) {
    var res = new Deferred();
    dirReader.readEntries(lang.hitch(this, function (results) {
        var allSubFolderPromises = [];
        if (!results.length) {
            res.resolve();
        } else {
            var i;
            for (i = 0; i < results.length; i++) {
                if (results[i].isDirectory) {
                    var subdirReader = results[i].createReader();
                    allSubFolderPromises.push(this.readEntries(subdirReader, allFiles));
                } else {
                    // We read the file and also wait for it
                    allSubFolderPromises.push(this.readFile(results[i], allFiles));
                }
            }
            // Also wait for me
            allSubFolderPromises.push(this.readEntries(dirReader, allFiles));

            // Then wai everyone
            all(allSubFolderPromises).then(function () {
                res.resolve();
            });
        }
    }), null);
    return res.promise;
}