Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 353 lines (253 sloc) 15.045 kb
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
1 h1. Introduction
2
4e85ba4c » Captain Future
2010-04-06 added rails 3 development branch note to readme
3 Note that there is a development branch for Rails 3. The Unit Tests pass at least, but it would still need some refactoring.
4
5 <pre>
6 Branch: 3.0-alpha
7 </pre>
8
9 The Master is still for Rails > 2.3.5
10
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
11 <pre>
12 acts_as_category (Version 2.0 alpha)
13 </pre>
607005e6 » Marius Maximus
2009-02-14 README tweaks
14
15 Let me explain to you what I mean by *acts_as_category*, which is yet another acts_as plugin for Ruby on Rails ActiveRecord models. Copyright is 2009 by <a href="http://www.funkensturm.com">www.funkensturm.com</a>, released under the _MIT/X11 license_, which is free for all to do whatever you want with it.
173c34de » Marius Maximus
2008-05-25 first commit
16
390ee8af » Marius Maximus
2009-02-20 readme tweaks
17 h3. acts_as_tree provides functionality for trees, but lacks some things:
fdeb3f4b » Marius Maximus
2009-02-20 readme tweaks
18
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
19 * It has no descendants method or things like @ancestors_ids@
20 * It doesn't validate @parent_id@ whatsoever, which means that you can make a category a parent of itself, etc.
c23aec55 » Commander Keen
2009-12-01 little readme fix
21 * It has no caching for ancestors and descendants (you need that to output trees using @<ul>@ and @<li>@ efficiently)
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
22 * It won't help if you want certain users to see only certain nodes
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
23 * There is no scoping, thus @root.siblings@ will return *all* roots, instead of this users' roots only.
173c34de » Marius Maximus
2008-05-25 first commit
24
390ee8af » Marius Maximus
2009-02-20 readme tweaks
25 h3. acts_as_list is maybe not exactly what I want either:
fdeb3f4b » Marius Maximus
2009-02-20 readme tweaks
26
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
27 * It also has no validation or features to hide particular entries
28 * It doesn't support a script.aculo.us sortable_list to reorder the tree
607005e6 » Marius Maximus
2009-02-14 README tweaks
29 * It has more than you might need, providing all these _move_just_a_little_bit_higher_ methods
30 * Last but not least, it won't work together with _acts_as_tree_ unless you hack around a lot with the scope code
173c34de » Marius Maximus
2008-05-25 first commit
31
390ee8af » Marius Maximus
2009-02-20 readme tweaks
32 h3. So I came up with acts_as_category, and this is what it does:
fdeb3f4b » Marius Maximus
2009-02-20 readme tweaks
33
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
34 * It provides a structure for infinite categories and their subcategories (similar to acts_as_tree)
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
35 * Each user can have his very own set of category trees using the @:scope@ feature
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
36 * It validates that no category will be the parent of its own descendant and all other variations of these foreign key things
37 * You can define which hidden categories should still be permitted to the current user (through a simple class variable, thus it can easily be set per user)
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
38 * There is a variety of instance methods such as @ancestors@, @descendants@, @descendants_ids@, @root?@, etc.
39 * It has view helpers to create menus, select boxes, drag and drop ajax lists, etc. (they need refactorization, though)
40 * It optionally provides sorting by a position column per hierarchy level, including administration methods that take parameters from the helpers
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
41 * There are automatic cache columns for children, ancestors and descendants (good for fast menu output)
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
42 * It is well commented and documented so that Rails beginners will learn from it or easily make changes
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
43 * I18n localization for individual error messages
44 * A full unit test comes along with it
45 * As you can see in the test: All options (e.g. database field names) highly configurable via a simple hash
173c34de » Marius Maximus
2008-05-25 first commit
46
c94d7752 » Marius Maximus
2009-02-20 readme tweaks
47 h3. What can acts_as_category NOT do?
fdeb3f4b » Marius Maximus
2009-02-20 readme tweaks
48
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
49 * You can't simply "turn off" the caching feature to speed up your application. If you really want to make this thing more efficient than it already is, @memoize@ each critical function (it work's fine, since I'm using it myself, but the unit tests will fail whenever I use memoize, that's why it's not published. Update: maybe I should double-check this again, maybe it works by now).
50 * ActiveRecord's "find" method won't respect the hidden categories feature (but a somewhat alternative method called @get@ is provided)
51 * @update@ and @update_attributes@ must not be used to change the parent_id, because there is no validation callback
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
52 * It can't make you a coffee
53
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
54 h3. Demonstration
55
56 Find a out-of-the-box demo application at <a href="http://github.com/funkensturm/funkengallery_demo">www.github.com/funkensturm/funkengallery_demo</a> (note that this demo is using version @1.0@, but you get the idea).
173c34de » Marius Maximus
2008-05-25 first commit
57
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
58 h3. Requirements
173c34de » Marius Maximus
2008-05-25 first commit
59
c47292f0 » Commander Keen
2009-12-03 tweaked the readme real' quick :)
60 * @Rails 2.3.5@ or higher (maybe lower, as well :)
173c34de » Marius Maximus
2008-05-25 first commit
61
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
62 h3. Installation
173c34de » Marius Maximus
2008-05-25 first commit
63
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
64 Just copy the *acts_as_category* directory into @vendor/plugins@ in your Rails application.
173c34de » Marius Maximus
2008-05-25 first commit
65
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
66 To generate *HTML documentation* for all your plugins, run @rake doc:plugins@.
67 To generate it just for this plugin, go to @vendor/plugins/acts_as_category@ and run @rake rdoc@.
173c34de » Marius Maximus
2008-05-25 first commit
68
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
69 To run the *Unit Test* that comes with this plugin, please read the instructions in @vendor/plugins/acts_as_category/test/category_test.rb@.
173c34de » Marius Maximus
2008-05-25 first commit
70
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
71 h1. Documentation
173c34de » Marius Maximus
2008-05-25 first commit
72
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
73 h2. Including acts_as_category in your model
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
74
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
75 First of all you need a database table which looks something like this. Of course you can add arbitrary fields like @name@, @description@, etc.
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
76
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
77 <pre>
78 class CreateCategories < ActiveRecord::Migration
79 def self.up
80 create_table :categories, :force => true do |t|
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
81
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
82 # Needed by acts_as_category
83 t.integer :parent_id, :children_count, :ancestors_count, :descendants_count
84 t.boolean :hidden
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
85
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
86 # Optional
87 t.string :name, :description
88 t.integer :position, :pictures_count
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
89
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
90 end
91 end
92 def self.down
93 drop_table :categories
94 end
95 end
96 </pre>
97
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
98 Notice that the mandatory table names above are needed by default (i.e. @parent_id@, @children_count@, @ancestors_count@, @descendants_count@, @hidden@). To make it work, you need to call @acts_as_category@ in the corresponding ActiveRecord model:
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
99
100 <pre>
101 class Category < ActiveRecord::Base
102 acts_as_category
103 end
104 </pre>
173c34de » Marius Maximus
2008-05-25 first commit
105
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
106 If your database table has different column names, you can modify them. Note that @:position@ and @:order_by@ are optional. Using @:order_by@ you can define any SQL ORDER BY statement. Default is @position@.
173c34de » Marius Maximus
2008-05-25 first commit
107
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
108 <pre>
173c34de » Marius Maximus
2008-05-25 first commit
109 class Category < ActiveRecord::Base
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
110 acts_as_category :foreign_key => 'my_parent_id',
111 :hidden => 'my_hidden',
112 :children_count => 'my_children_count',
113 :ancestors_count => 'my_ancestors_count',
114 :descendants_count => 'my_descendants_count',
115 :position => 'my_position',
116 :order_by => 'title, id ASC'
173c34de » Marius Maximus
2008-05-25 first commit
117 end
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
118 </pre>
173c34de » Marius Maximus
2008-05-25 first commit
119
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
120 You can also have associations with other models. If you have a @belongs_to@ association, you must also provide a @:scope@. The scope can be a table column or even a full SQL condition.
173c34de » Marius Maximus
2008-05-25 first commit
121
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
122 <pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
123 class Catalogue < ActiveRecord::Base
124 has_many :scoped_categories
173c34de » Marius Maximus
2008-05-25 first commit
125 end
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
126 </pre>
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
127
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
128 <pre>
129 class ScopedCategory < ActiveRecord::Base
130 belongs_to :catalogue
131 has_many :pictures, :counter_cache => true
132 acts_as_category :scope => :catalogue
133 end
134 </pre>
135
136 Note that it is assumed that a tree is in the same scope by any means. I.e. @Category.root.first.children@ will *not* respect the scope, but @Category.roots.first.siblings@ will (because the roots may be in different scopes, whereas the children or a category will assumably have the same scope).
173c34de » Marius Maximus
2008-05-25 first commit
137
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
138 h2. Including acts_as_category_content in your model
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
139
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
140 @acts_as_category@ provides a function called @.permitted?@ to find out whether a category is visible according to the current user permissions. However, you might want to have that feature for things that are *inside* your category, say pictures or articles. That way you could individually restrict access to these things. Just tell your content to @acts_as_category_content@ and define the corresponding model (@category@ is default if you leave it out). Like so:
141
142 <pre>
143 class Picture < ActiveRecord::Base
144 acts_as_category_content, :category => 'my_category_model'
145 end
146 </pre>
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
147
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
148 This will also validate the associations. However, it will currently not allow a category content to be in a category which has subcategories. It will be optional in future versions, just uncomment the validation in the @vendor/plugins/acts_as_category/lib/active_record/acts/category_content.rb@ file to change this.
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
149
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
150 h2. Tutorial
173c34de » Marius Maximus
2008-05-25 first commit
151
152 If everything is set up, you can actually use the plugin. Let's say you have trees like this and your model is called *Category*.
153
c23aec55 » Commander Keen
2009-12-01 little readme fix
154 <pre>
173c34de » Marius Maximus
2008-05-25 first commit
155 root1 root2
156 \_ child1 \_ child2
157 \_ subchild1 \subchild3
158 \_ subchild2 \subchild4
c23aec55 » Commander Keen
2009-12-01 little readme fix
159 </pre>
173c34de » Marius Maximus
2008-05-25 first commit
160
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
161 Then you can run the following methods. For more specific information about return values, please look at the HTML documentation generated by RDoc.
173c34de » Marius Maximus
2008-05-25 first commit
162
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
163 <pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
164 Category.get(1) # Returns category with id 1
165 Category.get(1,5) # Returns array of categories with ids 1 and 5
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
166 </pre>
607005e6 » Marius Maximus
2009-02-14 README tweaks
167
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
168 <pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
169 Category.roots # Returns an array with all permitted root categories [root1, root2]
170 Category.roots! # Same thing, but returns roots regardless of permissions (see further below)
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
171 </pre>
173c34de » Marius Maximus
2008-05-25 first commit
172
607005e6 » Marius Maximus
2009-02-14 README tweaks
173 (For the rest let's assume, that root1 = Category.get(1), etc...)
173c34de » Marius Maximus
2008-05-25 first commit
174
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
175 <pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
176 root1.root? # Returns true, because root is a root category
177 child1.root? # Returns false
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
178 </pre>
173c34de » Marius Maximus
2008-05-25 first commit
179
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
180 <pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
181 child1.parent # Returns root
182 root.parent # Returns nil, because root has no parent
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
183 </pre>
607005e6 » Marius Maximus
2009-02-14 README tweaks
184
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
185 <pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
186 root.children # Returns an array with [subchild1, subchild2].
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
187 </pre>
607005e6 » Marius Maximus
2009-02-14 README tweaks
188
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
189 <pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
190 subchild1.ancestors # Returns an array with [child1, root1]
191 subchild1.ancestors_ids # Returns the same array, but ids instead of categories [2,1]
192 root1.ancestors # Returns an empty array [], because root has none
193 </pre>
194
195 <pre>
196 root1.descendants # Returns an array with [child1, subchild1, subchild2]
197 root1.descendants_ids # Returns the same array, but ids instead of categories [2,3,4]
198 subchild1.descendants # Returns an empty array [], because it has none
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
199 </pre>
607005e6 » Marius Maximus
2009-02-14 README tweaks
200
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
201 <pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
202 root1.siblings # Returns an array with all siblings [root2]
203 child1.siblings # Returns an empty array [], because it has no siblings
204 subchild1.self_and_siblings # Returns an array [subchild1, subchild2], just like siblings, only with itself as well
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
205 </pre>
607005e6 » Marius Maximus
2009-02-14 README tweaks
206
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
207 h2. Usage with permissions
173c34de » Marius Maximus
2008-05-25 first commit
208
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
209 Let's bring *permissions* into the game. It let's you show categories for certain users, even though the categories might be flagged "hidden". If a category is hidden, it is practically invisible unless you have permissions.
210
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
211 <pre>
6f286caf » Marius Maximus
2008-10-23 Some major reengineering (especially with permissions)
212 child1.hidden = true
213 subchild1.hidden = true
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
214 </pre>
8d22e8f1 » Marius Maximus
2009-02-14 README tweaks
215
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
216 Sets child1 and subchild1 to be hidden, they are now invisible to everyone
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
217
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
218 <pre>
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
219 root1
8d22e8f1 » Marius Maximus
2009-02-14 README tweaks
220 \_ child1 (hidden)
221 \_ subchild1 (hidden)
222 \_ subchild2 (can't be found either, because child1 is hidden)
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
223 </pre>
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
224
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
225 Your tree will look like this to the world:
226
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
227 <pre>
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
228 root1
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
229 </pre>
607005e6 » Marius Maximus
2009-02-14 README tweaks
230
231 Now we set permissions:
232
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
233 <pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
234 Category.permissions = [2] # i.e. [child1.id]
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
235 </pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
236
237 Say child1 has the id 2. We just allowed the current user to see it though it's hidden. (The idea is to set this class variable array whenever a user logs in).
607005e6 » Marius Maximus
2009-02-14 README tweaks
238
239 Internally this is the structure of the tree:
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
240
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
241 <pre>
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
242 root1
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
243 \_ child1 (still hidden, but you have permissions now)
244 \_ subchild1 (still hidden to you)
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
245 \_ subchild2
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
246 </pre>
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
247
607005e6 » Marius Maximus
2009-02-14 README tweaks
248 If you try to access it, it will look like this:
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
249
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
250 <pre>
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
251 root1
252 \_ child1
253 \_ subchild2
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
254 </pre>
6f286caf » Marius Maximus
2008-10-23 Some major reengineering (especially with permissions)
255
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
256 <pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
257 root1.permitted? # Returns true, because root1 is not hidden
258 child1.permitted? # Returns true, because it's hidden but you have permissions
259 subchild1.permitted? # Returns false, because it inherits "hiddenness" by child1 and you have no explicit rights for subchild1
260 subchild2.permitted? # Returns true, because it's not hidden and you have permissions for child1
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
261 </pre>
607005e6 » Marius Maximus
2009-02-14 README tweaks
262
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
263 Respectively, using acts_as_content you will be able to use the same function on a model which belongs_to a category:
173c34de » Marius Maximus
2008-05-25 first commit
264
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
265 <pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
266 picture_of_child1.permitted? # Returns the same thing as child1.permitted?
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
267 </pre>
173c34de » Marius Maximus
2008-05-25 first commit
268
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
269 Note that you can still use Category.find(1) to override everything and get any category, regardless of it's status. So you should never use it unless you really have to. Here is an alternative method to pick a permitted category directly:
173c34de » Marius Maximus
2008-05-25 first commit
270
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
271 <pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
272 child1.children # Returns only subchild1
273 Category.get(4) # Returns an empty array, trying to access forbidden subchild2
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
274 </pre>
275
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
276 Please have a look at the comments for each function and the unit test to see, which method respects permissions and which one doesn't (e.g. ancestors).
607005e6 » Marius Maximus
2009-02-14 README tweaks
277
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
278 h2. Scopes
279
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
280 If you are using something, which @has_many@ categories, like so:
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
281
282 <pre>
283 class ScopedCategory < ActiveRecord::Base
284 belongs_to :catalogue
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
285 acts_as_category :scope => :catalogue
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
286 end
287 </pre>
288
289 You can easily use @:scope@ to let @acts_as_category@ respect that.
290
291 <pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
292 ScopedCategory.roots.first.siblings # Returns the siblings, which correspond to the same @Catalogue@.
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
293 </pre>
294
295 <pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
296 Catalogue.first.scoped_categories.roots # Can be used to find all visible roots for this user.
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
297 </pre>
298
299 <pre>
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
300 Catalogue.first.scoped_categories.create! # Will create a category root in the scope of that Catalogue.
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
301 </pre>
302
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
303 You get the idea. Please notice, that it is assumed that every tree is in one scope anyway! So @children@ has nothing to do with scope, it simply returns the children.
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
304
305 h2. FAQ
306
8d22e8f1 » Marius Maximus
2009-02-14 README tweaks
307 *Why is _find_ not respecting hidden?*
607005e6 » Marius Maximus
2009-02-14 README tweaks
308
8d22e8f1 » Marius Maximus
2009-02-14 README tweaks
309 I didn't feel comfortable overwriting the find method for Categories and it is not really needed.
173c34de » Marius Maximus
2008-05-25 first commit
310
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
311 *Why are @ancestors@, @ancestors_ids@ and @self.parent@ not respecting hidden/permissions?*
607005e6 » Marius Maximus
2009-02-14 README tweaks
312
8d22e8f1 » Marius Maximus
2009-02-14 README tweaks
313 Because the whole idea of hidden is to exclude descendants of an hidden Category as well, thus the ancestors of a category you can access anyway are never going to be hidden.
173c34de » Marius Maximus
2008-05-25 first commit
314
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
315 h2. Add AJAX positioning for ordering
316
26aab904 » Commander Keen
2009-12-03 tiny readme tweak
317 *WARNING:* This is not tested on scopes yet! If you @has_many :categories@ you might not be able to use this.
abc766a6 » Commander Keen
2009-12-03 Refurnished readme
318
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
319 Let's say you have a gallery and use acts_as_category on your categories. Then the categories will not be ordered by name (unless you want them to), but by a individual order. For this we have the position column. If the @:position@ parameter refers to a non-existent column, this feature is simply disabled.
173c34de » Marius Maximus
2008-05-25 first commit
320
321 You can manually update these positions, but I strongly recommend to let this be done by the sortable_category helper and the Category.update_positions(params) method like so:
322
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
323 In your layout, make sure that you have all the JavaScripts included, that will allow drag and drop with script.aculo.us, etc. For the beginning, let's just add all:
173c34de » Marius Maximus
2008-05-25 first commit
324
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
325 <pre>
173c34de » Marius Maximus
2008-05-25 first commit
326 <%= javascript_include_tag :all %>
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
327 </pre>
173c34de » Marius Maximus
2008-05-25 first commit
328
b894a633 » Marius Maximus
2008-05-25 Minor readme changes
329 Then, in your view, you can call this little helper to generate a drag and drop list where you can re-sort the positions. Remember to provide the name of the model to use:
173c34de » Marius Maximus
2008-05-25 first commit
330
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
331 <pre>
dd316c61 » Marius Maximus
2008-12-28 Added optional memoization (Rails 2.2), repaired unit tests
332 <%= aac_sortable_tree Category %>
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
333 </pre>
173c34de » Marius Maximus
2008-05-25 first commit
334
598c51fe » Marius Maximus
2008-05-25 Minor readme changes
335 Finally, in your controller create an action method like this:
173c34de » Marius Maximus
2008-05-25 first commit
336
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
337 <pre>
598c51fe » Marius Maximus
2008-05-25 Minor readme changes
338 def update_positions
339 Category.update_positions(params)
340 render :nothing => true
341 end
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
342 </pre>
598c51fe » Marius Maximus
2008-05-25 Minor readme changes
343
344 And you can already try it. You can change the URL to that action method like this:
173c34de » Marius Maximus
2008-05-25 first commit
345
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
346 <pre>
dd316c61 » Marius Maximus
2008-12-28 Added optional memoization (Rails 2.2), repaired unit tests
347 <%= aac_sortable_tree(Category, {:action => :update_positions}) %>
348 <%= aac_sortable_tree(Category, {:controller => :mycontroller, :action => :update_positions}) %>
2cf1b738 » Commander Keen
2009-12-01 refactored scope, tests and worked a bit on readme
349 </pre>
173c34de » Marius Maximus
2008-05-25 first commit
350
fdeb3f4b » Marius Maximus
2009-02-20 readme tweaks
351 h2. Ask questions and have fun!
80ab5301 » Marius Maximus
2009-02-14 Updated to version 1.0
352
fdeb3f4b » Marius Maximus
2009-02-20 readme tweaks
353 Feel free to add your comments and don't forget about the <a href="http://github.com/funkensturm/funkengallery_demo">demo application</a>.
Something went wrong with that request. Please try again.