avatar

29

Final pre-release additions to docs

by chrisk, 30 Jul, 2007 06:36 AM
rails_plugins/templated_attribute/README diff
27 29  
11 = Templated Attribute plugin
2   
3 This Rails plugin allows you to declare that certain attributes in your model
4 are "templated." A templated attribute has a helpful initial value---kind of
5 like a default value---except that these aren't valid data or saved in the
6 database. They're suggestions to the user about the expected formatting or
7 content of a field.
28 
9 You can view pre-generated rdocs for this plugin at: 
10 <http://docs.shiftcommathree.com/rails_plugins/templated_attribute>.
11 
312 See the blog post for a more detailed introduction:
4 <http://shiftcommathree.com/articles/templated_attributes>
13 <http://shiftcommathree.com/articles/templated_attributes>.
514 
6 This Rails plugin allows you to declare that certain attributes in your model are "templated." A templated attribute has a helpful initial value---kind of like a default value---except that these aren't valid data or saved in the database. They're suggestions to the user about the expected formatting or content of a field.
715 
816 
9 
1017 == Installation
1118 
1219 If you're using piston:
------
3744 
3845 This plugin aims to:
3946 
40 1.  pre-fill form fields with these templates, but keep these values out of the database
47 1.  pre-fill form fields with these templates, but keep these values out of the
48     database
4149 2.  specify these values only once in the model
42 3.  create a user experience that clearly implies that these values are just templates for valid data
50 3.  create a user experience that clearly implies that these values are just
51     templates for valid data
4352 
44 There are actually two kinds of templated attributes provided: those with <b>starting values</b>, which are potentially the start of valid data, and <b>labels</b>, which are just helpful, ephemeral reminders. An example of a starting value template is <tt>http://</tt> for a +website+ attribute; an example of a label template is <tt>(123) 555-1234</tt> for a +phone+ attribue. (We don't want the user to have to delete our dummy numbers and put in their own; it's too much work. Instead we think that the reminder will help coax the right format out of the user by itself---so this field gets blanked on focus using Javascript, unlike the +website+ attribute, which remains because it's the start of valid data.)
53 There are actually two kinds of templated attributes provided: those with
54 <b>starting values</b>, which are potentially the start of valid data, and
55 <b>labels</b>, which are just helpful, ephemeral reminders. An example of a
56 starting value template is <tt>http://</tt> for a +website+ attribute; an
57 example of a label template is <tt>(123) 555-1234</tt> for a +phone+ attribue.
58 (We don't want the user to have to delete our dummy numbers and put in their
59 own; it's too much work. Instead we think that the reminder will help coax the
60 right format out of the user by itself--so this field gets blanked on focus
61 using Javascript, unlike the +website+ attribute, which remains because it's
62 the start of valid data.)
4563 
4664 
4765 
4866 == Usage
4967 
68 See the documentation for the
69 +templated_attribute+[link:classes/TemplatedAttribute/ActiveRecordExtensions/ClassMethods.html]
70 method.
71 
5072   class User < ActiveRecord::Base
5173     templated_attribute :website, :starting_value => 'http://'
5274     templated_attribute :phone, :label => '(123) 555-1234'
5375   end
5476 
55 Validations work as expected, since unchanged template values get removed in a `:before_validation` callback. So you can sprinkle on a little `:validates_presence_of` and `:validates_format_of` for a really good time.
77 Validations work as expected, since unchanged template values get removed in a
78 <tt>:before_validation</tt> callback. So you can sprinkle on a little
79 <tt>:validates_presence_of</tt> and <tt>:validates_format_of</tt> for a really
80 good time.
5681 
57 There's also some nice, unobtrusive Javascript you can generate to get the behavior I mentioned above. If you're using `form_for`, it's totally automatic. It gets installed when you install the plugin, or you can install and remove manually with these `rake` tasks:
82 There's also some nice, unobtrusive Javascript you can generate to get the
83 behavior I mentioned above. If you're using +form_for+, it's totally automatic.
84 See the documentation for
85 +text_area+[link:classes/ActionView/Helpers/FormHelper.html] and
86 +text_field+[link:classes/ActionView/Helpers/FormHelper.html]. It gets
87 installed when you install the plugin, or you can install and remove manually
88 with these +rake+ tasks:
5889 
5990   rake templated_attribute:install
6091   rake templated_attribute:remove
6192 
62 To turn off the Javascript for a given `templated_attribute`---say, because the generated stuff doesn't jibe with your fancy-pantsy, AJAX-validating, Grey Poupon of a form---just throw `:templated_javascript => false` in the options hash for `text_field` or `text_area`. You'll have to do any styling and event handling by yourself.
93 To turn off the Javascript for a given +templated_attribute+--say, because the
94 generated stuff doesn't jibe with your fancy-pantsy, AJAX-validating, Grey
95 Poupon of a form--just throw <tt>:templated_javascript => false</tt> in the
96 options hash for +text_field+ or +text_area+. You'll have to do any styling
97 and event handling by yourself.
6398 
64 I'd like to make this work for fields other than `text_field` and `text_area`; the other contenders were `file_field`, which we can't do because the Javascript security model doesn't let us touch its value at runtime, and `password_field`, which I haven't done because showing the template value would require dynamically switching the element to a `text_field` and back (to avoid all those asterisks). That one's on the list, though.
99 I'd like to make this work for fields other than +text_field+ and +text_area+;
100 the other contenders were +file_field+, which we can't do because the
101 Javascript security model doesn't let us touch its value at runtime, and
102 +password_field+, which I haven't done because showing the template value
103 would require dynamically switching the element to a +text_field+ and back (to
104 avoid all those asterisks). That one's on the list, though.
65105 
66106 
67107