Home

Awesome

attache-rails

Gem Version Build Status

Ruby on Rails / ActiveRecord integration for attache server using attache/api

Dependencies

React, jQuery, Bootstrap 3

Installation

WARNING: Please see upgrade notes below if you are upgrading from V2

Install the attache-rails package from Rubygems:

gem install attache-rails

Or add this to your Gemfile

gem "attache-rails"

Add the attache javascript to your application.js

//= require attache

Using its components alone

If you prefer to skip automatic upgrading of input[type=file], you can wield the components yourself

//= require attache/cors_upload
//= require attache/bootstrap3
//= require attache/file_input

attache_cors_upload.CORSUpload
attache_bootstrap3.Bootstrap3FilePreview
attache_bootstrap3.Bootstrap3Header
attache_bootstrap3.Bootstrap3Placeholder

Customize UI

If you want to customize the file upload look and feel, define your own React <AttacheFilePreview/>, <AttacheHeader/>, <AttachePlaceholder/> renderer before including the attache js. For example,

//= require ./my_attache_file_preview.js
//= require attache

The attache_file_input.AttacheFileInput idempotent function is setup to find all the elements with enable-attache css class and upgrade them to use the direct upload & preview javascript. If you wish to re-run this function any other time, e.g. hookup the cocoon:after-insert event, you may

$(document).on('cocoon:after-insert', attache_file_input.AttacheFileInput);

Usage

Database

To use attache, you only need to store the JSON attributes given to you after you've uploaded a file. So if you have an existing model, you only need to add a text column (PostgreSQL users see below)

rails generate migration AddPhotoPathToUsers photo:text

To assign multiple images to one model, the same column can be used, although pluralized column name reads better

rails generate migration AddPhotoPathToUsers photos:text

Model

In your model, define whether it has_one_attache or has_many_attaches

class User < ActiveRecord::Base
  has_many_attaches :photos
end

New or Edit form

In your form, you would add some options to file_field using the attache_options helper method:

= f.file_field :photos, f.object.photos_options('64x64#')

If you were using has_many_attaches the file input will automatically allow multiple files, otherwise the file input will only accept 1 file.

NOTE: 64x64# is just an example, you should define a suitable geometry for your form

Strong Parameters

You'd need to permit the new field in your controller. For example, a strong parameters definition may look like this in your Users controller

def user_params
  params.require(:user).permit(:name)
end

If you're only accepting a single file upload, change it to

def user_params
  params.require(:user).permit(:name, :photo, attaches_discarded: [])
end

If you're accepting multiple file uploads, change it to

def user_params
  params.require(:user).permit(:name, photos: [], attaches_discarded: [])
end

NOTE: You do not have to manage params[:attaches_discarded] yourself. It is automatically managed for you between the frontend javascript and the ActiveRecord integration: files that are discarded will be removed from the attache server when you update or destroy your model.

Show

Use the *_url or *_urls methods (depending on whether you are accepting multiple files) to obtain full urls.

= image_tag @user.photo_url('100x100#')

or

- @user.photos_urls('200x200#').each do |url|
  = image_tag url

Environment configs

ATTACHE_URL points to the attache server. e.g. http://localhost:9292

ATTACHE_UPLOAD_DURATION refers to the number of seconds before a signed upload request is considered expired, e.g. 600

ATTACHE_SECRET_KEY is the shared secret with the attache server. e.g. t0psecr3t

PostgreSQL

Take advantage of the json support by using the json or jsonb column types instead

rails generate migration AddPhotoPathToUsers photo:json

This opens up the possibility to query inside the column, e.g.

User.where("photo ->> 'content_type' = ?", 'image/png')

License

MIT