File: README — Documentation for list_cloud

ListCloudFiles

ListCloudFiles is a really simple gem to help you show the contents of an Amazon S3 bucket in a view in your Rails app. It uses a simple _metadata.txt file inside your bucket (that you create) to provide friendly descriptions for each of the files in your bucket.

Configuration and usage is pretty simple. See below for example usage and sample Haml/Sass code, too.

Example Usage

Instructions for using ListCloudFiles:

Set up a bucket on Amazon S3 to hold your files. Make sure they’re all publicly readable. If you’d like to include description metadata for each of your files in the bucket, create a new file in the bucket called _metadata.txt. Format _metadata.txt like this:

<code>

Some_file_name.txt|This is a description about some file.
Another_file.txt|Here's a description about another file.

</code>

Anything after the pipe character on this line counts as a description.  Anything before the pipe character is the file name key we'll use to look up this description based on a matching filename in the bucket, so make sure it matches.

Create config/initializers/list_cloud_files.rb with: ListCloudFiles.aws_access_key_id = ‘your_amazon_aws_access_key’ ListCloudFiles.aws_secret_access_key = ‘your_amazon_aws_secret_access_key’

# this controls how often the cache of the s3 bucket’s file contents will be cleared ListCloudFiles.cache_expires_in = 1.day

Call ListCloudFiles.get_files_for_bucket(‘your-bucket-name’) in your controller. You’d probably do something like:

<code>

@cloud_files = ListCloudFiles.get_files_for_bucket('my-bucket-name')

</code>

ListCloudFiles.get_files_for_bucket(‘your-bucket-name’) returns a hash with:

:file_names    # an array of strings for each file in your bucket
:file_metadata # a hash of metadata keyed on each file_name from the file_names key above

Each hash vlaue in the :file_metadata contains these keys:

:pretty_name  # the name of the file without the extension
:extension    # the file's extension
:description  # a description taken from parsing the _metadata.txt file (see below)
:public_url   # the public url for the file, assuming it has public read access

Use the result of ListCloudFiles.get_files_for_bucket in your view to show the data. Assuming you set @cloud_files = ListCloudFiles.get_files_for_bucket(‘my-bucket-name’), and assuming you’re using Haml, you’d probably do something like the following.

Note: this example code assumes that you have file images to match each file extension in public/images/list_cloud_files/filetypes/<extension>.png

<code>

- @file_metadata = @cloud_files[:file_metadata]
%ul.cloud_files
  - @cloud_files[:file_names].each do |file_name|
    - file_metadata = @file_metadata[file_name]
    %li.file{ :class => file_metadata[:extension] }
      %a{:href => file_metadata[:public_url]}
        %img.file_icon{:src => "/images/list_cloud_files/filetypes/#{file_metadata[:extension]}.png", :alt => @file_metadata[file_name][:extension]}
      %span.file_name
        %a{:href => file_metadata[:public_url]}
          = file_metadata[:pretty_name]
      %span.file_description
        %a{:href => file_metadata[:public_url]}
          = file_metadata[:description]

</code>

Stlye the HTML output so it doesn’t look like total crap. Here’re some example Sass styles:

<code>

ul.cloud_files
  :list-style-type none
  :margin 0
  :padding 0 
  li.file
    :padding 0 
    :margin-bottom 20px
    a
      :color inherit
      :text-decoration none
    img.file_icon
      :width 50px
      :margin 0 10px 0 0 
      :float left
    span.file_name
      :font-weight bold
      :font-size 24px
      :display block
      :padding-top 24px
      :font-weight bold
      a
        :text-decoration underline
    span.file_description
      :display block
      :clear both
      :font-weight normal

</code>