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 [email protected]: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

  
2)  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    

4)  ADD ROUTE to config/routes.rb
  map.resources :documents
    
5)  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