Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 224 lines (148 sloc) 6.987 kB
949894e @obrie Integrate Travis CI
obrie authored
1 == preferences http://travis-ci.org/pluginaweek/preferences.png
497920d @obrie Removed install.rb files.
obrie authored
2
ffcf63d @obrie Rename to preferences
obrie authored
3 +preferences+ adds support for easily creating custom preferences for models.
497920d @obrie Removed install.rb files.
obrie authored
4
5 == Resources
6
5a4a7b9 @obrie Add API link
obrie authored
7 API
497920d @obrie Removed install.rb files.
obrie authored
8
feb10bb @obrie Fix docs not getting referenced properly
obrie authored
9 * http://rdoc.info/github/pluginaweek/preferences/master/frames
497920d @obrie Removed install.rb files.
obrie authored
10
78efc83 @obrie Update list of plugin resources to GitHub/Lighthouse
obrie authored
11 Bugs
12
d206832 @obrie Use GitHub instead of Lighthouse for issue tracking
obrie authored
13 * http://github.com/pluginaweek/preferences/issues
78efc83 @obrie Update list of plugin resources to GitHub/Lighthouse
obrie authored
14
497920d @obrie Removed install.rb files.
obrie authored
15 Development
16
78efc83 @obrie Update list of plugin resources to GitHub/Lighthouse
obrie authored
17 * http://github.com/pluginaweek/preferences
497920d @obrie Removed install.rb files.
obrie authored
18
949894e @obrie Integrate Travis CI
obrie authored
19 Testing
20
21 * http://travis-ci.org/pluginaweek/preferences
22
5a4a7b9 @obrie Add API link
obrie authored
23 Source
24
78efc83 @obrie Update list of plugin resources to GitHub/Lighthouse
obrie authored
25 * git://github.com/pluginaweek/preferences.git
5a4a7b9 @obrie Add API link
obrie authored
26
7b5d939 @obrie Add link to mailing list in README
obrie authored
27 Mailing List
28
29 * http://groups.google.com/group/pluginaweek-talk
30
497920d @obrie Removed install.rb files.
obrie authored
31 == Description
32
ffcf63d @obrie Rename to preferences
obrie authored
33 Preferences for models within an application, such as for users, is a pretty
34 common idiom. Although the rule of thumb is to keep the number of preferences
35 available to a minimum, sometimes it's necessary if you want users to be able to
36 disable things like e-mail notifications.
37
aff9c95 @obrie Fix spelling/grammar problems in the README
obrie authored
38 Generally, basic preferences can be accomplished through simple designs, such as
ffcf63d @obrie Rename to preferences
obrie authored
39 additional columns or a bit vector described and implemented by preference_fu[http://agilewebdevelopment.com/plugins/preferencefu].
40 However, as you find the need for non-binary preferences and the number of
41 preferences becomes unmanageable as individual columns in the database, the next
b98239d @obrie Add all prefers/preferred accessors for preferences to be analogous t…
obrie authored
42 step is often to create a separate "preferences" table. This is where the
43 +preferences+ plugin comes in.
ffcf63d @obrie Rename to preferences
obrie authored
44
b98239d @obrie Add all prefers/preferred accessors for preferences to be analogous t…
obrie authored
45 +preferences+ encapsulates this design by exposing preferences using simple
46 attribute accessors on the model, hiding the fact that preferences are stored in
47 a separate table and making it dead-simple to define and manage preferences.
ffcf63d @obrie Rename to preferences
obrie authored
48
49 == Usage
50
bae4321 @tlowrimore Add a generator for db migration to make installation a bit easier
tlowrimore authored
51 === Installation
52
51653a3 @obrie Fix README typo
obrie authored
53 +preferences+ requires an additional database table to work. You can generate
bae4321 @tlowrimore Add a generator for db migration to make installation a bit easier
tlowrimore authored
54 a migration for this table like so:
55
56 script/generate preferences
57
58 Then simply migrate your database:
59
60 rake db:migrate
61
ffcf63d @obrie Rename to preferences
obrie authored
62 === Defining preferences
63
64 To define the preferences for a model, you can do so right within the model:
65
66 class User < ActiveRecord::Base
67 preference :hot_salsa
68 preference :dark_chocolate, :default => true
69 preference :color, :string
70 preference :favorite_number
1920abc @obrie Add notes to README on group_defaults option
obrie authored
71 preference :language, :string, :default => 'English', :group_defaults => {:chat => 'Spanish'}
ffcf63d @obrie Rename to preferences
obrie authored
72 end
73
74 In the above model, 5 preferences have been defined:
75 * hot_salsa
76 * dark_chocolate
77 * color
78 * favorite_number
79 * language
80
81 For each preference, a data type and default value can be specified. If no
b98239d @obrie Add all prefers/preferred accessors for preferences to be analogous t…
obrie authored
82 data type is given, it's assumed to be a boolean value. If no default value is
ffcf63d @obrie Rename to preferences
obrie authored
83 given, the default is assumed to be nil.
84
85 === Accessing preferences
86
b98239d @obrie Add all prefers/preferred accessors for preferences to be analogous t…
obrie authored
87 Once preferences have been defined for a model, they can be accessed either
88 using the accessor methods that are generated for each preference or the generic
89 methods that are not specific to a particular preference.
ffcf63d @obrie Rename to preferences
obrie authored
90
b98239d @obrie Add all prefers/preferred accessors for preferences to be analogous t…
obrie authored
91 ==== Accessors
ffcf63d @obrie Rename to preferences
obrie authored
92
b98239d @obrie Add all prefers/preferred accessors for preferences to be analogous t…
obrie authored
93 There are several shortcut methods that are generated for each preference
94 defined on a model. These reflect the same set of methods (attribute accessors)
95 that are generated for a model's columns. Examples of these are shown below:
ffcf63d @obrie Rename to preferences
obrie authored
96
97 Query methods:
98 user.prefers_hot_salsa? # => false
b98239d @obrie Add all prefers/preferred accessors for preferences to be analogous t…
obrie authored
99 user.preferred_language? # => true
ffcf63d @obrie Rename to preferences
obrie authored
100
101 Reader methods:
b98239d @obrie Add all prefers/preferred accessors for preferences to be analogous t…
obrie authored
102 user.prefers_hot_salsa # => false
103 user.preferred_language # => "English"
ffcf63d @obrie Rename to preferences
obrie authored
104
105 Writer methods:
106 user.prefers_hot_salsa = false # => false
107 user.preferred_language = 'English' # => "English"
108
109 ==== Generic methods
110
b98239d @obrie Add all prefers/preferred accessors for preferences to be analogous t…
obrie authored
111 Each preference accessor is essentially a wrapper for the various generic methods
aff9c95 @obrie Fix spelling/grammar problems in the README
obrie authored
112 shown below:
ffcf63d @obrie Rename to preferences
obrie authored
113
114 Query method:
b98239d @obrie Add all prefers/preferred accessors for preferences to be analogous t…
obrie authored
115 user.prefers?(:hot_salsa) # => false
116 user.preferred?(:language) # => true
ffcf63d @obrie Rename to preferences
obrie authored
117
118 Reader method:
b98239d @obrie Add all prefers/preferred accessors for preferences to be analogous t…
obrie authored
119 user.prefers(:hot_salsa) # => false
120 user.preferred(:language) # => "English"
ffcf63d @obrie Rename to preferences
obrie authored
121
122 Write method:
fa57073 @obrie Rename #set_preference to #write_preference
obrie authored
123 user.write_preference(:hot_salsa, false) # => false
124 user.write_preference(:language, "English") # => "English"
ffcf63d @obrie Rename to preferences
obrie authored
125
126 === Accessing all preferences
127
ab24620 @obrie Avoid string evaluation for dynamic methods
obrie authored
128 To get the collection of all custom, stored preferences for a particular record,
257880e @obrie Rename preference_values hash to preferences
obrie authored
129 you can access the +stored_preferences+ has_many association which is automatically
ab24620 @obrie Avoid string evaluation for dynamic methods
obrie authored
130 generated:
ffcf63d @obrie Rename to preferences
obrie authored
131
257880e @obrie Rename preference_values hash to preferences
obrie authored
132 user.stored_preferences
ffcf63d @obrie Rename to preferences
obrie authored
133
ab24620 @obrie Avoid string evaluation for dynamic methods
obrie authored
134 In addition to this, you can get a hash of all stored preferences *and* default
257880e @obrie Rename preference_values hash to preferences
obrie authored
135 preferences, by accessing the +preferences+ helper:
ab24620 @obrie Avoid string evaluation for dynamic methods
obrie authored
136
257880e @obrie Rename preference_values hash to preferences
obrie authored
137 user.preferences # => {"language"=>"English", "color"=>nil}
ab24620 @obrie Avoid string evaluation for dynamic methods
obrie authored
138
139 This hash will contain the value for every preference that has been defined for
140 the model, whether that's the default value or one that has been previously
141 stored.
142
0247d76 @obrie Fix +preferences+ not properly selecting preferences when a group is …
obrie authored
143 A short-hand alternative for preferences is also available:
144
145 user.prefs # => {"language"=>"English", "color"=>nil}
146
ab24620 @obrie Avoid string evaluation for dynamic methods
obrie authored
147 === Grouping preferences
ffcf63d @obrie Rename to preferences
obrie authored
148
149 In addition to defining generic preferences for the owning record, you can also
b73fe27 @obrie Minor grammar tweaks
obrie authored
150 group preferences by ActiveRecord objects or arbitrary names. This is best shown
ab24620 @obrie Avoid string evaluation for dynamic methods
obrie authored
151 through an example:
ffcf63d @obrie Rename to preferences
obrie authored
152
153 user = User.find(:first)
154 car = Car.find(:first)
155
ab24620 @obrie Avoid string evaluation for dynamic methods
obrie authored
156 user.preferred_color = 'red', car
fa57073 @obrie Rename #set_preference to #write_preference
obrie authored
157 # user.write_preference(:color, 'red', car) # The generic way
ffcf63d @obrie Rename to preferences
obrie authored
158
b98239d @obrie Add all prefers/preferred accessors for preferences to be analogous t…
obrie authored
159 This will create a color preference of "red" for the given car. In this way,
ffcf63d @obrie Rename to preferences
obrie authored
160 you can have "color" preferences for different records.
161
162 To access the preference for a particular record, you can use the same accessor
163 methods as before:
164
ab24620 @obrie Avoid string evaluation for dynamic methods
obrie authored
165 user.preferred_color(car)
166 # user.preferred(:color, car) # The generic way
167
168 In addition to grouping preferences for a particular record, you can also group
169 preferences by name. For example,
170
171 user = User.find(:first)
172
450f979 @obrie Update README to reflect changes to #preferences
obrie authored
173 user.preferred_color = 'red', :automobiles
174 user.preferred_color = 'tan', :clothing
ab24620 @obrie Avoid string evaluation for dynamic methods
obrie authored
175
450f979 @obrie Update README to reflect changes to #preferences
obrie authored
176 user.preferred_color(:automobiles) # => "red"
177 user.preferred_color(:clothing) # => "tan"
178
179 user.preferences(:automobiles) # => {"color"=>"red"}
ffcf63d @obrie Rename to preferences
obrie authored
180
181 === Saving preferences
497920d @obrie Removed install.rb files.
obrie authored
182
b98239d @obrie Add all prefers/preferred accessors for preferences to be analogous t…
obrie authored
183 Note that preferences are not saved until the owning record is saved.
184 Preferences are treated in a similar fashion to attributes. For example,
497920d @obrie Removed install.rb files.
obrie authored
185
ffcf63d @obrie Rename to preferences
obrie authored
186 user = user.find(:first)
b98239d @obrie Add all prefers/preferred accessors for preferences to be analogous t…
obrie authored
187 user.attributes = {:prefers_hot_salsa => false, :preferred_color => 'red'}
ffcf63d @obrie Rename to preferences
obrie authored
188 user.save!
8fa2ef2 @obrie Initial import.
obrie authored
189
aff9c95 @obrie Fix spelling/grammar problems in the README
obrie authored
190 Preferences are stored in a separate table called "preferences".
8fa2ef2 @obrie Initial import.
obrie authored
191
9793648 @obrie Add README notes on latest tracking features
obrie authored
192 === Tracking changes
193
194 Similar to ActiveRecord attributes, unsaved changes to preferences can be
195 tracked. For example,
196
197 user.preferred_language # => "English"
198 user.preferred_language_changed? # => false
199 user.preferred_language = 'Spanish'
200 user.preferred_language_changed? # => true
201 user.preferred_language_was # => "English"
202 user.preferred_language_change # => ["English", "Spanish"]
203 user.reset_preferred_language!
204 user.preferred_language # => "English"
205
206 Assigning the same value leaves the preference unchanged:
207
208 user.preferred_language # => "English"
209 user.preferred_language = 'English'
210 user.preferred_language_changed? # => false
211 user.preferred_language_change # => nil
212
ffcf63d @obrie Rename to preferences
obrie authored
213 == Testing
8fa2ef2 @obrie Initial import.
obrie authored
214
ffcf63d @obrie Rename to preferences
obrie authored
215 Before you can run any tests, the following gem must be installed:
78efc83 @obrie Update list of plugin resources to GitHub/Lighthouse
obrie authored
216 * plugin_test_helper[http://github.com/pluginaweek/plugin_test_helper]
8fa2ef2 @obrie Initial import.
obrie authored
217
ff71c9d @obrie Add information about what version of Rails is required
obrie authored
218 To run against a specific version of Rails:
219
220 rake test RAILS_FRAMEWORK_ROOT=/path/to/rails
221
ffcf63d @obrie Rename to preferences
obrie authored
222 == Dependencies
8fa2ef2 @obrie Initial import.
obrie authored
223
ca1a77b @rds Updated dependencies in README
rds authored
224 * 0.5.0 for Rails 3 (0.4.x and below for Rails 2)
Something went wrong with that request. Please try again.