Upload - upgrading from 1.4

One of the new features of Editor 1.5 is that the upload and uploadMany field types have been introduced to the core software. This replaces the previous upload plug-in field type that was available from Editor 1.4.1 (there was no equivalent of the uploadMany field type).

This document details the changes that have been made and how you can update your software to use the new field type.

What has changed?

Two aspects of Editor's upload action have changed:

1. The display function of the field type is no longer given a second parameter.
2. display is no longer executed if the field has no value

Why the change?

The changes made were primarily to increase the flexibility of the software (to add the uploadMany field type) and also to clarify for developers how information about files can be retrieved.

Previously the upload plug-in depended upon obtaining additional information about files (for example a file name, web path, etc) by a join to a database table that contained this meta information about files. That proved to be quite brittle (the information passed to the display function as the second parameter sometimes could include a full row's data, and at other times just a limited sub-set about the file) and also quite confusing to developers just starting out with Editor.

The changes made mean that the meta information about files is now available through the file() API method that Editor attaches to DataTables. The meta information available is automatically populated by how the db() method has been configured in the Upload class instance on the server-side.

What do I need to do?

1. Remove the upload field plug-in from your code (JS and CSS) so the built in field type will be used
2. Update your display method to use the new file() method
3. Update the Editor upload definition to use the noFileText option, defining what will be shown if the input has no value.
4. Update your DataTables columns.render method that displays information about the file (if you have one, this is not required) to also use file().

The above principles are demonstrated in the following example:

fields: [
    {
        label:   'Image:',
        name:    'image.id',
        type:    'upload',
        display: function ( imageId, row ) {
            return imageId && row.image.webPath ?
                '<img src="'+row.image.webPath+'"/>' :
                'No image';
        },
    },
    ...
]

columns: [
    {
        data:   'image',
        render: function ( image ) {
            return image.webPath ?
                '<img src="'+image.webPath+'"/>' :
                null;
        },
        defaultContent: 'No image'
    },
    ...
]

fields: [
    {
        label:      'Image:',
        name:       'image.id',
        type:       'upload',
        noFileText: 'No image',
        display:    function ( imageId ) {
            return '<img src="'+table.file( 'uploads', imageId ).webPath+'"/>';
        },
    },
    ...
]

columns: [
    {
        data:   'image.id',
        render: function ( imageId ) {
            return imageId ?
                '<img src="'+table.file( 'uploads', imageId ).webPath+'"/>' :
                null;
        },
        defaultContent: 'No image'
    },
    ...
]

No change is required on the server-side.

Where can I read more?

As the upload and uploadMany field types are now integrated into the Editor core software, they are also documented as such. Documentation about file uploading with Editor can be found in the following locations:

• Client-side manual - includes an overview for uploads with Editor
• Server-side manual - PHP and .NET
• upload and uploadMany field types
• file() and files() DataTables API methods