JQueryPlugin

jQuery JavaScript library for Foswiki

Description

Powered by WikiRing Consultants

"jQuery is a fast, concise, JavaScript Library that simplifies how you traverse HTML documents, handle events, perform animations, and add Ajax interactions to your web pages."

Coding Standards

See JQuery Coding Standards? This plugin contains the latest version of the jQuery JavaScript library. See also Foswiki:Development.UsingJQueryWithFoswiki for more information on using jQuery with Foswiki.

Further references and tutorials

• Getting the feet wet
• Tutorials
• Reference API
• Using jQuery with other libraries
• Plugin repository

Using compressed javascript and css files

All jQuery plugins are shipped with uncompressed js and css files, as well as minified and gzip compressed. For instance the jquery.autocomplete comes with the following set:

1. /pub/System/JQueryPlugin/plugins/autocomplete/jquery.autocomplete.uncompressed.js
2. /pub/System/JQueryPlugin/plugins/autocomplete/jquery.autocomplete.js
3. /pub/System/JQueryPlugin/plugins/autocomplete/jquery.autocomplete.js.gz

There is a Makefile in the /pub/System/JQueryPlugin root directory that grants all these files are up to date. By default all files in the JQueryPlugin package are up to date. So you only have to issue a make in the root directory if you wish to modify one of the files underneath. This will update all minified and gzipped files as needed. Enable the {JQueryPlugin}{Debug} flag in configure, to use the uncompressed files right away to omit the make step during development of further javascript components.

Apache can be configured to automatically use the .gz files if present using mod_rewrite as follows:

  <FilesMatch ".*\.(js|css)$">
    RewriteEngine On
    RewriteCond %{HTTP:Accept-encoding} gzip
    RewriteCond %{REQUEST_FILENAME}.gz -f
    RewriteRule ^(.*)$ %{REQUEST_URI}.gz [L,QSA]
  </FilesMatch>

  <Files *.js.gz>
    AddEncoding gzip .js
    ForceType application/x-javascript
  </Files>

  <Files *.css.gz>
    AddEncoding gzip .css
    ForceType text/css
  </Files>

So whenever the browser accepts encoding the file as gzip and the file with the .gz does exist in the filesystem, then trigger an internal redirect while still enforcing the original mine-type. The browser on the other side will unzip the css and js files automatically. This will drastically reduce bandwidth and speed up interactive performance.

Available jQuery plugins

1. Autocomplete

Autocomplete an input field to enable users quickly finding and selecting some value, leveraging searching and filtering. By giving an autocompleted field focus or entering something into it, the plugin starts searching for matching entries and displays a list of values to choose from. By entering more characters, the user can filter down the list to better matches. This can be used to enter previous selected values, eg. for tags, to complete an address, eg. enter a city name and get the zip code, or maybe enter email addresses from an addressbook.

See also JQueryjaxHelper for examples on how to integrate autocompletion into Foswiki.

2. bgiframe (active)

A jQuery plugin that helps ease the pain when having to deal with IE z-index issues.

3. blockUI

The jQuery BlockUI? Plugin lets you simulate synchronous behavior when using AJAX, without locking the browser. When activated, it will prevent user activity with the page (or part of the page) until it is deactivated. BlockUI? adds elements to the DOM to give it both the appearance and behavior of blocking user interaction.

4. Button

This is a simple way to render nice buttons in Foswiki. It can be used to replace submit and reset buttons of html forms as well. Foswiki:Extensions/FamFamFamContrib is recommended to display nice icons on buttons. Note, that this widget does not participate on the jquery theme roller. This is independent.

5. Chili

Chili is the jQuery code highlighter plugin.

Features:

• Very fast highlighting, trivial setup, fully customizable, thoroughly documented, and MIT licensed
• Renders identically on IE, Firefox, Mozilla, Opera, and Safari
• Comes bundled with recipes for C++, C#, CSS, Delphi, Java, JavaScript? , LotusScript? , MySQL? , PHP, and XHTML
• Many configuration options: Static, Dynamic, Automatic, Manual, Ad-Hoc, with Metaobjects.
• Provides fine control over which elements get highlighted by means of a jQuery selector or the mithical jQuery chainability.
• Fully supports javascript regular expressions, including backreferences
• The replacement format gives full control on what HTML is used for highlighting
• Provides examples which show setups and features

Additional recpipes: bash

6. Cookie

Easy cookie handling using jQuery.

Example usage:

