forked from mustardamus/ketchup-plugin
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
438 lines (345 loc) · 14.3 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<title>jQuery Ketchup Plugin - Documentation</title>
<link rel="stylesheet" type="text/css" media="screen" href="css/reset.css" />
<link rel="stylesheet" type="text/css" media="screen" href="css/main.css" />
<link rel="stylesheet" type="text/css" media="screen" href="../css/jquery.ketchup.css" />
<script type="text/javascript" src="../tests/jquery-1.4.4.min.js"></script>
<script type="text/javascript" src="../jquery.ketchup.js"></script>
<script type="text/javascript" src="../jquery.ketchup.helpers.js"></script>
<script type="text/javascript" src="../jquery.ketchup.validations.js"></script>
<script type="text/javascript" src="js/demos.js"></script>
</head>
<body>
<div id="wrapper"><h1>jQuery Ketchup Plugin - Tasty Form Validation</h1>
<blockquote><p>This is still in development. Anyway, feel free to test it and tell me what you think at twitter <code>@mustardamus</code>
or <code>@usejquery</code>. This doc has live demos in <code>docs/index.html</code> Have fun!</p></blockquote>
<p>Ketchup is a small (xxx minified) jQuery Plugin that helps you to validate your forms.
Out of the box it has (many) basic validations and a nice little bubble style. But truly this
Plugin wants to be hacked to fit your needs. Easily write your own validations and overwrite
the default behaviour. Bubbles are not for everyone...</p>
<h2>Default Behavior</h2>
<p>If you like the style of the bubbles and all validations you need are already written
you can get this Plugin up and running in a minute.</p>
<h3>Your HTML Header</h3>
<pre><code><!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<title>Yammie</title>
<link rel="stylesheet" type="text/css" media="screen" href="css/jquery.ketchup.css" />
<script type="text/javascript" src="js/jquery-1.4.2.min.js"></script>
<script type="text/javascript" src="js/jquery.ketchup.js"></script>
<script type="text/javascript" src="js/jquery.ketchup.validations.js"></script>
</head>
<body>
... form stuff ...
</code></pre>
<h3>Your HTML</h3>
<p>By default Ketchup checks the data-validate attribute of form fields if it can find matching and
existing validations. The default indicator for validations is validate(), all validations
go in there and are seperated by comma. Validations can have arguments, also seperated by comma.</p>
<pre><code><form id="default-behavior" action="index.html">
<ul>
<li>
<label for="db-mail">E-Mail</label>
<input type="text" id="db-mail" data-validate="validate(required, email)" />
</li>
<li>
<label for="db-username">Username</label>
<input type="text" id="db-username" data-validate="validate(required, username, minlength(3))" />
</li>
<li>
<input type="submit" value="Is Tasty?" />
</li>
</ul>
</form>
</code></pre>
<h3>Your Javascript</h3>
<p>Just call ketchup() on your form, voilà. Form validation baby!</p>
<pre><code>$('#default-behavior').ketchup();
</code></pre>
<h2>Declare fields to validate in the call</h2>
<p>The last version of Ketchup looked in class attributes for validations. Some people said that
this is abusive and they would never stick (pseudo) code in their classes. With the HTML5
data- attributes we don't have that problem. We can set whatever we want and be total valid.
However, if you still want to seperate the validations declarations from our markup you can do so
by passing an object with jQuery selectors as key and validations as value to Ketchup.</p>
<h3>Your HTML</h3>
<p>Note that required is not a validation declaration but an actual class name. We use that to
select the fields to validate.</p>
<pre><code><form id="fields-in-call" action="index.html">
<ul>
<li>
<label for="fic-email">E-Mail</label>
<input type="text" id="fic-email" class="required" />
</li>
<li>
<label for="fic-username">Username</label>
<input type="text" id="fic-username" class="required" />
</li>
<li>
<input type="submit" value="Is Tasty?" />
</li>
</ul>
</form>
</code></pre>
<h3>Your Javascript</h3>
<p>Right after the options (empty here) we pass in an object. Use the key to declare the jQuery
selector on which fields the validations in the value are processed.
If you declare fields like this you can left out the validations indicator.</p>
<pre><code>$('#fields-in-call').ketchup({}, {
'.required' : 'required', //all fields in the form with the class 'required'
'#fic-username': 'minlength(3)' //one field in the form with the id 'fic-username'
});
</code></pre>
<h2>Validate on different events</h2>
<p>By default Ketchup listens to the blur event on form fields. You can overwrite that behaviour
for every fields in the options, or you can overwrite it per form field.</p>
<h3>Your HTML</h3>
<p>In the data-validate attribute (you can choose which attribute can contain validations via the
options) you have the on() indicator. Events go in there and are seperated by a space. These
are strings jQuery's bind() accepts.</p>
<pre><code><form id="validation-events" action="index.html">
<ul>
<li>
<label for="ve-username">Username</label>
<input type="text" id="ve-username" data-validate="huha(required, minlength(3)) on(keyup focus)" />
</li>
<li>
<input type="submit" value="Is Tasty?" />
</li>
</ul>
</form>
</code></pre>
<h3>Your Javascript</h3>
<pre><code>$('#validation-events').ketchup({
validateEvents: 'dblclick',
validateIndicator:'huha'
});
/*if you set the fields to validate in the call
you simply passin a array as value. First argument
is the validations string and the second are the
events. Like so:
$('#validation-events').ketchup({}, {
'#ve-username': ['required, minlength(3)', 'keyup focus']
});*/
</code></pre>
<h2>Write your own validation</h2>
<p>Now to the real fun part, hacking instead of just calling! You can write your own validation
functions for Ketchup. A validation function must return a boolean, true if the field validates
fine and false if it fails to validate. Validations are called with at least three arguments:</p>
<ul>
<li>form - the jQuery object for the form</li>
<li>el - the jQuery object for the form field</li>
</ul>
<h3>Your HTML</h3>
<pre><code><form id="own-validation" action="index.html">
<ul>
<li>
<label for="ov-word">Ketchup or Mustard</label>
<input type="text" id="ov-word" data-validate="validate(word(ketchup, mustard))" />
</li>
<li>
<input type="submit" value="Is Tasty?" />
</li>
</ul>
</form>
</code></pre>
<h3>Your Javascript</h3>
<pre><code>$.ketchup.validation('word', 'Either "{arg1}" or "{arg2}"', function(form, el, value, word1, word2) {
if(value == word1 || value == word2) {
return true;
} else {
return false;
}
});
$('#own-validation').ketchup();
</code></pre>
<h2>Helpers for your validations</h2>
<p>this in your validations represents helper methods you can declare.</p>
<ul>
<li>list of</li>
<li>helpers here</li>
</ul>
<h3>Your HTML</h3>
<pre><code><form id="validation-helper" action="index.html">
<ul>
<li>
<label for="vh-email">Your E-Mail (must contain 'ketchup')</label>
<input type="text" id="vh-email" data-validate="validate(ketchupEmail)" />
</li>
<li>
<input type="submit" value="Is Tasty?" />
</li>
</ul>
</form>
</code></pre>
<h3>Your Javascript</h3>
<pre><code>$.ketchup.validation('ketchupEmail', 'Must be a valid e-mail and contain "ketchup"', function(form, el, value) {
if(this.isEmail(value) && value.toLowerCase().indexOf('ketchup') != -1) {
return true;
} else {
return false;
}
});
$('#validation-helper').ketchup();
</code></pre>
<h2>Write your own helpers</h2>
<h3>Your HTML</h3>
<pre><code><form id="own-helper" action="index.html">
<ul>
<li>
<label for="oh-rand1">This field is validated randomly</label>
<input type="text" id="oh-rand1" data-validate="validate(random)" />
</li>
<li>
<label for="oh-rand2">Words are validated randomly: ketchup, mustard</label>
<input type="text" id="oh-rand2" data-validate="validate(randomWord(ketchup, mustard))" />
</li>
<li>
<input type="submit" value="Is Tasty?" />
</li>
</ul>
</form>
</code></pre>
<h3>Your Javascript</h3>
<pre><code>$.ketchup.helper('randomNumber', function(min, max) {
return (min + parseInt(Math.random() * (max - min + 1)));
});
$.ketchup.validation('random', 'Not this time...', function(form, el, value) {
return (this.randomNumber(0, 1) ? true : false);
});
$.ketchup.validation('randomWord', 'Try the other word', function(form, el, value, word1, word2) {
return (this.randomNumber(0, 1) ? word1 : word2) == value;
});
$('#own-helper').ketchup();
</code></pre>
<h2>Set the messages for your validations</h2>
<p>As seen above the message can be set when you add the validaion. You can seperate the messages from the
validations in two ways.</p>
<p>Either overwrite single messages:</p>
<pre><code>$.ketchup.message('word', 'Guess the word!');
</code></pre>
<p>Or pass in an object to the messages method (You can copy and paste them if you changed them in the last version).
Note that only declared validation messages gets overwritten, the others are still set.</p>
<pre><code>$.ketchup.messages({
required : 'Something?',
minlength: '>= {arg1}'
});
</code></pre>
<h2>Control the behavior of the error container</h2>
<h3>Your HTML</h3>
<pre><code><form id="custom-behavior" action="index.html">
<ul>
<li>
<label for="cb-mail">E-Mail</label>
<input type="text" id="cb-mail" data-validate="validate(required, email)" />
</li>
<li>
<label for="cb-username">Username</label>
<input type="text" id="cb-username" data-validate="validate(required, minlength(3))" />
</li>
<li>
<input type="submit" value="Is Tasty?" />
</li>
</ul>
</form>
</code></pre>
<h3>Your Javascript</h3>
<pre><code>$.ketchup
.createErrorContainer(function(form, el) {
return $('<ul/>', {
css: {
display: 'none',
margin : 10,
}
}).insertAfter(el);
})
.addErrorMessages(function(form, el, container, messages) {
container.html('');
for(i = 0; i < messages.length; i++) {
$('<li/>', {
text: messages[i],
css : {
fontSize : 10,
textTransform: 'uppercase',
background : '#E44100',
textShadow : '1px 1px 0 #BF3600',
color : 'white',
padding : '3px 10px',
marginBottom: 2
}
}).appendTo(container);
}
})
.showErrorContainer(function(form, el, container) {
container.slideDown('fast');
})
.hideErrorContainer(function(form, el, container) {
container.slideUp('fast');
});
$('#custom-behavior').ketchup({
validateEvents: 'blur focus keyup'
});
</code></pre>
<h2>Check if the form and fields are valid from outside</h2>
<h3>Your HTML</h3>
<pre><code><form id="from-outside" action="index.html">
<ul>
<li>
<label for="fo-mail">E-Mail</label>
<input type="text" id="fo-mail" data-validate="validate(required, email)" />
</li>
<li>
<label for="fo-username">Username</label>
<input type="text" id="fo-username" data-validate="validate(required, username, minlength(5))" />
</li>
<li>
<input type="submit" value="Is Tasty?" />
</li>
</ul>
</form>
</code></pre>
<h3>Your Javascript</h3>
<pre><code>//reset our show function so no error container is displayed
$.ketchup.showErrorContainer(function(){});
var form = $('#from-outside'),
mail = $('#fo-mail', form),
username = $('#fo-username', form),
result = $('<ul/>').appendTo(form);
form.ketchup().submit(function() {
result.html('');
$.each([form, mail, username], function(index, el) {
var valid = el.ketchup('isValid') ? 'valid' : 'invalid';
$('<li/>', {
'class': valid,
text : '#' + el.attr('id') + ' is ' + valid
}).appendTo(result);
});
return false; //don't submit the form even if it's valid
}).submit();
</code></pre>
<h2>To-Do</h2>
<ul>
<li>Rewrite fieldsFrom* methods</li>
<li>Trigger events</li>
<li>Docs for Helpers</li>
<li>Finish docs</li>
<li>Style docs</li>
<li>Add navigation to html docs</li>
</ul>
<h2>Default Options</h2>
<pre><code>attribute : 'data-validate', //look in that attribute for an validation string
validateIndicator : 'validate', //in the validation string this indicates the validations eg validate(required)
eventIndicator : 'on', //in the validation string this indicates the events when validations get fired eg on(blur)
validateEvents : 'blur', //the default event when validations get fired on every field
validateElements : ['input', 'textarea', 'select'],//check this fields in the form for a validation string on the attribute
createErrorContainer: null, //function to create the error container (can also be set via $.ketchup.createErrorContainer(fn))
showErrorContainer : null, //function to show the error container (can also be set via $.ketchup.showErrorContainer(fn))
hideErrorContainer : null, //function to hide the error container (can also be set via $.ketchup.hideErrorContainer(fn))
addErrorMessages : null //function to add error messages to the error container (can also be set via $.ketchup.addErrorMessages(fn))
</code></pre>
</div></body></html>