Skip to content

Latest commit

 

History

History
130 lines (90 loc) · 5.79 KB

0.10.0.md

File metadata and controls

130 lines (90 loc) · 5.79 KB
Raw

Ember Droplet

NOTE: This documentation relates to v0.10.0.

Build Status   NPM version

Heroku: http://ember-droplet.herokuapp.com/

Install via npm: npm install ember-droplet.

See this comment for installing for Ember CLI.

Ember Droplet allows HTML5 drag and drop functionality in Ember straight out-of-the-box. Its philosophy is that it doesn't impose anything, and instead allows each individual developer to decide how it should work. I've provided a view – DropletView that you're free to use in your views. However, most of the functionality exists in the controller mixin – DropletController).

For the time being, please refer to the example.

EmberDroplet Screenshot

Features

  • Upload with HTML5's drag and drop;
  • MIME type restrictions on permitted file types;
  • Instant image previews upon dropping;
  • Specifies extension in class name to allow for icons for different file types;
  • Allows the deletion of files before they're uploaded;
  • Keeps a track of all files – even invalid files;

Methods

The DropletController contains the following actions:

  • addValidFile – Adds a file that is allowed by its MIME type;
  • addInvalidFile – Same as above, but a file that isn't allowed by its MIME type;
  • deleteFile – Deletes a specified file by its object;
  • clearAllFiles – Clears all files, including uploaded files;
  • uploadAllFiles – Uploads all valid files;

In addition to the actions, DropletController also has the following computed properties for convenience:

  • validFiles – Provides a list of valid files;
  • invalidFiles – Provides a list of invalid files;
  • uploadedFiles – All uploaded files;
  • deletedFiles – All deleted files;

Additional computed properties can be added to your controller that implements the mixin. To add additional computed properties, please refer to the protected _filesByProperties method in the mixin.

Getting Started

In order to begin using EmberDroplet, you need a controller. Within your controller you can implement the DropletController mixin, which will give you access to all methods defined in it.

App.IndexController = Ember.Controller.extend(DropletController, {

});

Properties that can be defined in your controller to interact with the mixin are as follows:

  • dropletUrl: URL in which the Node.js (default) or Apache/Nginx server is running on;
  • mimeTypes: Enumeration of valid MIME types. Can be appended using concatenatedProperties (see example);
  • dropletOptions.useArray: Defaults to true, which works for Ruby/PHP scripts where you need to specify an array-like name for the field (file[]). Set to false to use the field name file instead;
  • dropletOptions.fileSizeHeader: Defaults to true. Set to false to omit the X-File-Size http header;
  • dropletOptions.method: Defaults to post, but can be set to put if needed;
  • didUploadFiles: Function which will be called if files were uploaded successfully, with the server response as the argument;

Now that your controller is using the mixin, it's time for your view to interact with your controller and its related mixin. For this we recommend using the in-built view, but it's not essential. In order to create your own, please refer to the example. The simplest way to use the in-built view is to embed it into your template.

App.IndexView = Ember.View.extend({

    /**
     * @property DragDrop
     * @type DropletView
     */
    DragDrop: DropletView.extend()

});

Once you have the property DragDrop defined, the view and all of its related functionality can be output into the DOM using {{view.DragDrop}}. It's worth bearing in mind that this view is quite abstract in order to be customisable – see index.html for an example.

Example

The example uses the Node.js server to upload files, which is available in example/node-server. Simply run: node server to create it.

Vagrant

As an alternative, if you have Vagrant installed then you can simply issue the vagrant up command and the Node.js server will be available on port 8889.

View Mixin

In order to use EmberDroplet it's not necessary for you to implement the DropletView mixin into your view. However, if you don't, then you'll need to communicate with the DropletController mixin yourself.

There is also DropletPreview which allows image uploads to be previewed immediately.

Handling Errors

If you need to handle upload errors in your controller, you can observe changes to the uploadStatus.error property. Here is an example function which would be placed in your controller:

onFileUploadError: function () {
    // `uploadStatus.error` contains `false` if there are no errors, `true` if
    // there was a network error, and the arguments passed to jqXHR.fail wrapped
    // in an object - { jqXHR, textStatus, errorThrown }
    var error = this.get('uploadStatus.error');
    if (error) {
        console.error(error.jqXHR.responseText);
        alert('An error occurred uploading the file');
    }
}.observes('uploadStatus.error'),

Testing

All of the related tests are written in Jasmine, and can be run with npm test. You'll also need to run npm install to install the project's dependencies.

Jasmine