JQueryPlugin < System

---+!! %TOPIC%
<!--
   * Set SHORTDESCRIPTION = jQuery <nop>JavaScript library for Foswiki
-->
%SHORTDESCRIPTION%

%TOC%

---++ Description
<blockquote>
"jQuery is a fast, concise, <nop>JavaScript Library that simplifies how you traverse
HTML documents, handle events, perform animations, and add Ajax interactions to
your web pages."
</blockquote>

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 [[#Macros][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 %SYSTEMWEB%.JQueryMetadata for an example.

Use [[#VarJQREQUIRE][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 [[%SCRIPTURLPATH{"configure"}%][configure]]. 

Those plugins coming with their own [[#Macros][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 %SYSTEMWEB%.JQueryCodingStandards.

---++ jQuery References and tutorials
   * [[http://learn.jquery.com/about-jquery/how-jquery-works/][How jQuery Works]]
   * [[http://http://learn.jquery.com/][jQuery Learning Center]]
   * [[http://api.jquery.com/][jQuery API Documentatiom]]
   * [[http://jqapi.com][Alternative jQuery Documentation and API Browser]]
   * [[http://learn.jquery.com/using-jquery-core/avoid-conflicts-other-libraries/][Avoiding Conflicts with Other Libraries]]
   * [[http://plugins.jquery.com/][The jQuery Plugin Registry]]

---++ Macros

%INCLUDE{"VarBUTTON"}%

%INCLUDE{"VarTABPANE"}%
%INCLUDE{"VarENDTABPANE"}%

%INCLUDE{"VarTAB"}%
%INCLUDE{"VarENDTAB"}%

%INCLUDE{"VarJQICON"}%
%INCLUDE{"VarJQICONPATH"}%

%INCLUDE{"VarJQPLUGINS"}%
%INCLUDE{"VarJQREQUIRE"}%
%INCLUDE{"VarJQTHEME"}%

%INCLUDE{"VarPOPUPWINDOW"}%

---++ Available jQuery plugins
%JQPLUGINS{
  format="---+++ $index. $percntIF{\"istopic '$documentation'\" 
                  then=\"[[$documentation][$name]]\" 
                  else=\"<nop>$name\"
               }$percnt $active
          $summary
  "
}%

---++ 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 %PUBURLPATH%/%SYSTEMWEB%/JQueryPlugin/plugins/form/jquery.form.uncompressed.js
   1 %PUBURLPATH%/%SYSTEMWEB%/JQueryPlugin/plugins/form/jquery.form.js
   1 %PUBURLPATH%/%SYSTEMWEB%/JQueryPlugin/plugins/form/jquery.form.js.gz

There is a Makefile in the =%PUBURLPATH%/%SYSTEMWEB%/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:
<verbatim>
  <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>
</verbatim>

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

<blockquote class="foswikiHelp"> %X% 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.</blockquote>

---++ Plugin Info
|  Maintainer(s): | Michael Daum |
|  Copyright: | 2007-2013 Foswiki Contributors http://foswiki.org |
|  License: | GPL |
|  Release: | 4.91 |
|  Version: | 4.91 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  08 Nov 2013: | (4.91) - Release with Foswiki 1.1.9 \
                  Item12650: Add config error for removed Themeswitcher plugin |
|  23 Oct 2013: | (4.90) - Item12567: fix checking of version number in configure \
                  Item12577: deprecate jquery-tooltip in favour of jquery-ui-tooltip \
                  Item12596: improve documentation of jquery-ui \
                  Item12583: revert version string to simple float not to break installation on RHEL and SLES \
                  Item12599: use jQuery-1.9x (not 2.0.x) for IE9 \
                  Item12600: various minor changes to jquery components |
|  12 Oct 2013: | (4.83) - Item12567: fix version check in =configure= (not released) | 
|  07 Jun 2013: | (4.82) - Item12528: fixed char mapping in jquery.wikiword |
|  31 May 2013: | (4.81) - Item12520: added jquery-1.10.1 and jquery-2.0.2 |
|  30 May 2013: | (4.80) - Item12519: upgraded superfish, supersubs and hoverintent |
|  29 May 2013: | (4.70) - Item12345: added jquery-1.9.1, jquery-1.10.0, jquery-2.0.0, jquery-2.0.1; \
                           removed themeswitcher as it isn't supported and non-functional anymore; \
                           upgraded to jquery-ui-1.10.3; \
                           upgraded form, rating, masonry, blockui, scrollto;\
                           removed warning in configure about chilli |
|  15 Jan 2013: | (4.60) - Item12345: added jquery-1.8.3, upgraded pnotify, masonry, scrollto, form, blockui, cycle |
|  11 Dec 2012: | (4.50) - Item12229: improved transliteration of unicode characters in jquery.wikiword |
|  28 Nov 2012: | (4.45) - Release with Foswiki 1.1.6 <br />\
                  Item12192: Fix some layout issues<br />\
                  Item12214: default jquery-ui theme overrides manual JQTHEME choice.<br />\
                  Item12215: Hide JQLoader using CSS. |
|  26 Oct 2012: | Item12195: Default jquery version is jquery-1.8.2 now |
|  24 Oct 2012: | Item12190: Chili enabled by default,  warning demoted to a note. |
|  17 Oct 2012: | (4.44) - Item12048: upgraded to jquery-ui-1.8.23; added jquery-1.8.2 |
|  11 Jul 2012: | (4.43) - Item11993: upgraded JQueryLiveQuery to 1.3.1 ; reworked documentation and examples; %BR% \
                  Item11175: upgrade JQueryValidate to 1.9.0; %BR% \
                  Item11994: upgraded JQueryUI to 1.8.21 |
|  09 Jul 2012: | (4.42) - Item11742: removed all jquery prior to 1.7.1 |
|  01 Jun 2012: | (4.42) - Item11917: simplemodal updated to 1.4.2. fixed upstream bug computing dialog heights |
|  23 May 2012: | (4.41) - Item11889: \
                  added means to hide the close button on textboxlist values; \
                  docu improvements to textboxlixst and pnotify | 
|  10 Apr 2012: | (4.40) - Item11397, Item11742: \
                  use a JSON instead of &lt;meta> to export preferences to javascript; \
                  add jquery-1.7.2 (new default); \
                  deprecate all jquery versions prior to 1.7.1 \
                  improve docu and integration of scrollto and serialscroll; \
                  removed deprecated foswiki.web, foswiki.topic etc properties |
|  06 Apr 2012: | (4.33) - Item11511, Item11512:  Minor changes to improve JSON output and Javascript validations.%BR%\
                   Item11685: deprecate simmplemodal, replace by jquery.ui.dialog.%BR%\
                   Item11654: JQueryTmpl is discontinued upstream.%BR%\
                   Item11383: Document jqUIDialogSubmit.%BR%\
                   Item10383: !JQuerySimpleModal sample window isn't displayed properly. |
|  20 Dec 2011: | (4.32) - re-release Foswiki 1.1.4 - Item11335 revert spinner changes, Item11371 - close suggestions list. |
|  12 Dec 2011: | (4.31) - Foswiki 1.1.4 Release. Item11335 JQueryAjaxHelper examples don't work reliably. |
|  22 Nov 2011: | (4.30) added jquery-1.7 and jquery-1.7.1; \
                  added jquery.loader to ease loading sections asynchronously |
|   3 Dec 2011: | (4.22) Incremented version for Foswiki 1.1.4 release. Minor code and documentation cleanup. |
|  22 Nov 2011: | (4.21) added config warnings for the deprecated JQuery plugins; \
                  and a warining for Chili highlighter corruption; \
                  fixed jquery.chili to allow other non-recipe css classes in verbatim sections; \
                  fixed jquery.cookie to return undefined instead of an empty Object when asking for an unknown cookie; \
                  fixed <nop>JQueryAjaxHelper's =users= backend to return users and groups \
                  improved jquery-ui-dialog integration |
|  26 Oct 2011: | fixing compatibility of jquery.media with newer jqueries; \
                  fixed placement of jquery.tooltips when viewport at right bottom;\
                  fixed jquery.superfish's index related to jquery.ui.dialog's; \
                  improved jquery.button click usability; \
                  improved and documented integration of jquery.ui.dialog; \
                  fixed jquery.ui.resizable to init array objects correctly |
|  08 Sep 2011: | (4.20) added perl api to make ui themes pluggable; \
                  upgrade to jquery-ui 1.8.16, masked-input 1.3, masonry 2.0, textboxlist 1.0, validate 1.8.1, cycle 2.9995, bgiframe 2.1.2, blockUI 2.39, corner 2.12, gradient 1.0, \
                  autocomplete 1.2.2, form 2.80; \
                  upgraded all jquery-ui themes to match the latest version; \
                  deprecated abandoned jquery.autocomplete in favor of jquery-ui's autocomplete; \
                  added modules ui::accordion, ui::autocomplete, ui::button, ui::datepicker, ui::dialog, ui::draggable, ui::progressbar, ui::resizable, ui::slider, ui::tabs; \
                  improved rating formfield to display the actual value as well, not only the stars; \
                  added initializer for jquery.validate; \
                  improved initializer for simplemodals to make them draggable and resizable; \
                  fixed css of treeview, autocomplete, tabpane, button; \
                  new foswiki jquery-ui theme; \
                  added jquery-1.6.2 and jquery-1.6.3; \
                  improved docu of jquery.cycle, jquery.masonry, jquery.validate |
|  20 Jun 2011: | (4.11) Fix "Use of uninitialized" in textboxlist |
|  25 May 2011: | (4.10) Added JQueryPlaceholder; \
                  Updated jquery.autocomplete to work around Firefox 4 problem breaking up/down arrow keys in edit fields; \
                  Added jquery.tmpl; \
                  Updated jquery.metadata to support html5 attributes; \
                  Updated jquery.validate to 1.8.0; \
                  Added jquery-1.5.[0-2] and jquery-1.6.1; \
                  Implemented history support for jquery.tabpane; \
                  Updated jquery.media and added more skins to the swf player; \
                  Fixed jquery.shake to work with elements positioned relatively; \
                  Adding context variables for all enabled jQuery modules; |
|  11 Apr 2011: | (4.03) jQuery default corrected to be 1.4.3. \
                  Fixed syntax for accessing meta variables. \
                  Improved iterating hash. \
                  Updated forms jq plugin from 2.25 to 2.43. \
                  Removed useless BOM code from blockUI. \
                  Compress using utf8 encoding by default\
                  This version is shipping with Foswiki 1.1.3 |
|  21 Feb 2011: | (4.02) cleaned up and documented the process for adding new plugins |
|  02 Feb 2011: | (4.01) added pnotify, configure checker to check that \
                  configured ={JQueryVersion}= is sane |
|  13 Dec 2010: | (4.00) adding jquery-1.4.2/3/4 (default is 1.4.3); \
                  removing jquery-1.2.6, deprecating jquery-1.3.x (incompatible with shipped jquery-ui); \
                  upgraded to jquery-ui 1.8.5 (needs jquery-1.4+); \
                  upgraded jquery-cookie; \
                  added themeswitcher; \
                  fixed spinner in autocomplete; \
                  various fixes to jquery.tooltip; \
                  improved tooltip themes (added blackbox theme); \
                  fixed rating formfield; \
                  improved printout of tabpanes; \
                  added new jquery-ui theme flickr; \
                  update forms plugin to 2.49 to improve jQuery 1.4 compatibility |
|  27 Oct 2010: | (3.75) fixed IE error in chili recipe for TML |
|  19 Oct 2010: | (3.74) Version included with Foswiki 1.1.0 + fix for code bug in SLIMBOX causing !ImageGalleryPlugin to fail |   
|  19 Aug 2010: | (3.71) JQueryLiveQuery now loads by default; \
                  removed JQueryBgiframe and JQueryEasing plugins from default plugins |
|  02 Jul 2010: | (3.70) removed outdated spinner and ifixpng plugins; \
                  improved documentation; \
                  fixed IE error in treeview; \
                  added post method to async mode of treeview; \
                  moved %CLEAR to %SYSTEM.DefaultPreferences |
|  28 May 2010: | (3.60) removed pointless TOGGLE module; \
                  reworked handling of =meta= tags by merging =foswikilibs.js= with =jquery.foswiki= module; \
                  fixed IE7 error with floats inside tabpanes; \
                  added ajax handler to query foswiki preferences async-ly |
|  30 Apr 2010: | (3.51) fixed initial classes of click-areas in treeviews |
|  29 Mar 2010: | (3.42) disable plugin when prerequisites are not met |
|  28 Mar 2010: | (3.41) fix ZonePlugin listed as optional dependency (not optional for Foswiki 1.0.x installations) |
|  26 Mar 2010: | (3.40) externalized grid and fullcalendar modules into plugins of their own; upgraded to jquery-ui 1.7.2; only load i18n support matching the current site language |
|  20 Mar 2010: | (3.31) Minifier CPAN libs removed from plugin. They will be in core CPAN lib in Foswiki 1.1 |
|  14 Mar 2010: | (3.30) upgraded =validate= to v1.7; added =wikiword= validation method; \
                  fixed computation of line-height in =fluidfont=; \
                  fixed height issue in =tabpane= |
|  03 Mar 2010: | made !ZonePlugin an optional dependency |
|  01 Mar 2010: | improved js and css compression using yuicompressor; \
                  improved simplemodal integration to foswiki to create modal dialogs with less additional javascript; \
                  added custom events to textboxlist: <nop>AddValue, <nop>DeleteValue , Reset and Clear |
|  12 Feb 2010: | added livequery and rewrote all initializers to use it; \
                  added =rating= formfield type; \
                  updated jqGrid to latest version; \
                  improved foswiki integration and documentation of various plugins; \
                  upgraded jwplayer coming with media plugin; \
                  using Foswiki:Extensions/ZonePlugin now to optimize page load time |
|  08 Feb 2010: | added query-object |
|  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 %SANDBOXWEB% to %SYSTEMWEB% |
|  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 <nop>JQueryPlugin <nop>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 <nop>FamFamFamContrib) |
|  15 Jan 2009: | fixed click target for relative urls in %<nop>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: | <table class="foswikiTable" border="1"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">Foswiki::Plugins::ZonePlugin</td><td align="left">&gt;=3.1</td><td align="left">Required. required for Foswiki < 1.1</td></tr></table> |
|  Home: | Foswiki:Extensions/%TOPIC% |
|  Support: | Foswiki:Support/%TOPIC% |
This topic: System > JQueryPlugin
Topic revision: revision 6 (raw view)
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback