Fileman

Requirements:

IMPORTANT: You will need the following plugins...

• haml - http://haml.hamptoncatlin.com/download/ (Note: the edge versions of Haml seem to be problematic with some of the Rails visual_effects - I am using an older stable version)
• attachment_fu - http://svn.techno-weenie.net/projects/plugins/attachment_fu/
• responds_to_parent - http://responds-to-parent.googlecode.com/svn/trunk/

Optional Plugin... - acts_as_iconic - git clone git@github.com:bilson/acts_as_iconic.git This plugin will allow your models to automatically show an icon beside the uploaded file that corresponds with that file's mime_type

---

SETUP a FILEMAN

1. GENERATOR: Run generator script/generate fileman model_name

As an example we will use "Document" as the model name

script/generate fileman Document ...

create app/views/fileman create app/views/fileman/_form.haml create app/views/fileman/_list_item.haml create app/views/fileman/_add_facility.haml create app/views/documents create app/views/documents/index.haml create app/models/document.rb create app/controllers/documents_controller.rb exists db/migrate create db/migrate/012_create_documents.rb

1. PREPARATION: You now need to decide whether this attachment_fu object will be owned by another object and, if so, if that relationship will be polymorphic.

OPTION 1 - Document is not owned

You might be ready to just skip this step and move on, but take a look at the migration just to make sure.
db/migrate/00?_create_documents.rb
  - add any custom fields - you will be able to fill these in automatically

OPTION 2 - Document has a single owner...

app/models/document.rb...
  Uncomment and change "whatever" to whatever the object is that owns this document
  Let's say it is a specific User that owns this document
    # for single ownership associations
    belongs_to :user
db/migrate/00?_create_documents.rb
  Do the same for the migration
    # Uncomment for and change to appropriate owning object type for Single Ownership Relationships
    t.integer :user_id
    - add any custom fields - you will be able to fill these in automatically
app/models/user.rb... (example)
  Add the appropriate has_many or has_one declaration in the object that owns these documents...
  has_many :documents, :dependent => :destroy

OPTION 3 - Document is owned by any object (polymorphic)

app/models/document.rb...
  Uncomment the polymorphic belongs_to association
  As a default the generator will set this to the model name + "able"
  This may or may not be to your liking so feel free to manually change it
    # for polymorphic associations
    belongs_to :documentable, :polymorphic => true
db/migrate/00?_create_documents.rb
  Do the same for the migration
    # Uncomment for Polymorphic Relationships
    # t.integer :documentable_id
    # t.string  :documentable_type
  - add any custom fields - you will be able to fill these in automatically
app/models/user.rb... (example)
  Add the appropriate has_many or has_one declaration any objects that own these documents...
  has_many :documents, :as => :documentable, :dependent => :destroy

3) RUN MIGRATION - run the migration

1. ADD ROUTE to config/routes.rb map.resources :documents

2. IMPORTANT: add javascript_include_tag :defaults to your layout...unless you don't mind the plugin being completely useless

---

USAGE in the VIEW

Most of the action will happen in the fileman_helper and views/fileman/ partials

Note that there will be an example fileman facility automatically created for the "Document" model that we have created. This will be in views/documents/index.haml

This is the simplest implementation of the fileman helper and consists of...

= fileman 'Document'

This will display a facility to add new documents and also show those documents in a list. Of course, in most cases you will be using this within a different view.

There are a number of options to change what functionality and relationships are displayed.

OPTIONS:

:with_delete => true || false -- display the delete link?
:with_update => true || false -- display the update link?

:facility => :all (default) || :list || :add -- ability to separate out facilities
  fileman 'Document' -- will display both the list and add facilities
  fileman 'Document', :facility => :list -- only the list facility
  fileman 'Document', :facility => :add
  This allows you to separate the :add and :list facilities to different parts of the page.
  Note: The :list must always be present somewhere or it will throw an error upon upload.  Also, make sure that all appropriate options are set on both fileman facilities.

:polymorphic => true || false (default is false)
:polymorphic_name => example: 'attachable', 'phonable', 'edible' 
  - _id and _type will automatically be added to this name
  - default is resource name + able => ex. attachment would become attachmentable
:belongs_to => object that owns this resource (if there is an owner)

:with_display_name => true || false (default is true)
:with_caption => true || false (default is false)
  There are display name and caption fields automatically created for you.
:with_icon => true || false - for acts_as_iconic plugin (defaults to false)
:with_link => true || false - show or hide the filename/linkname and link (defaults to true)

:with_image => true || false - if this is an image model you can show the image (default is false)
:image_size => 'thumbnail_size' - specify a thumbnail name (defaults to full size)

:add_browse_visible => true || false - keeps the add facility file browser open at all times (defaults to false)

:extras => {} - add any custom field name that exists in your model
  Example: :extras => { :author_name => 'somebody', :pi => 3.14 }
  These will be added in the appropriate field of your table when the record is created

:find => option to add a custom find query for the file list - If ownership is set with :belongs_to, then the query will be scoped
  Examples: fileman 'Document', :belongs_to => @some_object, :find => 'find_all_by_usage("accounting")' -- returns a list of all Documents belonging to @some_object that have a usage of "accounting"
            fileman 'Document', :belongs_to => @some_object, :polymorphic => true, :find => 'find_all_by_usage("accounting") -- same as above except recognizes the polymorphic relationship
  Note: This currently only updates with a page refresh
  
            
:association => :has_one || :has_many (default is :has_many) - 
  This option sets whether fileman will accomodate single or multiple uploads - setting to :has_one will initially show an open file browser.  Upon uploading, the file browser will disappear.  If the file is deleted, the browser will once again show.  Setting to :has_many will default the file browser to hidden, but with an "add" button that will make the browser appear.  With each upload, the browser will again fade out.  This visibility can be overriden by setting :add_browse_visible to true.  Note that this MUST correspond with your association declaration in your model file.

Copyright (c) 2008 David Baldwin, released under the MIT license