• $.cookie('the_cookie');: return the value of the cookie
• $.cookie('the_cookie', 'the_value');: set the value of a cookie
• $.cookie('the_cookie', 'the_value', { expires: 7, path: '/', domain: 'jquery.com', secure: true });: create a cookie with all available options.
• $.cookie('the_cookie', null);: delete a cookie by passing null as value. Keep in mind that you have to use the same path and domain used when the cookie was set.

Options:

• expires: either an integer specifying the expiration date from now on in days or a Date object. If a negative value is specified (e.g. a date in the past), the cookie will be deleted. If set to null or omitted, the cookie will be a session cookie and will not be retained when the the browser exits.
• path: the value of the path atribute of the cookie (default: path of page that created the cookie).
• domain: the value of the domain attribute of the cookie (default: domain of page that created the cookie).
• secure: if true, the secure attribute of the cookie will be set and the cookie transmission will require a secure protocol (like HTTPS).

7. Cycle

The jQuery Cycle Plugin is a lightweight slideshow plugin. Its implementation is based on the InnerFade? Plugin by Torsten Baldes, the Slideshow Plugin by Matt Oakes, and the jqShuffle Plugin by Benjamin Sterling. It supports pause-on-hover, auto-stop, auto-fit, before/after callbacks, click triggers and many transition effects. It also supports, but does not require, the Metadata Plugin and the Easing Plugin.

8. Debug

Simple jQuery logger / debugger using firebug's console or a div of its own of the form

<div id="DEBUG">
  <ol>
    <li>...</li>
    ...
  </ol>
</div>

Usage:

• $.log("message");: will send the message to the console
• $.log(object);: will stringify the object
• $("").debug(); will stringify the found objects

9. Easing (active)

Uses the built in easing capabilities added In jQuery 1.1 to offer multiple easing options.

10. Farbtastic

Farbtastic is a jQuery plug-in that can add one or more color picker widgets into a page. Each widget is then linked to an existing element (e.g. a text field) and will update the element's value when a color is selected. Farbtastic uses layered transparent PNGs to render a saturation/luminance gradient inside of a hue circle. No Flash or pixel-sized divs are used.

Basic usage:

<input type="text" id="color" name="color" value="#123456" class="jqFarbtastic" />

There's a color formfield for easy integration into Foswiki DataForms.

11. Focus

This plugin sets the focus on a form input field or textarea of a form when the page is loaded.

Add the css class .jqFocus to the input field you'd like to focus.

12. Form

The jQuery Form Plugin allows you to easily and unobtrusively upgrade HTML forms to use AJAX. The main methods, ajaxForm and ajaxSubmit, gather information from the form element to determine how to manage the submit process. Both of these methods support numerous options which allows you to have full control over how the data is submitted. Submitting a form with AJAX doesn't get any easier than this!

13. Foswiki (active)

This is plugin takes care of loading the jQuery core and default plugins and performs any initialization steps specific to Foswiki, For instance, it reads all <meta> tags from the html head as they have been set by Foswiki and constructs the foswiki javascript object to be used by other javascript plugins.

In addition it adds some basic Foswiki tags to make life easier using jQuery plugins, most notably %JQREQUIRE{"pluginName"}% to load a subsequent jQuery plugin and all of its dependencies, taking care where and how it is added to the html page.

Curent default plugins are: jquery.easing, jquery.metadata, jquery.bgiframe, jquery.hoverIntent

14. Gradient

Adds a gradient to the background of an element.

example:

$('div').gradient({ from: '000000', to: 'CCCCCC' });

options:

• from: The hex color code to start the gradient with. By default the value is "000000".
• to: The hex color code to end the gradient with. By default the value is "FFFFFF".
• direction: This tells the gradient to be horizontal or vertical. By default the value is "horizontal".
• length: This is used to constrain the gradient to a particular width or height (depending on the direction). By default the length is set to null, which will use the width or height (depending on the direction) of the element.
• position: This tells the gradient to be positioned at the top, bottom, left and/or right within the element. The value is just a string that specifices top or bottom and left or right. By default the value is 'top left'.

15. hoverIntent

hoverIntent is similar to jQuery's built-in "hover" function except that instead of firing the onMouseOver event immediately, hoverIntent checks to see if the user's mouse has slowed down (beneath the sensitivity threshold) before firing the onMouseOver event.

16. InnerFade

