JQueryPlugin

jQuery JavaScript library for Foswiki

Description

"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."

Besides jQuery itself, JQueryPlugin comes with a selection of third party plugins that are thought to be essential for modern web applications. These are integrated into Foswiki either by means of a special macro, by "minimal markup", or custom javascript initializer. "Minimal markup" is a way to avoid the need to write javascript code to initialize the interface. Instead, a special css class is added to an html element that triggers its initialization. See JQueryMetadata for an example.

Use JQREQUIRE to make use of a specific jQuery plugin on a page. This will prepare the page by loading the required javascript and css components. If you need to make a feature available on each and every page of your site, you may add this plugin to the list of default plugins loaded automatically. See configure.

Those plugins coming with their own macro will take care of loading their javascript and css by themselves. So you won't need to call JQREQUIRE explicitly for those listed below.

Adding new plugins

The JQuery ecosystem has a huge number of plugins - more than can be included by default by this plugin. If you want to add new plugins, then you will find instructions for adding them at Foswiki:Development.UsingJQueryWithFoswiki#adding_plugins.

Writing your own Javascript

Whether writing your own plugins or writing Javascript code in topics, you should observe the Foswiki JQueryCodingStandards.

jQuery References and tutorials

• How jQuery Works
• jQuery Learning Center
• jQuery API Documentatiom
• Alternative jQuery Documentation and API Browser
• Avoiding Conflicts with Other Libraries
• The jQuery Plugin Registry

Macros

BUTTON -- renders a nice button

Parameters

Examples

You type:

%BUTTON{
   "%MAKETEXT{"Submit"}%"
   icon="fa-check"
   onclick="confirm('Are your sure?')"
}%
%BUTTON{
   "%MAKETEXT{"Cancel"}%"
   icon="fa-times"
   target="%WEB%.%TOPIC%"
}% 

You get:

Submit Cancel

TABPANE -- tabpane widget

This macro starts the tabpane, containing a series of TAB...ENDTABs and ends with ENDTABPANE. A complete tabpane normally looks like this:

%TABPANE%
 %TAB{"tab 1"}%
   ...
 %ENDTAB%
 %TAB{"tab 2"}%
   ...
 %ENDTAB%
%ENDTABPANE%

Multiple tabpanes can be nested using the following scheme:

%TABPANE%
 %TAB{"tab 1"}%
   %TABPANE%
     %TAB{"tab 1.1"}%
       ...
     %ENDTAB%
     %TAB{"tab1.2"}%
       ...
     %ENDTAB%
   %ENDTABPANE%
 %ENDTAB%
 %TAB{"tab 2"}%
   ...
 %ENDTAB%
%ENDTABPANE%

Parameters

Examples

see JQueryTabpane for more examples

ENDTABPANE -- ending tag for tabpane widget

This closes a previously opened TABPANE.

TAB -- tab inside a tabpane widget

Defines a tab inside a TABPANE area; must be closed using ENDTAB.

Parameters

ENDTAB -- ending marker for a tab of a tabpane

This closes a previously opened TAB.

JQICON -- render an image

Renders an icon made availabe by the IconService.

Parameters

Example for famfamfam icons:

%JQICON{"tick" alt="alternative content" title="this is a tick icon"}%
%JQICON{"cross"}%
%JQICON{"disk"}%
%JQICON{"star"}%
%JQICON{"lightbulb"}%
%JQICON{"camera"}%
%JQICON{"date"}%
%JQICON{"heart" animate="bounce"}%

Produces:

Example for font-awesome icons:

%JQICON{"fa-pagelines" style="font-size:1em;color:#00BF00"}%
%JQICON{"fa-pagelines" style="font-size:2em;color:#0FAF0F"}%
%JQICON{"fa-pagelines" style="font-size:3em;color:#1F9C1F"}%
%JQICON{"fa-pagelines" style="font-size:4em;color:#2D812D"}%
%JQICON{"fa-pagelines" style="font-size:5em;color:#315C31"}%

Produces:

JQICONPATH -- render the url path to an image icon

This is a shortcut for:

%JQICON{"name" format="$iconPath"}%

Examples

%JQICONPATH{"tick"}% expands to /pub/System/FamFamFamSilkIcons/tick.png

JQPLUGINS -- display a summary of available plugins

Parameters

Examples

 %JQPLUGINS{
   "treeview|slimbox"
   header="   * JQuery Plugins:$n"
   format="      * [[$documentation][$name]] v$version was developed by [[$homepage][$author]]"
 }%

Produces:

• JQuery Plugins:
  • Slimbox v2.05 was developed by Christophe Beyls
  • Treeview v1.4.2 was developed by Joern Zaefferer

