https://github.com/mudge/jquery_example
jQuery plugin to populate form inputs with example text that disappears on focus. See also http://github.com/mudge/jquery_placeholder
https://github.com/mudge/jquery_example
Last synced: 11 months ago
JSON representation
jQuery plugin to populate form inputs with example text that disappears on focus. See also http://github.com/mudge/jquery_placeholder
- Host: GitHub
- URL: https://github.com/mudge/jquery_example
- Owner: mudge
- License: bsd-3-clause
- Created: 2008-04-07T12:39:36.000Z (about 18 years ago)
- Default Branch: master
- Last Pushed: 2017-07-17T07:36:32.000Z (almost 9 years ago)
- Last Synced: 2025-07-30T09:47:30.449Z (11 months ago)
- Language: JavaScript
- Homepage: http://mudge.name/jquery_example/
- Size: 200 KB
- Stars: 107
- Watchers: 5
- Forks: 24
- Open Issues: 1
-
Metadata Files:
- Readme: README.markdown
Awesome Lists containing this project
README
jQuery Form Example Plugin 1.6.2 [](http://travis-ci.org/mudge/jquery_example)
======================================
This is a jQuery plugin to populate form inputs with example text that
disappears on focus.
Basic usage revolves around the use of the `example` function like so:
$('input#name').example('Bob Smith');
This will then put the example text "Bob Smith" into the input with the ID
"name". When a user then focuses on this input, the example text will
disappear, allowing them to enter their data. If they then click elsewhere
*without entering any information*, the example will re-appear.
By default, example text is given the class `example`, allowing you to style
it with CSS like so:
.example { color: #666; }
If this class name conflicts with one you already use, you can override it
with the `className` option like so:
$('input#name').example('Bob Smith', { className: 'hint' });
The above example would then be given the class `hint` instead of `example`.
If you plan to use the same options repeatedly, it is possible to override the
plugin's defaults directly:
$.fn.example.defaults.className = 'notExample';
This will cause any uses of the plugin after this point to use the new
defaults.
As well as supplying the example text via a string, a callback function can be
used instead to determine the value at runtime:
$('input#name').example(function() {
return $(this).attr('title');
});
The above example will set the example text to the `title` attribute of the
input. The callback is executed within the context of the input field so, as
in the example above, `$(this)` will return the input itself.
It is worth noting that the callback is evaluated every time the example text
needs to be inserted and *is not cached*. This makes it possible to
dynamically change the example text of a field after page load like so:
$('input#name').example(function() {
var text = $(this).attr('title');
$(this).attr('title', 'Not the original title anymore');
return text;
});
The plugin also supports the jQuery Metadata plugin which allows you to
specify metadata in elements themselves. You can specify the example text and any options like so:
Please note that metadata will be overridden by arguments, e.g.
$('#m1').example('Another example');
The example will be set to "Another example" instead of "An example".
All events are namespaced with `.example` so they can be selectively unbound with
`unbind('.example')`. The full list is as follows:
* `unload.example` on the `window`;
* `submit.example` on any affected `form`s;
* `focus.example` on affected inputs;
* `change.example` on affected inputs;
* `blur.example` on affected inputs.
As of 1.6.0, if you wish to manually trigger clearing examples from a form (e.g. because you wish to override a form's `submit` event in some way) then you can trigger a special custom event, `example:resetForm` to do so:
```javascript
$('#myform').trigger('example:resetForm');
```
Note that, due to event bubbling, triggering `example:resetForm` on a specific field will actual propagate up to its parent form and reset all examples.
```javascript
/* This will actually bubble up to trigger on #myform. */
$('#myform input.name').trigger('example:resetForm');
```
Downloading
-----------
[Download jQuery Example 1.6.2](https://github.com/mudge/jquery_example/zipball/v1.6.2).
Or use [Bower](http://bower.io/):
```console
$ bower install jquery_example
```
Testing
-------
As of 1.4, this plugin now comes with a QUnit test suite that you can find
in the test/ directory and run by opening index.html in your browser.
Compatibility
-------------
This plugin has been tested with jQuery 1.6 to 1.7.0 and should work in all
browsers supported by jQuery itself (it has been tested with Safari 5.1.1,
Google Chrome 15.0.874.121, Mozilla Firefox 3.6, Mozilla Firefox 8, Opera 11.52 and
Internet Explorer 6).
Author
------
This plugin was written by and is maintained by Paul Mucur aka "mudge". Please
do not hesitate to contact me with comments and bug reports through GitHub:
https://github.com/mudge/jquery_example/issues
You can view the latest source code (and fork the entire project if you wish)
at http://github.com/mudge/jquery_example
Contributors
------------
The code to support the Metadata plugin was contributed by DeLynn Berry (http://github.com/delynn).
Licensing
---------
Copyright (c) Paul Mucur (http://mudge.name), 2007-2014.
Dual-licensed under the BSD (BSD-LICENSE.txt) and GPL (GPL-LICENSE.txt)
Licenses.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
Donations
---------
[Donations are accepted using Pledgie](http://www.pledgie.com/campaigns/1517)