Working with upload

Let's see how to upload files or images using the plugin. Here is the complete code:

(function($R)
{
    $R.add('plugin', 'myplugin', {
        modals: {
            'mymodal': '<form action="">'
                + '<div class="form-item">'
                    + '<input type="file" name="file">'
                + '</div>'
            + '</form>'
        },
        translations: {
            en: {
                "myplugin": "My Plugin"
            }
        },
        init: function(app)
        {
            // define app
            this.app = app;

            // define services
            this.lang = app.lang;
            this.toolbar = app.toolbar;
        },

        // messages
        onmodal: {
            mymodal: {
                open: function($modal, $form)
                {
                    this._setUpload($form);
                }
            },
        },
        onupload: {
            myupload: {
               complete: function(response)
                {
                    this._insert(response);
                },
                error: function(response)
                {
                    this._uploadError(response);
                }
            }
        },

        // public
        start: function()
        {
            // create the button data
            var buttonData = {
                title: this.lang.get('myplugin'),
                api: 'plugin.myplugin.open'
            };

            // create the button
            var $button = this.toolbar.addButton('myplugin', buttonData);
        },
        open: function()
        {
            var options = {
                title: this.lang.get('myplugin'),
                name: 'mymodal',
                commands: {
                    cancel: { title: this.lang.get('cancel') }
                }
            };

            this.app.api('module.modal.build', options);
        },

        // private
        _setUpload: function($form)
        {
            var options = {
                url: '/my-upload-server-side/',
                element: $form.getField('file'),
                name: 'myupload'
            };

            this.app.api('module.upload.build', options);
        },
        _uploadError: function(response)
        {
            this.app.broadcast('myuploadError', response);
        },
        _insert: function(response)
        {
            this.app.api('module.modal.close');
            this.app.broadcast('myuploadComplete', response);
        }
    });
})(Redactor);

Build upload #

You can see how the upload is built for the form field in the _setUpload method. The method calls the API module.upload.build and specifying the upload options.

var options = {
    url: '/my-upload-server-side/',
    element: document.getElementById('#my-id'),
    name: 'myupload'
};

this.app.api('module.upload.build', options);

The options:

  • name String
    • the upload variable
  • url String
    • the path to the server-side script that will handle the upload
  • element Node, Dom
    • element on the base of which the upload will be built (an area will be created for the drag and drop file or by clicking on the area it will be possible to select a file from the disk)

The element option is any node on the page, or you can use the Modal Form API and specify an element from the form of the modal window:

_setUpload: function($form)
{
    var options = {
        url: '/my-upload-server-side/',
        element: $form.getField('file'),
        name: 'myupload'
    };

    this.app.api('module.upload.build', options);
}

Callbacks/messages #

Upload calls one of the two complete or error callbacks after uploading the file. Each of these callbacks is tied to upload by the variable name, which we specified in the upload options, in our case it is myupload:

onupload: {
    myupload: {
        complete: function(response)
        {
        },
        error: function(response)
        {
        }
    }
}

You can specify JSON in your server-side script if an error occurred:

{
    "error": true,
    "message": "Something went wrong..."
}

In this case, the error callback will be triggerd and the server-side script sent JSON to the callback as the argument response.

If the upload is successful, the callback complete will be triggered, and the JSON object that you generated on the server-side is passed as the argument response.

Catching drag and drop for upload #

You can listen to the messages dropimage or dropfile to catch the images or files dropped to Redactor.

To do this, specify the catching of messages in the plugin, for images:

ondropimage: function(e, files, clipboard)
{
    var options = {
        url: '/my-upload-server-side/',
        event: (clipboard) ? false : e,
        files: files,
        name: 'imagedrop'
    };

    this.app.api('module.upload.send', options);
}

For files:

ondropfile: function(e, files, clipboard)
{
    var options = {
        url: '/my-upload-server-side/',
        event: (clipboard) ? false : e,
        files: files,
        name: 'filedrop'
    };

    this.app.api('module.upload.send', options);
}

Then listen the upload messages like this:

onupload: {
    imagedrop: {
        complete: function(response, e)
        {
        },
        error: function(response)
        {
        }
    },
    filedrop: {
        complete: function(response, e)
        {
        },
        error: function(response)
        {
        }
    }
}

The complete example with inserting file or image to the dropped point.

(function($R)
{
    $R.add('plugin', 'myplugin', {
        init: function(app)
        {
            // define app
            this.app = app;

            // define services
            this.insertion = app.insertion;
        },

        // messages
        ondropimage: function(e, files, clipboard)
        {
            var options = {
                url: '/my-upload-server-side/',
                event: (clipboard) ? false : e,
                files: files,
                name: 'imagedrop'
            };

            this.app.api('module.upload.send', options);
        },
        ondropfile: function(e, files, clipboard)
        {
            var options = {
                url: '/my-upload-server-side/',
                event: (clipboard) ? false : e,
                files: files,
                name: 'filedrop'
            };

            this.app.api('module.upload.send', options);
        },
        onupload: {
            imagedrop: {
                complete: function(response, e)
                {
                    this._insert(response, e);
                },
                error: function(response)
                {
                    this._uploadError(response);
                }
            },
            filedrop: {
                complete: function(response, e)
                {
                    this._insert(response, e);
                },
                error: function(response)
                {
                    this._uploadError(response);
                }
            }
        },

        // private
        _insert: function(response, e)
        {
            this.insertion.insertToPoint(e, '<p>Some HTML</p>')
        },
        _uploadError: function(response)
        {
            this.app.broadcast('mypluginUploadError', response);
        }
    });
})(Redactor);