InnerFade? is a small plugin for the jQuery-JavaScript-Library. It's designed to fade you any element inside a container in and out. These elements could be anything you want, e.g. images, list-items, divs. Simply produce your own slideshow for your portfolio or advertisings. Create a newsticker or do an animation.

Example:

<ul id="news">
    <li>content 1</li>
    <li>content 2</li>
    <li>content 3</li>
</ul>

$('#news').innerfade({
    animationtype: 
      Type of animation 'fade' or 'slide' 
      (Default: 'fade'),

    speed: 
      Fading-/Sliding-Speed in milliseconds or keywords 
      (slow, normal or fast) (Default: 'normal'),

    timeout: 
      Time between the fades in milliseconds (Default: '2000'),

    type: 
      Type of slideshow: 'sequence', 'random' or 'random_start' 
      (Default: 'sequence'), 

    containerheight: 
      Height of the containing element in any css-height-value 
      (Default: 'auto'),

    runningclass: 
      CSS-Class which the container get’s applied 
      (Default: 'innerfade'),

    children: 
      optional children selector (Default: null)
});

17. MaskedInput

This is a masked input plugin for the jQuery javascript library. It allows a user to more easily enter fixed width input where you would like them to enter the data in a certain format (dates,phone numbers, etc). It has been tested on Internet Explorer 6/7, Firefox 1.5/2/3, Safari, Opera, and Chrome. A mask is defined by a format made up of mask literals and mask definitions. Any character not in the definitions list below is considered a mask literal. Mask literals will be automatically entered for the user as they type and will not be able to be removed by the user.

The following mask definitions are predefined: * a - Represents an alpha character (A-Z,a-z) * 9 - Represents a numeric character (0-9) * * - Represents an alphanumeric character (A-Z,a-z,0-9)

Examples:

$("#date").mask("99/99/9999");
$("#phone").mask("(999) 999-9999");
$("#tin").mask("99-9999999");
$("#ssn").mask("999-99-9999");

Use a space instead of an underscore "_" character as a placeholder

$("#product").mask("99/99/9999",{
  placeholder:" "
});

Adda "completed" callback:

$("#product").mask("99/99/9999",{
  completed: function() {
    alert("You typed the following: "+this.val());
  }
});

Define an own mask:

$.mask.definitions['~']='[+-]';
$("#eyescript").mask("~9.99 ~9.99 999");

18. Media

jQuery Media Plugin for converting elements into rich media content.

Supported Media Players:

• Flash
• Quicktime
• Real Player
• Silverlight
• Windows Media Player
• iframe

Supported Media Formats:
Any types supported by the above players, such as:

• Video: asf, avi, flv, mov, mpg, mpeg, mp4, qt, smil, swf, wmv, 3g2, 3gp
• Audio: aif, aac, au, gsm, mid, midi, mov, mp3, m4a, snd, rm, wav, wma
• Other: bmp, html, pdf, psd, qif, qtif, qti, tif, tiff, xaml

19. Metadata (active)

This plugin is capable of extracting metadata from classes, random attributes, and child elements.

20. Nifty

Nifty for jQuery is a modified and optimized version of Nifty Corners Cube. The new one has been programmed by Paul Bakaus (paul.bakaus@gmail.com).

Nifty Corners Cube - rounded corners with CSS and Javascript Copyright 2006 Alessandro Fulciniti (a.fulciniti@html.it)

21. Rating

The Star Rating Plugin is a plugin for the jQuery Javascript library that creates a non-obstrusive star rating control based on a set of radio input boxes.

It turns a collection of radio boxes into a neat star-rating control. It creates the interface based on standard form elements, which means the basic functionality will still be available even if Javascript is disabled.

22. Shake

jQuery plugin to emulate “shake” on login failure in OSX login box.

Example:

$('#btn').click(function() {
  $(this).shake(3, 6, 180);
});

23. ShrinkUrls

Shrinks all urls in a given container whose link text exceeds a given size and have no white spaces in it, that is don't wrap around nicely. If the text is skrunk, the original text is appended to the title attribute of the anchor.

Usage:

 $("#container a").shrinkUrls({
   size:<number>,           // max size (default 25)
   include:'<regex>'       // regular expression a link text must
                           // match to be considered
   exclude:'<regex>'       // regular expression a link text must
                           // not match to be considered
   whitespace:<boolean>,   // true: even shrink if there's whitespace
                           // in the link text (default false)
   trunc:<head|middle|tail> // position where to insert the ellipsis
 });

24. SimpleModal

SimpleModal? is a lightweight jQuery plugin that provides a simple interface to create a modal dialog.

