Attachments API

Overview

Attachments have been completely reworked to use Paperclip (https://github.com/thoughtbot/paperclip) in BrowserCMS 3.5

• Each block can now have multiple attachments using to different styles.
• Attachments can be defined as one to one (has_attachment :image) or be stored as a collection (has_many_attachments).
• Upgrade migrations are provide to migrate file and data for older projects to the new attachment structure.
• New generators have been provided to create content blocks with the new attachment styles.

1. Single Attachments

To create a block with a single named attachment, you can do the following:

$ rails g cms:content_block Product photo:attachment

This will generate a model that looks like this:

class Product < ActiveRecord::Base
  acts_as_content_block
  has_attachment :photo
end

The has_attachment method defines a single attachment in one to one relationship with this content block. When you edit this model, you will have a single 'file upload' field to associate it.

1a. Multiple named attachments

You can also define more than one named attachment like so:

$ rails g cms:content_block Product photo_1:attachment photo_2:attachment

which will generate a model like:

class Product < ActiveRecord::Base
  acts_as_content_block
  has_attachment :photo_1
  has_attachment :photo_2
end

1b. Configuring the editor

In the generated _form.html.erb you can customize whether or not users can select a path or section to place the file in. You can do this by specifying the following:

<%= f.cms_text_field :name %>
<%= f.cms_file_field :photo, :label => "Photo", edit_path: true, edit_section: true %>

By setting :edit_path and :edit_section to true, the CMS will display widgets for selecting a section and a creating a custom path for the file to be accessed from.

2. Multiple Attachments

To define a model with multiple attachments, use the following generator:

$ rails g cms:content_block Catalog photos:attachments

This will create a model that looks like this:

class Catalog < ActiveRecord::Base
  acts_as_content_block
  has_many_attachments :photos
end

The 'has_many_attachments' will use a new AJAX based widget that allows users to upload/delete multiple files when creating or editing files.

3. Paperclip Configuration

The has_attachment and has_many_attachments are designed to provide the exact same configuration as using has_attached_file that Paperclip provides. The main advantage of this is that in the CMS, attachments are handled as separate models, which have their own security and versioning through the UI.

For example, to define a thumbnail, you can do the following:

class Product < ActiveRecord::Base
  acts_as_content_block
  has_attachment :photo, :styles => {:thumbnail => "224x200#", :mini => "90x80#"}
end

For now, only the :styles option is supported, see the Paperclip documentation for documentation on how styles work.