neo.mjs 5.16.4 → 5.17.0

package/src/form/field/FileUpload.mjs

@@ -14,7 +14,7 @@ const
  * An accessible file uploading widget which automatically commences an upload as soon as
  * a file is selected using the UI.
  *
- * The URL to which the file must be uploaded is specified in the {@link #member-uploadUrl} property.
+ * The URL to which the file must be uploaded is specified in the {@link config#uploadUrl} property.
  * This service must return a JSON status response in the following form for successful uploads:
  *
  * ```json
@@ -130,6 +130,42 @@ class FileUpload extends Base {
 
         cls : [],
 
+        /**
+         * An Object containing a default set of headers to be passed to the server on every HTTP request.
+         * @member {Object} headers
+         */
+        headers : {},
+
+        /**
+         * An Object which allows the status text returned from the {@link #property-documentStatusUrl} to be
+         * mapped to the corresponding next widget state.
+         * @member {Object} documentStatusMap
+         */
+        documentStatusMap : {
+            SCANNING         : 'scanning',
+
+            // The server doing its own secondary upload to the final storage location may return this.
+            // We enter the same state as scanning. A spinner shows for the duration of this state
+            UPLOADING        : 'scanning',
+
+            MALWARE_DETECTED : 'scan-failed',
+            UN_DOWNLOADABLE  : 'not-downloadable',
+            DOWNLOADABLE     : 'downloadable',
+            DELETED          : 'deleted'
+        },
+
+        document_ : null,
+
+        /**
+         * If this widget should reference an existing document, configure the widget with a documentId
+         * so that it can initialize in the correct "uploaded" state.
+         *
+         * If this is *not* configured, then this property will be set after a successful upload to
+         * the id returned from the {@link #property-uploadUrl}.
+         * @member {String|Number} documentId
+         */
+        documentId : null,
+
         /**
          * The URL of the file upload service to which the selected file is sent.
          *
@@ -149,12 +185,14 @@ class FileUpload extends Base {
          * The document status request URL must be configured in {@link #member-documentStatusUrl}
          * @member {String} uploadUrl
          */
-        uploadUrl_ : null,
+        uploadUrl : null,
 
         /**
          * The name of the JSON property in which the document id is returned in the upload response
-         * JSON packet and the HTTP parameter which is used when requesting a malware scan and a document
-         * deletion.
+         * JSON packet and the token string which is substituted for the document id when requesting
+         * a malware scan and a document deletion.
+         *
+         * Defaults fro `documentId`
          *
          * @member {String} downloadUrl
          */
@@ -163,16 +201,38 @@ class FileUpload extends Base {
         /**
          * The URL from which the file may be downloaded after it has finished its scan.
          *
+         * This must contain a substitution token named the same as the {@link #property-documentIdParameter}
+         * which is used when creating a URL
+         * 
+         * for example:
+         * 
+         * ```json
+         * {
+         *     downloadUrl : '/getDocument/${documentId}'
+         * }
+         * ```
+         *
          * The document id returned from the {@link #member-uploadUrl upload} is passed in the parameter named
          * by the {@link #member-documentIdParameter}. It defaults to `'documentId'`.
          *
          * @member {String} downloadUrl
          */
-        downloadUrl_ : null,
+        downloadUrl : null,
 
         /**
          * The URL of the file status reporting service.
          *
+         * This must contain a substitution token named the same as the {@link #property-documentIdParameter}
+         * which is used when creating a URL
+         * 
+         * for example:
+         * 
+         * ```json
+         * {
+         *     documentStatusUrl : '/getDocumentStatus/${documentId}'
+         * }
+         * ```
+         *
          * This widget will use this service after a successful upload to determine its next
          * state.
          *
@@ -188,9 +248,30 @@ class FileUpload extends Base {
          */
         documentStatusUrl : null,
 
+        /**
+         * The polling interval *in milliseconds* to wait between asking the server how the document scan
+         * is proceeding.
+         *
+         * Defaults to 2000ms
+         *
+         * @member {String} documentDeleteUrl
+         */
+        statusScanInterval : 2000,
+
         /**
          * The URL of the file deletion service.
          *
+         * This must contain a substitution token named the same as the {@link #property-documentIdParameter}
+         * which is used when creating a URL
+         * 
+         * for example:
+         * 
+         * ```json
+         * {
+         *     documentDeleteUrl : '/deleteDocument/${documentId}'
+         * }
+         * ```
+         *
          * This widget will use this service after a successful upload to determine its next
          * state.
          *
@@ -200,8 +281,6 @@ class FileUpload extends Base {
          */
         documentDeleteUrl : null,
 
-        headers_ : {},
-
         /**
          * @member {String} state_=null
          */
@@ -215,7 +294,27 @@ class FileUpload extends Base {
         /**
          * @member {String|Number} maxSize
          */
-        maxSize_: null
+        maxSize_: null,
+
+        /**
+         * The error text to show below the widget
+         * @member {String} error
+         */
+        error_ : null,
+
+        // UI strings which can be overridden for other languages
+        documentText         : 'Document',
+        pleaseUseTheseTypes  : 'Please use these file types',
+        fileSizeMoreThan     : 'File size exceeds',
+        documentDeleteError  : 'Document delete service error',
+        isNoLongerAvailable  : 'is no longer available',
+        documentStatusError  : 'Document status service error',
+        uploadFailed         : 'Upload failed',
+        scanning             : 'Scanning',
+        malwareFoundInFile   : 'Malware found in file',
+        pleaseCheck          : 'Please check the file and try again',
+        successfullyUploaded : 'Successfully uploaded',
+        fileWasDeleted       : 'File was deleted'
     }
 
     /**
@@ -232,6 +331,13 @@ class FileUpload extends Base {
         ]);
     }
 
+    /**
+     * @returns {Object}
+     */
+    getInputEl() {
+        return this.vdom.cn[3];
+    }
+
     async clear() {
         const me = this;
 
@@ -246,7 +352,7 @@ class FileUpload extends Base {
 
         // We have to wait for the DOM to have changed, and the input field to be visible
         await new Promise(resolve => setTimeout(resolve, 100));
-        me.focus(me.vdom.cn[3].id);
+        me.focus(me.getInputEl().id);
     }
 
     /**
@@ -265,10 +371,10 @@ class FileUpload extends Base {
                 type     = pointPos > -1 ? file.name.slice(pointPos + 1) : '';
 
             if (me.types && !types[type]) {
-                me.error = `Please use these file types: .${Object.keys(types).join(' .')}`;
+                me.error = `${me.pleaseUseTheseTypes}: .${Object.keys(types).join(' .')}`;
             }
             else if (file.size > me.maxSize) {
-                me.error = `File size exceeds ${String(me._maxSize).toUpperCase()}`;
+                me.error = `${me.fileSizeMoreThan} ${String(me._maxSize).toUpperCase()}`;
             }
             // If it passes the type and maxSize check, upload it
             else {
@@ -288,7 +394,8 @@ class FileUpload extends Base {
             me         = this,
             xhr        = me.xhr = new XMLHttpRequest(),
             { upload } = xhr,
-            fileData   = new FormData();
+            fileData   = new FormData(),
+            headers    = { ...me.headers };
 
         // Show the action button
         me.state = 'starting';
@@ -311,6 +418,22 @@ class FileUpload extends Base {
 
         xhr.open("POST", me.uploadUrl, true);
 
+        /**
+         * This event fires before every HTTP request is sent to the server via any of the configured URLs.
+         * 
+         * @event beforeRequest
+         * @param {Object} event The event
+         * @param {Object} event.headers An object containing the configured {@link #property-headers}
+         * for this widget, into which new headers may be injected.
+         * @returns {Object}
+         */
+        me.fire('beforeRequest', {
+            headers
+        });
+        for (const header in headers) {
+            xhr.setRequestHeader(header, headers[header]);
+        }
+
         xhr.send(fileData);
     }
 
@@ -381,6 +504,10 @@ class FileUpload extends Base {
                 me.abortUpload();
                 break;
 
+            // While processing we just have to wait until it's succeeded or failed..
+            case 'processing':
+                break;
+
             // If the upload or the scan failed, the document will not have been
             // saved, so we just go back to ready state
             case 'upload-failed':
@@ -389,13 +516,17 @@ class FileUpload extends Base {
                 me.state = 'ready';
                 break;
 
-            // During scanning and for stored documents, we need to tell the server the document
+            // For stored documents, we need to tell the server the document
             // is not required.
             case 'processing':
             case 'downloadable':
             case 'not-downloadable':
                 me.deleteDocument();
                 break;
+            case 'deleted':
+                me.clear();
+                me.state = 'ready';
+                break;
         }
     }
 
@@ -404,43 +535,88 @@ class FileUpload extends Base {
     }
 
     async deleteDocument() {
+        const
+            me          = this,
+            { headers } = me;
+
+        me.fire('beforeRequest', {
+            headers
+        });
+
         // We ask the server to delete using our this.documentId
-        const statusResponse = await fetch(`${this.documentDeleteUrl}?${this.documentIdParameter}=${this.documentId}`);
+        const statusResponse = await fetch(me.documentDeleteUrl, {
+            headers
+        });
 
         // Success
         if (String(statusResponse.status).slice(0, 1) === '2') {
-            this.clear();
-            this.state = 'ready';
+            me.clear();
+            me.state = 'ready';
         }
         else {
-            this.error = `Document delete service error: ${statusResponse.statusText}`;
+            me.error = `${me.documentDeleteError}: ${statusResponse.statusText}`;
         }
     }
 
     async checkDocumentStatus() {
-        const me = this;
+        const
+            me          = this,
+            { headers } = me;
 
-        if (this.state === 'processing') {
-            const statusResponse = await fetch(`${this.documentStatusUrl}?${me.documentIdParameter}=${this.documentId}`);
+        if (me.state === 'processing') {
+            me.fire('beforeRequest', {
+                headers
+            });
+
+            const statusResponse = await fetch(me.documentStatusUrl, {
+                headers
+            });
 
             // Success
             if (String(statusResponse.status).slice(0, 1) === '2') {
-                const status = (await statusResponse.json()).status;
+                const 
+                    serverJson   = await statusResponse.json(),
+                    serverStatus = serverJson.status,
+                    // Map the server's states codes to our own status codes
+                    status       = me.documentStatusMap[serverStatus] || serverStatus;
 
                 switch (status) {
                     case 'scanning':
-                        setTimeout(() => me.checkDocumentStatus(), 2000);
+                        setTimeout(() => me.checkDocumentStatus(), me.statusScanInterval);
+                        break;
+                    case 'deleted':
+                        me.error = `${me.documentText} ${me.documentId} ${isNoLongerAvailable}`;
+                        me.state = 'ready';
                         break;
                     default:
+                        const { fileName, size } = serverJson;
+
+                        if (fileName) {
+                            me.vdom.cn[1].cn[0].innerHTML = fileName;
+                            me.fileSize = me.formatSize(size);
+                        }
                         me.state = status;
                 }
             }
             else {
-                this.error = `Document status service error: ${statusResponse.statusText}`;
+                me.error = `${documentStatusError}: ${statusResponse.statusText}`;
             }
         }
     }
 
+    afterSetDocument(document) {
+        if (document) {
+            const
+                me = this;
+
+            me.preExistingDocument = true;
+            me.documentId = document.id;
+            me.fileSize = me.formatSize(document.size);
+            me.vdom.cn[1].cn[0].innerHTML = document.fileName;
+            me.state = me.documentStatusMap[document.status];
+        }
+    }
+
     /**
      * Triggered after the state config got changed
      * @param {String} value
@@ -456,30 +632,40 @@ class FileUpload extends Base {
             anchor  = vdom.cn[1].cn[0],
             status  = vdom.cn[1].cn[1];
 
+        delete vdom.inert;
+
         switch (value) {
             case 'ready':
                 anchor.tag = 'div';
                 anchor.href = '';
                 break;
             case 'upload-failed':
-                status.innerHTML = `Upload failed... (${Math.round(me.progress * 100)}%)`;
+                status.innerHTML = `${me.uploadFailed}... (${Math.round(me.progress * 100)}%)`;
                 break;
             case 'processing':
-                status.innerHTML = `Scanning... (${me.formatSize(me.uploadSize)})`;
+                status.innerHTML = `${me.scanning}... (${me.formatSize(me.uploadSize)})`;
+                vdom.inert = true;
                 break;
             case 'scan-failed':
-                status.innerHTML = `Malware found in file. \u2022 ${me.fileSize}`;
-                me.error = 'Please check the file and try again';
+                status.innerHTML = `${me.malwareFoundInFile}. \u2022 ${me.fileSize}`;
+                me.error = me.pleaseCheck;
                 break;
             case 'downloadable':
                 anchor.tag = 'a';
-                anchor.href = `${me.downloadUrl}?${me.documentIdParameter}=${me.documentId}`;
+                anchor.href = me.createUrl(me.downloadUrl, {
+                    [me.documentIdParameter] : me.documentId
+                });
                 status.innerHTML = me.fileSize;
                 break;
             case 'not-downloadable':
-                status.innerHTML = `Successfully uploaded \u2022 ${me.fileSize}`;
+                status.innerHTML = me.preExistingDocument ?
+                me.fileSize : `${successfullyUploaded} \u2022 ${me.fileSize}`;
+                break;
+            case 'deleted':
+                status.innerHTML = me.fileWasDeleted;
         }
 
+        me.validate();
         me.update();
 
         // Processing above may mutate cls
@@ -490,6 +676,41 @@ class FileUpload extends Base {
         me.cls = cls;
     }
 
+    /**
+     * Creates a URL substituting the passed parameter names in at the places where the name
+     * occurs within `{}` in the pattern.
+     * @param {String} urlPattern 
+     * @param {Object} params 
+     */
+    createUrl(urlPattern, params) {
+        for (const paramName in params) {
+            urlPattern = urlPattern.replace(`{${paramName}}`, params[paramName]);
+        }
+        return urlPattern;
+    }
+
+    beforeGetHeaders(headers) {
+        return { ...(headers || {}) }
+    }
+
+    beforeGetDocumentStatusUrl(documentStatusUrl) {
+        return typeof documentStatusUrl === 'function'? documentStatusUrl.call(me, me) : me.createUrl(documentStatusUrl, {
+            [me.documentIdParameter] : me.documentId
+        });
+    }
+
+    beforeGetDocumentDeleteUrl(documentDeleteUrl) {
+        return typeof documentDeleteUrl === 'function'? documentDeleteUrl.call(me, me) : me.createUrl(documentDeleteUrl, {
+            [me.documentIdParameter] : me.documentId
+        });
+    }
+
+    beforeGetDownloadUrl(downloadUrl) {
+        return typeof downloadUrl === 'function'? downloadUrl.call(me, me) : me.createUrl(downloadUrl, {
+            [me.documentIdParameter] : me.documentId
+        });
+    }
+
     beforeGetMaxSize(maxSize) {
         // Not configured means no limit
         if (maxSize == null) {
@@ -507,21 +728,18 @@ class FileUpload extends Base {
         }
     }
 
-    set error(text) {
-        const { cls } = this;
-
+    afterSetError(text) {
         if (text) {
             this.vdom.cn[4].cn = [{
                 vtype : 'text',
                 html  : text
             }];
-            NeoArray.add(cls, 'neo-invalid');
         }
         else {
-            NeoArray.remove(cls, 'neo-invalid');
+            this.vdom.cn[4].cn = [];
         }
 
-        this.cls = cls;
+        this.validate();
         this.update();
     }
 
@@ -535,6 +753,27 @@ class FileUpload extends Base {
         }
         return 'n/a';
     }
+
+    /**
+     * @returns {Boolean}
+     */
+    validate() {
+        const { isValid, cls } = this;
+
+        NeoArray.toggle(cls, 'neo-invalid', !isValid);
+        this.cls = cls;
+
+        return isValid;
+    }
+
+    get isValid() {
+        const me = this;
+
+        return !me.error &&
+               ((me.state === 'ready' && !me.required) ||
+               (me.state === 'downloadable') ||
+               (me.state === 'not-downloadable'));
+    }
 }
 
 Neo.applyClassConfig(FileUpload);

package/src/form/field/Text.mjs

@@ -665,7 +665,7 @@ class Text extends Base {
 
         me.silentVdomUpdate = true;
 
-        me.validate(false);
+        !me.clean && me.validate(false);
         me.changeInputElKey('required', value ? value : null);
         me.labelText = me.labelText; // apply the optional text if needed