The goal of SimpleModal? is to provide developers with a cross-browser overlay and container that will be populated with data provided to SimpleModal? .

There are two ways to call SimpleModal? : 1) As a chained function on a jQuery object, like $('#myDiv').modal();. This call would place the DOM object, #myDiv, inside a modal dialog. Chaining requires a jQuery object. An optional options object can be passed as a parameter.

Examples:

$('<div>my data</div>').modal({options});
$('#myDiv').modal({options});
jQueryObject.modal({options});

2) As a stand-alone function, like $.modal(data). The data parameter is required and an optional options object can be passed as a second parameter. This method provides more flexibility in the types of data that are allowed. The data could be a DOM object, a jQuery object, HTML or a string.

$.modal('<div>my data</div>', {options});
$.modal('my data', {options});
$.modal($('#myDiv'), {options});
$.modal(jQueryObject, {options});
$.modal(document.getElementById('myDiv'), {options});

A SimpleModal? call can contain multiple elements, but only one modal dialog can be created at a time. Which means that all of the matched elements will be displayed within the modal container.

SimpleModal? internally sets the CSS needed to display the modal dialog properly in all browsers, yet provides the developer with the flexibility to easily control the look and feel. The styling for SimpleModal? can be done through external stylesheets, or through SimpleModal? , using the overlayCss and/or containerCss options.

SimpleModal? has been tested in the following browsers:

• IE 6, 7
• Firefox 2, 3
• Opera 9
• Safari 3

25. Superfish

Superfish is an enhanced Suckerfish-style menu jQuery plugin that takes an existing pure CSS drop-down menu (so it degrades gracefully without JavaScript? ). Features:

• Suckerfish-style hover support for IE6. The class added is sfHover by default but can be changed via the options object,
• Timed delay on mouseout to be more forgiving of mouse-piloting errors. Default is 800 milliseconds but can be changed via the options object
• Animation of sub-menu reveal. uses a fade-in by default but can be given a custom object to be used in the first argument of the animate function. The animation speed is also customisable but is set to ?normal? by default
• Keyboard accessibility. Tab through the links and the relevant sub-menus are revealed and hidden as needed
• Supports the hoverIntent plugin. Superfish automatically detects the presence of Brian Cherne?s hoverIntent plugin and uses its advanced hover behaviour for the mouseovers (mouseout delays are handled by Superfish regardless of the presence of hoverIntent). Using this is only an option, but a nice one. The examples on this page are using hoverIntent. If for some reason you want to use hoverIntent on your page for other plugins but do not want Superfish to use it you can set the option disableHI to true.
• Indicates the presence of sub-menus by automatically adding arrow images to relevant anchors. Arrows are fully customisable via CSS. You can turn off auto-generation of the arrow mark-up via the ?autoArrows? option if required.
• drop shadows for capable browsers ? degrades gracefully for Internet Explorer 6. Can disable shadows completely via options object.
• Can show the path to your current page while the menu is idle. The easiest way to understand this is to view the nav-bar example.
• Optional callback functions. The 'this' keyword within the handlers you attach will refer to the animated ul sub-menu. From version 1.4 there are now three other optional callbacks allowing for further enhancements and functionality to be added without needing to alter the core Superfish code.

TODO: upgrade to 1.4.8 or later

26. Tabpane

This implements an alternative tabpane widget. There is already one in jquery-ui, however as long as jquery-ui is still in flux, this alternative offers a safe substitute well integrated into Foswiki.

Individual tabs can be loaded on demand using a REST call. Installing Foswiki:Extensions/RenderPlugin is recommended for that.

Tabpanes can be nested. Tabs can be extended in height automatically. Heights can be auto-updated to follow windows resize events. Tabpanes can be established as part of reloaded content via ajax.

Note that this widget does not participate in jquery-ui themerolling. It does match jquery.button in terms of look & feel.

27. TextboxList

Turns a text input into a Facebook like list widget with autocompletion.

28. Toggle

This is a lightweigted widget to add a toggle feature similar to the TwistyPlugin. It uses the means available in jQuery only, i.e. it selectors to toggle the display of all matching elements.

29. Tooltip

Display a customized tooltip instead of the default one for every selected element. Tooltips can be added automatically to any element that has got at title attribute thus replacing the standard tooltip as displayed by the browsers with a customizable one.

Content can be reloaded using AJAX. For example, this can be used to display an image preview in a tooltip. Have a look at the thumbnail REST service of Foswiki:Extensions/ImagePlugin how to load the thumnail from the backend dynamically.

