-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME
148 lines (112 loc) · 7.49 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
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
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