JQREQUIRE -- enable a plugin on the current page

This macro will load a list of plugins to be added to the current page. Use JQPLUGINS to display the list of available and active plugins. While loading a plugin, additional plugins it may depend on are loaded as well. Information about these dependencies is stored within the plugins themselves and can't be changed. Dependencies also make sure the javascript code is added to the html page in the right order. It uses ADDTOZONE to aggregate javascript and css at the right place on the html page.

in case of an error JQREQUIRE will produce an inline HTML error message.

Parameters

Examples

• %JQREQUIRE{"easing,sliding,falling"}%

JQTHEME -- switch jQuery UI theme

WARNING: JQuery-UI themes are deprecated since Foswiki-2.1.9. Please don't use this macro anymore.

Foswiki's default UI theme is configured in $Foswiki::cfg{JQueryPlugin}{JQueryTheme} and defaults to foswiki. Use configure to change this site wide. Use JQTHEME if you decide to use a different theme on the current page.

Some Foswiki skins may come with their own jQuery UI matching the overall user experience of the web design.

in case of an error JQTHEME will produce an inline HTML error message.

Parameters

POPUPWINDOW -- opens a topic or url in a new window

Parameters

Examples

• Example with topic link:

  %POPUPWINDOW{"JQueryPlugin" label="Open this topic in a new window"}%

  Generates: Open this topic in a new window
• Example with URL:

  %POPUPWINDOW{url="https://foswiki.org"}%

  Generates: https://foswiki.org
• Enable POPUPWINDOW by writing %JQREQUIRE{"popupwindow"}% on the page

Available jQuery plugins

1. Animate

A cross-browser library of CSS animations.

2. 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.

3. Browser (active)

4. Button (active)

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. 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

6. Comment

7. Configure

8. Cookie

Easy cookie handling using jQuery.

9. Cycle

The jQuery Cycle Plugin is a lightweight slideshow plugin. Its implementation is based on the JQueryInnerFade 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.

10. Debug

Simple jQuery logger / debugger using firebug's console or a div of its own of the form. Useful for JavaScript developers.

11. Easing

Uses the built in easing capabilities added In jQuery 1.1 to offer additional "easing" effects.

12. 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.

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

13. FluidFont

Recompute the font size of an element based on its width.

14. Focus

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

15. FontAwesome (active)

This plugin adds support for the fontawesom icon font. Icons are accessible via the %JQICON macro.

16. 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!

17. 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

18. 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.

19. I18N

This plugin tries to be the simplest possible solution to add internationalization to javascript. It only does message translation reading translations from the backend. It does not cover dates, numbers, gender or pluralization.

20. ImagesLoaded

21. 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.

22. JEditable

The JQuery "JEditable" plugin, packaged for use in Foswiki

23. JsonRpc

24. Loader

This plugin allows to reload parts of a page, either automatically or manually.

25. LocalScroll

This plugin will animate a regular anchor navigation. It will allow your visitors to navigate your site with a smooth scrolling effect.

Each time a link is clicked, the element you decide(can be the whole screen), will gradually scroll to the targeted element, instead of "jumping" as it'd normally do. JQueryScrollTo is used for the animation.

26. 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, Firefox, 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)

27. Masonry

Masonry is a JavaScript grid layout library. It works by placing elements in optimal position based on available vertical space, sort of like a mason fitting stones in a wall. You've probably seen it in use all over the Internet.

28. Metadata

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

29. Migrate (active)

This plugin can be used to detect and restore APIs, features or functionality that have been deprecated in jQuery and removed as of version 1.9. They include:

• jQuery.browser docs
• jQuery.fn.andSelf() docs
• jQuery.sub() docs
• jQuery.fn.toggle() docs (event click signature only)
• "hover" pseudo-event name docs
• jQuery.fn.error() docs
• ajaxStart, ajaxSend, ajaxSuccess, ajaxError, ajaxComplete, ajaxStop global events on non-document targets docs
• Use of attrChange, attrName, relatedNode, srcElement on the Event object (use Event.originalEvent.attrChange etc. instead)
• jQuery.fn.attr() using the pass argument (undocumented)
• jQuery.attrFn object (undocumented)
• jQuery.fn.data() data events (undocumented)
• jQuery.fn.data("events") to retrieve event-related data (undocumented)

See the warnings page for more information regarding messages the plugin generates.

Use %JQREQUIRE{"migrate"}% to load the plugin into the page.

The plugin can be included with versions of jQuery as old as 1.6.4 as a migration tool to identify potential upgrade issues. However, the plugin is only required for version 1.9 or higher to restore deprecated and removed functionality.

