README

S3Storage
=========

This is an alpha-release. Use at your own risk.

This plugin is created for the Ruby on Rails framework and makes it really simple to 
use Amazon S3 for storing your uploaded files. 

You will need an account with Amazon Web Services http://aws.amazon.com/ 

Installation
============
Install the Amazon gem first

  sudo gem install aws-s3

Then you can install the plugin itself:

  ruby ./script/plugin install git://github.com/standout/s3storage.git

If you get a 'Not found' message, you probably don't have the latest version of 
rails. You could grab the plugin manually from http://github.com/standout/s3storage/tarball/master
and extract it into your vendor/plugins folder. 

Your model needs to have the following fields for this to work.

  - original_filename
  - content_type


Usage
=======

The plugin will create your bucket automatically if it does not already exist. 
Remember that bucket names must be unique across all of S3. I usually get around this
by setting the bucket name to a domain name.

I'll show some example code for a model called Document.

Scaffold (command line):
ruby ./script/generate scaffold Document title:string, original_filename:string, content_type:string
rake db:migrate

Model (app/models/document.rb):
class Document < ActiveRecord::Base
  s3_storage  :bucket => 'YOUR_BUCKET_NAME',
              :access_key => 'YOUR_ACCESS_KEY',
              :secret => 'YOUR_SECRET_KEY'
end

New document (app/views/document/new.html.erb):
In your view, you'll need to have a form for uploading.
<% form_for(@document, :html => {:multipart => true}) do |f| %>
  <p>
    <label for="document_title">Title</label><br />
    <%= f.text_field :title %>
  </p>
  <p>
    <label for="document_file">Select a file to upload</label><br />
    <%= f.file_field :file %>
  </p>
  <%= submit_tag "Upload file" %>
<% end %>

List of documents (app/views/document/index.html.erb):
<ul>
<% for document in @documents %
  <li>
    <%= link_to document.title, document.s3_path %>
  </li>
<% end %>
</ul>

That's it. Your uploaded files will now be stored in your Amazon S3 bucket.
Files will be deleted from Amazon S3 when you delete the object as usual in rails.

-------
Copyright (c) 2008 David Svensson http://www.standout.se/, released under the MIT license