|
|
| 24 |
27 |
|
| 1 | 1 | = Templated Attribute plugin |
| 2 | 2 | |
| 3 | | See the blog post for an introduction: |
| 3 | See the blog post for a more detailed introduction: |
| 4 | 4 | <http://shiftcommathree.com/articles/templated_attributes> |
| 5 | 5 | |
| 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. |
| 6 | 7 | |
| 7 | 8 | |
| 8 | 9 | |
| 9 | 10 | == Installation |
| 10 | 11 | |
| 11 | | If you're using piston, change to your <tt>vendor/plugins</tt> directory and do: |
| 12 | If you're using piston: |
| 12 | 13 | |
| 13 | 14 | piston import http://svn.shiftcommathree.com/rails_plugins/templated_attribute vendor/plugins/templated_attribute |
| 14 | 15 | |
| --- | --- | |
| 19 | 20 | This will also generate <tt>public/javascripts/templated_attribute.js</tt> and |
| 20 | 21 | <tt>public/stylesheets/templated_attribute.css</tt>. It's up to you to include |
| 21 | 22 | these in your layouts. One good way to go is the new asset caching option added |
| 22 | | in <http://dev.rubyonrails.org/changeset/6164>: |
| 23 | in <http://dev.rubyonrails.org/changeset/6164> (not available in Rails 1.2.x): |
| 23 | 24 | |
| 24 | 25 | javascript_include_tag :all, :cache => true |
| 25 | 26 | stylesheet_link_tag :all, :cache => true |
| --- | --- | |
| 32 | 33 | |
| 33 | 34 | |
| 34 | 35 | |
| 36 | == Description |
| 37 | |
| 38 | This plugin aims to: |
| 39 | |
| 40 | 1. pre-fill form fields with these templates, but keep these values out of the database |
| 41 | 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 |
| 43 | |
| 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.) |
| 45 | |
| 46 | |
| 47 | |
| 48 | == Usage |
| 49 | |
| 50 | class User < ActiveRecord::Base |
| 51 | templated_attribute :website, :starting_value => 'http://' |
| 52 | templated_attribute :phone, :label => '(123) 555-1234' |
| 53 | end |
| 54 | |
| 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. |
| 56 | |
| 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: |
| 58 | |
| 59 | rake templated_attribute:install |
| 60 | rake templated_attribute:remove |
| 61 | |
| 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. |
| 63 | |
| 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. |
| 65 | |
| 66 | |
| 67 | |
| 35 | 68 | == Endnote |
| 36 | 69 | |
| 37 | 70 | See CHANGELOG[link:files/CHANGELOG.html] for a list of revisions. |