See the Upgrade guide for more information.

30. MouseWheel

31. NatEdit

The NatEdit is an wiki editor that helps in learning the TML Language by providing a GUI. By design, this is not a wysiwyg editor that tries to generate the correct TML in the background. Instead, the user is still in charge of writing correct wiki markup but with a bit more of assistance as a plain browser textarea. Therefor this editor helps to lower the learning curve but will not get in your way once you are aware of wiki markup.

32. Observer (active)

33. PNotify

Full featured plugin to show temporary floating messages for status updates, actions and errors.

34. PopUpWindow (active)

Open a page in a new window.

35. QueryObject

This extension creates a singleton query string object for quick and readable query string modification and creation. This plugin provides a simple way of taking a page's query string and creating a modified version of this with little code.

36. Render

This plugin brings modern template based javascript apps to Foswiki based on the libraries by Boris Moore. It is intended to supersede jquery.tmpl. JsRender is a light-weight but powerful templating engine, highly extensible, and optimized for high-performance pure string-based rendering, without DOM or jQuery dependency.

37. ScrollTo

With this plugin, you will easily scroll overflowed elements, and the screen itself. It gives you access to many different options to customize and various ways to specify where to scroll.

See also JQuerySerialScroll, JQueryLocalScroll

38. SerialScroll

This plugin allows you to easily animate any series of elements, by sequentially scrolling them. It uses JQueryScrollTo to achieve the scrolling animation.

39. 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.

40. Slimbox

Show images in a lightbox. Slimbox 2 is a 4 KB visual clone of the popular Lightbox 2 script by Lokesh Dhakar, written using the jQuery javascript library. It was designed to be very small, efficient, standards-friendly, fully customizable, more convenient and 100% compatible with the original Lightbox 2.

41. Sprintf

42. Stars

Flexible and non-obstructive star rating. This plugin turns an HTML <input> element into a star rating widget. The design is heavily influenced by System.JQueryRating by Fyneworks.com bit requries considerably less HTML markup which is of advantage with high precision ratings.

Features:

• arbitrary number of stars
• arbitrary precision of star rating by splitting each star
• mouse wheel support
• non-obstructive integration using CSS and HTML5

43. Subscribe

44. 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.

45. 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 JQueryButton in terms of look & feel.

46. TextboxList

Turns a text input into a list widget with autocompletion. This plugin adds a new formfield type textboxlist to DataForms.

47. TinyMCE

48. 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.

49. Twisty

50. UI

Widget collection for jQuery. This is the official user interface library.

51. UI::Accordion

52. UI::Autocomplete

Autocomplete, when added to an input field, enables users to quickly find and select from a pre-populated list of values as they type, leveraging searching and filtering.

By giving an Autocomplete field focus or entering something into it, the plugin starts searching for entries that match and displays a list of values to choose from. By entering more characters, the user can filter down the list to better matches.

53. UI::Button

54. UI::Datepicker

55. UI::Dialog

A dialog is a floating window that contains a title bar and a content area. The dialog window can be moved, resized and closed with the 'x' icon by default.

If the content length exceeds the maximum height, a scrollbar will automatically appear.

A bottom button bar and semi-transparent modal overlay layer are common options that can be added.

A call to $(foo).dialog() will initialize a dialog instance and will auto-open the dialog by default. If you want to reuse a dialog, the easiest way is to disable the "auto-open" option with: $(foo).dialog({ autoOpen: false }) and open it with $(foo).dialog('open'). To close it, use $(foo).dialog('close').

56. UI::Draggable

57. UI::Progressbar

58. UI::Resizable

59. UI::Slider

60. UI::Spinner

61. UI::Tabs

62. UI::Tooltip

63. Validate

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

64. View

This plugin adds JsViews functionality to the JsRender plugin. JsViews builds off of standard JsRender templates, but adds two-way declarative data-binding, MVVM, and MVP.

See JQueryRender and https://www.jsviews.com/#jsviews for more details.

65. 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.

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.form plugin comes with the following set:

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

There is a Makefile in the /pub/System/JQueryPlugin root directory that ensures 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 required. Enable the {JQueryPlugin}{Debug} flag in configure, to use the uncompressed files right away to omit the make step during development of new 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 exists in the filesystem, then there will be an internal redirect in the server while still enforcing the original mime-type. The browser on the client side will unzip the css and js files automatically. This will drastically reduce bandwidth and speed up interactive performance.

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. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> 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 https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

For Foswiki versions before 1.1, this plugin requires the Foswiki:Extensions.ZonePlugin to be installed. The ZonePlugin is not required for Foswiki 1.1 or later.

Dependencies

Change History