Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 184 lines (126 sloc) 6.733 kB
2c2a6c7 @kristianmandrup initial commit
authored
1 h1. jQuery Form Utils
2
3 Packages various useful Javascript form and other UI utils into Rails 3 assets for the asset pipeline.
4 This gem makes it much easier to use these javascript enhancements in a Rails 3 app :)
5
6 h3. In-field labels
7
8 $(document).ready(function(){
9 $("label").inFieldLabels();
10 });
11
12 $("label").inFieldLabels({ optionName:value });</pre>
13
14 fadeOpacity: Value between 0.1 and 1.0. When a field is focussed, its label is animated to this opacity. Defaults to 0.5
15
16 fadeDuration: Time in milliseconds When an animation occurs, it uses this setting to determine duration. Defaults to 300.
17
18 h3. Highlight active form fields
19
20 See http://www.keyframesandcode.com/resources/javascript/jQuery/demos/highlight-demo.html
21
22 Highlights the part of the form currently in focus.
23
24 h3. Tipsy
25
26 See http://onehackoranother.com/projects/jquery/tipsy/
27
28 Simple, flexible tooltips plugin
29
30 h3. Autotab
31
32 http://www.mathachew.com/sandbox/jquery-autotab/
33
34 Auto-tab between form fields when field is complete
35
36 $(document).ready(function() {
37 $('#area_code, #number1, #number2').autotab_magic().autotab_filter('numeric');
38 });
39
40 .autotab_magic(): Automatically assign tabbing rules to all selected elements.
41
42 Example
43 -------
44 $(document).ready(function() {
45 $(':input').autotab_magic();
46 // OR
47 $('#area_code, #number1, #number2').autotab_magic();
48 });
49
50 .autotab_filter(string): Apply the specified filter to an element.
51
52 Example
53 -------
54 $(document).ready(function() {
55 $('#area_code, #number1, #number2').autotab_filter('numeric');
56 $('#key1, #key2, #key3, #key4, #key5').autotab_filter('alpha');
57 });
58
59 Options
60 -------
61 all (default): Any character
62 text: Any character except numbers 0 through 9
63 alpha: A through Z
64 numeric: 0 through 9
65 number: Identical to numeric
66 alphanumeric: A through Z and 0 through 9
67 custom: A custom regular expression to be used along with the pattern setting.
68
69 .autotab_filter(settings): Apply the key/value pairs to configure filter options to an element.
70
71 Example
72 $(document).ready(function() {
73 $('#area_code, #number1, #number2').autotab_filter({
74 format: 'alphanumeric',
75 uppercase: true
76 });
77 });
78
79 Settings
80 --------
81 format: The filtering method of the text field. Available filtering options are listed above.
82 uppercase: Converts any text to uppercase.
83 lowercase: Converts any text to lowercase.
84 nospace: Removes any spaces.
85 pattern: A regular expression pattern to use for custom formats.
86
87 .autotab(settings): Apply the key/value pairs to configure auto-tab and filter options to an element. Filtering settings are optional.
88
89 Example
90 -------
91 $(document).ready(function() {
92 // This example achieves the same result as Step 3 under Basic Usage.
93 $('#area_code').autotab({ target: 'number1', format: 'numeric' });
94 $('#number1').autotab({ target: 'number2', format: 'numeric', previous: 'area_code' });
95 $('#number2').autotab({ previous: 'number1', format: 'numeric' });
96 });
97
98 Settings
99 --------
100 All listed settings under .autotab_filter()
101 maxlength: Determines the maximum number of characters allowed in a text field. Passing maxlength will override the hardcoded maxlength attribute in the HTML.
102
103 target: The text field to auto-tab to when the maxlength has been reached on the current text field.
104
105 previous: The text field to auto-tab to when the Backspace key has been pressed in an empty text field. You can also press and hold Backspace to continue auto-tabbing in reverse.
106
107 h3. Custom inputs (radio and checkboxes)
108
109
110 We start with basic HTML for each input that follows web standards conventions:
111 assigned a unique id and value to each input
112 paired the input with a label element
113 included a "for" attribute on each label that references the preceding input's id
114 Each radio button input also needs a common name attribute to group it with a set.
115
116 <form>
117 <fieldset>
118 <legend>Which genres do you like?</legend>
119
120 <input type="checkbox" name="genre" id="check-1" value="action" />
121 <label for="check-1">Action / Adventure</label>
122
123 . . .
124 </fieldset>
125 <fieldset>
126 <legend>Caddyshack is the greatest movie of all time, right?</legend>
127
128 <input type="radio" name="opinions" id="radio-1" value="1" />
129 <label for="radio-1">Totally</label>
130
131 . . .
132 </fieldset>
133 </form>
134
135 Pairing the inputs and labels correctly is essential to how this plugin works. As stated in the HTML spec, "When a LABEL element receives focus, it passes the focus on to its associated control." Browsers have standardized this behavior so that when you click a label, the click is passed on to the input — in other words, the label and input act as a single element when marked up this way. Because we don't have to interact with the input directly, we can hide it from view with CSS and apply styles to the label to make it look like a customized checkbox or radio button.
136
137 When the page loads, the plugin script finds each input/label pair and wraps it in a div. Each wrapper div is assigned a class to it based on the type of input it contains:
138
139 <div class="custom-checkbox">
140 <input id="check-3" type="checkbox" value="epic" name="genre"/>
141 <label class="" for="check-3">Epic / Historical</label>
142 </div>
143
144 Use:
145
146 $('input').customInput();
147
148 Customize images for radio and checkbox
149
150 .custom-checkbox label { background: url(/assets/custom_input/checkbox.gif) no-repeat; }
151 .custom-radio label { background: url(/assets/custom_input/radiobutton.gif) no-repeat; }
152
153 h3. Message
154
155 Easily display feedback messages as an unobstrusive overlay. The message fades away automatically after some time, avoiding the need to click an “ok” button or something similar. The user can speed up hiding of the message by moving the mouse or clicking anywhere.
156
157 The interaction is based on Aza Raskin’s Humanized Message.
158
159 See http://bassistance.de/jquery-plugins/jquery-plugin-message/
160
161 h3. Justify labels
162
163 justifyLabels('form#login');
164
165 h3. Validation engine
166
167 See https://github.com/posabsolute/jQuery-Validation-Engine
168
169 h2. Contributing to Jquery Form Utils
170
171 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
172 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
173 * Fork the project.
174 * Start a feature/bugfix branch.
175 * Commit and push until you are happy with your contribution.
176 * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
177 * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
178
179 h2. Copyright
180
181 Copyright (c) 2012 Kristian Mandrup. See LICENSE.txt for
182 further details.
183
Something went wrong with that request. Please try again.