3.7: Edit / Override File names

Fine Uploader version 3.7 brings a brand new feature targeting FineUploader mode: the ability to edit a submitted file or blob’s name. 3.7 brings a new API method for FineUploaderBasic mode users who want to utilize the convention put in place for overriding a filename while providing their own UI. FineUploader mode users get support for this new feature baked into the provided UI. Note that, in both cases, the feature only makes sense when the autoUpload option is set to false. If autoUpload is set to true (the default value), this feature will be disabled in FineUploader mode.

Turning on the edit filename feature in FineUploader mode

In order to enable this feature, you must set the enabled property of the new editFilename option. Also, as stated earlier, the autoUpload option must be set to false. Here’s a very simple example:

$('#myFineuploaderContainer').fineUploader({
    autoUpload: false,
    request: {
        endpoint: 'my/endpoint'
    },
    editFilename: {
        enabled: true
    }
});

Editing a file name

When this feature is properly enabled, you will notice an edit icon next to each submitted file in the UI, assuming the filename is editable at the time. Also, notice the cursor will be set to “pointer” in this case. A filename is editable only while the upload status is SUBMITTED. This means that you may edit your file after submitting it, before calling the uploadStoredFiles API method.

When an editable file name is clicked/touched, a text input will appear. Here, the filename can be changed. Note that the extension is not modifiable. The original extension will always be appended to the filename after the name edit is complete. The extension is not editable to ensure that any validation rules surrounding file type are not violated.

After editing a filename, you have a few options:

  • Press ENTER to save the change.
  • Click or touch some other area on the page to save the change.
  • Hit TAB to edit the name of the next file in the UI (and save the name entered into the current input box).

Note that an empty file name is not an acceptable value. In this case, the original or previously overridden file name will be used instead.

Styling

By default, Fine Uploader places an edit icon next to each editable file name (only) when it is editable. The cursor is changed to a pointer when it is over the file name or the edit icon (only) when the file name is editable. Finally, the file name element is hidden and a text input element is displayed when the file name or edit icon is clicked/touched/focused. The following associated properties have been added to the classes option:

  • editFilenameInput: attached to the text input element
  • editNameIcon: Attached to the element holding the edit icon
  • editable: Attached to the icon or input when the associated file name is editable

The fileTemplate option has changed to allow for these new elements as well. UPDATE: Templating changed drastically in Fine Uploader 4.0. If you are using 4.0, please read the styling documentation page for details.

Things to be aware of

When a file name has been modified, please keep the following in mind:

  • Fine Uploader cannot change the filename listed in the header of the associated file’s multipart boundary. The new file name is sent as a parameter along with the request. See the server-side section below for more details.
  • The getUploads API method can be used to obtain the original file name. All objects returned by this method will now include an originalName property. The name property will be set to the current file name.
  • The getName API method will return the current file name, not the original file name.
  • All name parameters passed to callback handlers will equal the new file name, not the original file name.
  • The resume feature will key on the most current (not necessarily the original) file name when deciding if a submitted file is resumable. This determination is made by Fine Uploader just before the first upload request for the file request is sent. If you submit a previously interrupted file with an overridden name, you must ensure the file name is again changed to ensure the file is properly resumed.

Handling an overridden / new file name server-side

If a file name has been edited / overridden client-side, a “qqfilename” parameter with the new file name will be included with the upload request. If you see this parameter in the request, you should use the associated value when naming your file and not the value of the filename parameter of the Content-Disposition header associated with the file’s multipart boundary. Note that the “qqfilename” parameter is named by default, but is also tied to the new filenameParam property of the request option. This change is associated with some other breaking changes. See the breaking changes section below for more details.

Breaking changes

All breaking changes are related to cleanup of filename-related parameters passed along with the requests. These breaking changes don’t represent a complete cleanup of this mess, but this gets most of the job done.
All breaking changes are related to cleanup of filename-related parameters passed along with the requests. These breaking changes don’t represent a complete cleanup of this mess, but this gets most of the job done.

  • The name property of the blobs.paramNames option has been removed. The new filenameParam property of the request option replaces this.
  • The fileName property of the chunking.paramsNames option has been removed. The new filenameParam property of the request option replaces this.