willcode2surf / emberdroplet

Ember.js HTML5 file uploading with drag & drop and image/file preview.

Ember Droplet

 

Install via npm: npm install ember-droplet.

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.

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 exposes the following public methods:

• 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 – returns a jQuery promise;

In addition to the methods, 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);

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 8888.

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.

Testing

All of the related tests are written in Jasmine, and can be run with grunt test (assuming you have grunt installed – npm install grunt -g). You'll also need to run npm install to install the project's dependencies.