merged cont.
[opensuse:yast-rest-service.git] / webservice / public / javascripts / jquery.example.js
1 /*
2  * Source: jQuery Form Example Plugin 1.4.2
3  * Populate form inputs with example text that disappears on focus.
4  *
5  * e.g.
6  *  $('input#name').example('Bob Smith');
7  *  $('input[@title]').example(function() {
8  *    return $(this).attr('title');
9  *  });
10  *  $('textarea#message').example('Type your message here', {
11  *    className: 'example_text'
12  *  });
13  *
14  * Copyright (c) Paul Mucur (http://mucur.name), 2007-2008.
15  * Dual-licensed under the BSD (BSD-LICENSE.txt) and GPL (GPL-LICENSE.txt)
16  * licenses.
17  *
18  * This program is free software; you can redistribute it and/or modify
19  * it under the terms of the GNU General Public License as published by
20  * the Free Software Foundation; either version 2 of the License, or
21  * (at your option) any later version.
22  *
23  * This program is distributed in the hope that it will be useful,
24  * but WITHOUT ANY WARRANTY; without even the implied warranty of
25  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
26  * GNU General Public License for more details.
27  */
28 (function($) {
29   
30   $.fn.example = function(text, args) {
31     
32     /* Only calculate once whether a callback has been used. */
33     var isCallback = $.isFunction(text);
34     
35     /* Merge the arguments and given example text into one options object. */
36     var options = $.extend({}, args, {example: text});
37     
38     return this.each(function() {
39       
40       /* Reduce method calls by saving the current jQuery object. */
41       var $this = $(this);
42       
43       /* Merge the plugin defaults with the given options and, if present,
44        * any metadata.
45        */
46       if ($.metadata) {        
47         var o = $.extend({}, $.fn.example.defaults, $this.metadata(), options);
48       } else {
49         var o = $.extend({}, $.fn.example.defaults, options);
50       }
51       
52       /* The following event handlers only need to be bound once
53        * per class name. In order to do this, an array of used
54        * class names is stored and checked on each use of the plugin.
55        * If the class name is in the array then this whole section 
56        * is skipped. If not, the events are bound and the class name 
57        * added to the array.
58        *
59        * As of 1.3.2, the class names are stored as keys in the
60        * array, rather than as elements. This removes the need for
61        * $.inArray().
62        */
63       if (!$.fn.example.boundClassNames[o.className]) {
64       
65         /* Because Gecko-based browsers cache form values
66          * but ignore all other attributes such as class, all example
67          * values must be cleared on page unload to prevent them from
68          * being saved.
69          */
70         $(window).unload(function() {
71           $('.' + o.className).val('');
72         });
73       
74         /* Clear fields that are still examples before any form is submitted
75          * otherwise those examples will be sent along as well.
76          * 
77          * Prior to 1.3, this would only be bound to forms that were
78          * parents of example fields but this meant that a page with
79          * multiple forms would not work correctly.
80          */
81         $('form').submit(function() {
82         
83           /* Clear only the fields inside this particular form. */
84           $(this).find('.' + o.className).val('');
85         });
86       
87         /* Add the class name to the array. */
88         $.fn.example.boundClassNames[o.className] = true;
89       }
90     
91       /* Internet Explorer will cache form values even if they are cleared
92        * on unload, so this will clear any value that matches the example
93        * text and hasn't been specified in the value attribute.
94        *
95        * If a callback is used, it is not possible or safe to predict
96        * what the example text is going to be so all non-default values
97        * are cleared. This means that caching is effectively disabled for
98        * that field.
99        *
100        * Many thanks to Klaus Hartl for helping resolve this issue.
101        */
102       if ($.browser.msie && !$this.attr('defaultValue') && (isCallback || $this.val() == o.example))
103         $this.val('');
104       
105       /* Initially place the example text in the field if it is empty
106        * and doesn't have focus yet.
107        */
108       if ($this.val() == '' && this != document.activeElement) {
109         $this.addClass(o.className);
110         
111         /* The text argument can now be a function; if this is the case,
112          * call it, passing the current element as `this`.
113          */
114         $this.val(isCallback ? o.example.call(this) : o.example);
115       }
116       
117       /* Make the example text disappear when someone focuses.
118        *
119        * To determine whether the value of the field is an example or not,
120        * check for the example class name only; comparing the actual value
121        * seems wasteful and can stop people from using example values as real 
122        * input.
123        */
124       $this.focus(function() {
125         
126         /* jQuery 1.1 has no hasClass(), so is() must be used instead. */
127         if ($(this).is('.' + o.className)) {
128           $(this).val('');
129           $(this).removeClass(o.className);
130         }
131       });
132
133       /* Detect a change event to the field and remove the example class. */
134       $this.change(function() {
135         if ($(this).is('.' + o.className)) {
136           $(this).removeClass(o.className);
137         }
138       });
139
140       /* Make the example text reappear if the input is blank on blurring. */
141       $this.blur(function() {
142         if ($(this).val() == '') {
143           $(this).addClass(o.className);
144           
145           /* Re-evaluate the callback function every time the user
146            * blurs the field without entering anything. While this
147            * is not as efficient as caching the value, it allows for
148            * more dynamic applications of the plugin.
149            */
150           $(this).val(isCallback ? o.example.call(this) : o.example);
151         }
152       });
153     });
154   };
155   
156   /* Users can override the defaults for the plugin like so:
157    *
158    *   $.fn.example.defaults.className = 'not_example';
159    */
160   $.fn.example.defaults = {
161     className: 'example'
162   };
163   
164   /* All the class names used are stored as keys in the following array. */
165   $.fn.example.boundClassNames = [];
166   
167 })(jQuery);