Item9229: jQuery documentation

http://foswiki.org/Development/UsingJQueryWithFoswiki is hard to follow.

It should more clearly distinguish information for administrators from information for "users" (who may be developers). These might go on separate pages.

"Once you have done that, all you need to do is to add the appropriate %JQREQUIRE directive". What directive is that? Much further down this page refers one to the plugin itself, but the plugin refers to this page for documentation! Apparently this is partly attributable to a damaged installation at the site I was using, but still...

What does the jQuery plugin do, from a user viewpoint?

When using jQuery, is there a reason to prefer linking to the version on the wiki rather than the one on jquery's site?

The coding standards section says not to use global $, but to use function($) if one wants to use $ in the usual jQuery way. It is hard to believe that works; wouldn't $ just be unbound? At any rate, I've been using $ as in the standard jQuery docs, seemingly without harm (though it is all nested inside functions inside a "namespace" of a js literal).

The very next paragraph (Shorthands) has a suggestion of using the (apparently global) $. Doesn't that contradict the previous advice?

The foswiki object discussion is cast in terms that are revealed, beneath the table, to be obsolete. That new syntax is apparently foswiki.getPreference('TOPIC'). However, the discussion of ajax queries says to use SCRIPTURL{view}% (note the missing leading %). It is not obvious how or if that can be done with the getPreferences syntax.

It was not obvious to me how to generalize the example in Making a simple query to the server to retrieving an arbitrary file in an abitrary web. The example seems to suggest that the web goes in the 2nd argument to the get function, but when I tried I seemed to need the web in the URL. The example uses the contenttype attribute, while in http://foswiki.org/Support/Question506 Crawford Currie used content_type. Experimentally, ony contenttype worked. Also, does skin of None or text matter?

-- RossBoylan - 30 Jun 2010

Very good points about the doc. Regarding the use of $, it is not good practice to assume this will be an alias to jQuery, as detailed in the jquery docs themselves: http://docs.jquery.com/Using_jQuery_with_Other_Libraries#Overriding_the_.24-function

We do use $('foo') code when writing for Foswiki, but it's inside one of these wrapper blocks that locally aliases jQuery to $.

Just briefly, one should use the wiki's JQueryPlugin because:

• It's probably already being added by your skin; no need to force your user to download jquery twice.
• Provides the %JQREQUIRE{"foo"}% macro
  • Adds a plugin named foo and any dependent .css, other lib dependencies in the correct order to the appropriate part of the rendered HTML: CSS always in the <head>, and .js at the end of the <body> if {OptimizePageLayout] is enabled in configure.
  • Does some basic URI versioning, which is good for managed upgrades of plugins and caching. Eg. if foo is at version 1.2 on the server, the <script src...>= is rendered with a URI that looks like http://....jquery.foo.js?version=1.2 - less chance for a user's browser cache to cause problems with stale files
  • There's a debug mode (set via configure) which will force all the script URIs to use an jquery.foo.uncompressed.js version
• Other Foswiki plugins can easily require your JS code behind-the-scenes in the perl code (ie. without rendering a %JQREQUIRE% macro anywhere into the output)

... and other reasons, probably

-- PaulHarvey - 30 Jun 2010

On the use of $, what confused me was that the documentation seemed to imply I could just put it in a function and things would work. I think the missing piece is that jQuery is passed as an argument to some functions, and one needs to define them with $ as the name of the appropriate argument.

-- RossBoylan - 24 Sep 2010

Michael, any Documentation points here worth picking up? If not please close. Thx.

-- GeorgeClark - 06 Jan 2015

Probably. There are still some areas that need better docu and examples. Please guys, open separate tasks for docu improvements and act upon them.

-- MichaelDaum - 07 Jan 2015

Commenting is disabled while not logged in