30. Treeview

Lightweight and flexible transformation of an unordered list into an expandable and collapsable tree, great for unobtrusive navigation enhancements. Supports both location and cookie based persistence.

Subtrees can be loaded on demand using AJAX. See the Foswiki:Extensions/RenderPlugin how to implement such REST handlers easily.

31. UI

Userinterface for jQuery

32. Validate

Very powerful client-side form validation framework (article).

33. WikiWord

This plugin allows to create a WikiWord on the base of a set of input elements. The value of these are concatenated and the result is normalized to be a valid WikiWord. For example, this can be used to derive a topic name from a free-form topic title text.

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Plugin Info

Author(s):	Michael Daum
Copyright:	2007-2010 Michael Daum http://michaeldaumconsulting.com
License:	GPL
Release:	3.01
Version:	6185 (2010-01-28)
Change History:
28 Jan 2010:	added jquery-1.4.1, corner, fluidfont, fullcalendar, localscroll, masonry, scrollto, serialscroll, slimbox; deprecated jquery.nifty; disabled JQSCRIPT and JQSTYLE
11 Nov 2009:	added jqGrid library; reorganized documentation
07 Nov 2009:	updated Superfish to 1.4.8 and added examples topic, added supersubs plugin, moved JQuery examples from Sandbox to System
29 Oct 2009:	added SCRIPTSUFFIX to foswiki var set (CDot)
14 Sep 2009:	added perls tubs for jquery.ui, so that you can pull it in via JQREQUIRE now; reworked plugin initialization to allow elements to be init'ed when loaded via ajax; fixed BUTTON to play nicely with TwistyPlugin; only load ui-theme if you jqrequire the ui library
20 Aug 2009:	made JQueryPlugin SafeWikiPlugin compatible
02 Jul 2009:	improved parsing of foswiki meta tags in html header; fixed jqTreeview initialisation for jquery-1.3.x; fixed chili initialisation; dropped support for konqueror3
23 Jun 2009:	added jquery.focus, jquery.textboxlist, jquery.farbtastic; jquery.gradient; added color and textboxlist formfield types; made JQueryPlugin pluggable itself; added animation switching tabs; improved automaxexpand feature in tabs
28 Apr 2009:	added jquery.media, jquery.simplemodal, shell highlightning for chilli
03 Feb 2009:	fixed tabpane not being rendered using a rest handler; added id to tabs that can be used to init the first active one; added compressed version of blockUI; replaced ICONTOPIC preference variable with ICONSEARCHPATH to search for icons in multiple directories (defaults to all of FamFamFamContrib)
15 Jan 2009:	fixed click target for relative urls in %BUTTON{}%; yet another jquery.wikiword fix
13 Jan 2009:	fixed jquery.wikiword not to depend on outside string libraries; added foswiki alias to global javascript variables (Eugen Mayer)
08 Jan 2009:	certified for foswiki/compat; fixed BUTTON target for non-wikiword topics
12 Dec 2008:	fixed a series of IE6+IE7 issues
18 Nov 2008:	added jquery.ifixpng; improved BUTTON tag to have submit and clear and reset buttons; ie6 fixes for BUTTONs; added missing jquery.wikiword plugin
13 Nov 2008:	added automaxexpand for TABPANES ; added jquery.shake plugin; reworked BUTTON tag
15 Oct 2008:	added jquery.autocomplete, jquery.cycle
20 Jul 2008:	added jquery.form, jquery.maskedinput, jquery.validate
15 Jul 2008:	updated to ui-1.5.2; added async treeview; added async options to tabpane
03 Jul 2008:	updated to ui-1.5.1
05 Jun 2008:	updated to jquery-1.2.6 and ui-1.5-RC1
30 Apr 2008:	repackaged to contain jquery UI
13 Feb 2008:	upgrade to jquery-1.2.3, as well as most plugins
17 Jan 2008:	added jquery.metadata plugin; implemented a jquery.tabpane plugin; updated jquery.dimensions plugin; added jquery.empty plugin to ease development of new plugins
15 Nov 2007:	use skin independent way to add javascript files to header
10 Oct 2007:	upgraded to jQuery-1.1.4; compressed js and css
12 Jul 2007:	initial package containing jQuery-1.1.3.1
Dependencies:	None
Home:	Foswiki:Extensions/JQueryPlugin
Support:	Foswiki:Support/JQueryPlugin