You are here: Foswiki>System Web>JQueryPlugin>JQueryAjaxHelper (01 Sep 2010, ProjectContributor)EditAttach

JQueryAjaxHelper

This page contains is a set of example JQueryPlugin helpers that can be used in wiki applications. The examples demonstrate how you can dynamically populate jquery.autocomplete enabled input boxes.

Examples are in two parts; a Client section and a Server section. The Client section is designed to be included into your topics using %INCLUDE. The Server section is expanded in response to an AJAX request from a jQuery plugin.

This page also acts as a library of some commonly-used form inputs. For example, the Topic selector example can be used in your own topics to define an HTML form input with the name newtopic by putting this in your topic:

%INCLUDE{
 "%SYSTEMWEB%.JQueryAjaxHelper"
 section="topicselector"
 INPUT_NAME="newtopic"
 EXCLUDE="Web*"
}%

Note that the examples below are implemented using base Foswiki functionality. There are a range of plugins, such as Foswiki:Extensions.RenderPlugin, Foswiki:Extensions.FlexWebListPlugin and Foswiki:Extensions.DBCachePlugin that can be used to simplify or improve these sections when building up your own library of input types. Some examples of the use of these plugins are given at the end of this topic.

Topic selector

Select a topic in the current web. jquery.autocomplete is given a url that loads the topic section of this topic, which expands to the topic list.

Client section

INCLUDE Parameters

INPUT_NAME: name (and id) of HTML input field
INPUT_VALUE: preselected value
EXCLUDE: exclude expression to filter out unwanted topics, see the excludetopic parameter in VarSEARCH

%STARTSECTION{"topicselector"}%<!-- topicselector  -->
<input type="text" class="foswikiInputField" name="%INPUT_NAME%" id="%INPUT_NAME%" autocomplete="%SCRIPTURL{"view"}%/%SYSTEMWEB%/JQueryAjaxHelper?section=topic;skin=text;baseweb=%BASEWEB%;%IF{"defined EXCLUDE" then="exclude=%EXCLUDE%"}%" size="60" value="%IF{"defined INPUT_VALUE" then="%INPUT_VALUE%"}%" />
<!-- //topicselector -->%ENDSECTION{"topicselector"}%

Server section

URL parameters

q: search term substring typed so far
limit: number of search results to return, defaults to 10
baseweb: the web where to search for topics
format: format of returned values, defaults to $topic
exclude: exclude expression to filter out unwanted topics

%STARTSECTION{"topic"}%%SEARCH{
  "^%URLPARAM{"q" default="does not exist"}%.*"
  type="regex"
  scope="topic"
  format="<nop>%URLPARAM{"format" default="$topic"}%"
  separator="$n"
  limit="%URLPARAM{"limit" default="10"}%"
  nonoise="on"
  excludetopic="%URLPARAM{"exclude"}%"
  web="%URLPARAM{"baseweb" default="%BASEWEB%"}%"
}%%ENDSECTION{"topic"}%

Example

Web selector

Select from a list of webs, using jquery.autocomplete.

Note: there is currently no way to filter a list of webs in the default Foswiki core. To use this example you will have to install Foswiki:Extensions.FlexWebListPlugin.

Client section

INCLUDE Parameters

INPUT_NAME: name of text input field
INPUT_VALUE: preselected value

%STARTSECTION{"webselector"}%<!-- webselector  -->
<input type="text" class="foswikiInputField {matchCase:true}" name="%INPUT_NAME%" id="%INPUT_NAME%" autocomplete="%SCRIPTURL{"view"}%/%SYSTEMWEB%/JQueryAjaxHelper?section=web;skin=text;%IF{"defined EXCLUDE" then="exclude=%EXCLUDE%"}%" size="60" value="%IF{"defined INPUT_VALUE" then="%INPUT_VALUE%"}%" />
<!-- //webselector -->%ENDSECTION{"webselector"}%

Server section

URL parameters

q: search term substring typed so far
limit: number of search results to return, defaults to 10

%STARTSECTION{"web"}%%FLEXWEBLIST{
  include="^%URLPARAM{"q" default="does not exist"}%.*"
  ignorecase="on"
  limit="%URLPARAM{"limit" default="10"}%"
  format="<nop>$web"
  separator="$n"
  subheader="$n"
}%%ENDSECTION{"web"}%

Example

Jump box

Jump to specific topics.

Client section

INCLUDE Parameters

INPUT_NAME: name of text input field, defaults to jumpbox
GLOBAL: toggle search for topics in all webs on/off, defaults to off

%STARTSECTION{"jumpbox"}%<!-- jumpbox -->
<input type="text" class="foswikiInputField jqJumpBox {%IF{
  "$GLOBAL = 'on'"
  then="global: true, baseweb:'all', format:'$web.$topic'"
  else="global: false, baseweb:'%BASEWEB%', format:'$topic'"
}%}" name="%IF{"defined INPUT_NAME" then="%INPUT_NAME%" else="jumpbox"}%" autocomplete="off" size="60" />
%ADDTOZONE{"script"
  tag="jumpbox::js"
  section="jumpbox::js"
  requires="JQUERYPLUGIN::AUTOCOMPLETE"
}%
<!-- //jumpbox -->%ENDSECTION{"jumpbox"}%

The following section is used by the section above; it adds a special Javascript function to the page.

%STARTSECTION{"jumpbox::js"}%<literal>
<script type="text/javascript">
jQuery(function($){
  $(".jqJumpBox").each(function() {
    var $this = $(this);
    var opts = $.extend({}, $this.metadata());
    $this.autocomplete(
      "%SCRIPTURL{"view"}%/%SYSTEMWEB%/JQueryAjaxHelper?section=topic;skin=text"+
      ";baseweb="+opts.baseweb+
      ";format="+opts.format
    ).result(function(event, item) {
      window.location.href="%SCRIPTURLPATH{"view"}%/"+(opts.global?'':opts.baseweb+'/')+item;
    });
  });
});
</script>
</literal>%ENDSECTION{"jumpbox::js"}%

Server section

Uses the topic server section, defined above.

Examples

Jump to a topic in the current web

Jump to a topic in any web

User selector

Client section

INCLUDE Parameters

INPUT_NAME: name of text input field
INPUT_VALUE: preselected user

%STARTSECTION{"userselector"}%<!-- userselector -->
<input type="text" class="foswikiInputField jqUserSelector" name="%INPUT_NAME%" id="%INPUT_NAME%" autocomplete="off" size="60" value="%IF{"defined INPUT_VALUE" then="%INPUT_VALUE%"}%" />
%ADDTOZONE{"script"
  tag="userselector::js"
  section="userselector::js"
  requires="JQUERYPLUGIN::AUTOCOMPLETE"
}%
<!-- //userselector -->%ENDSECTION{"userselector"}%

The following section is used by the section above; it adds a special Javascript function to the page.

%STARTSECTION{"userselector::js"}%<literal>
<script type="text/javascript">
jQuery(function($){
  $(".jqUserSelector").each(function() {
    var $this = $(this);
    var opts = $.extend({
      autoFill:false,
      selectFirst:false,
      scrollHeight:250,
      formatItem: function(row, index, max, search) {
        return "<table width='100%'><tr><td width='60px'><img width='50' src='"+row[2]+"' /></td><td>"+row[0]+"<br />"+row[1]+"</td></tr></table>";
      }
    }, $this.metadata());
    $this.autocomplete(
      "%SCRIPTURL{"view"}%/%SYSTEMWEB%/JQueryAjaxHelper?section=user;skin=text", 
      opts
    );
  });
});
</script>
</literal>%ENDSECTION{"userselector::js"}%

Server section

URL parameters

q: search term substring typed so far
limit: number of search results to return, defaults to 10

%STARTSECTION{"user"}%%SEARCH{
   "^%URLPARAM{"q" default="does not exist"}%.*"
   type="regex"
   scope="topic"
   format="$percntUSERINFO{\"$topic\" format=\"<nop>$dollarwikiname|$dollaremails|$percntFORMFIELD{\"Photo\" topic=\"$web.$topic\" default=\"%PUBURLPATH%/%SYSTEMWEB%/JQueryPlugin/images/nobody.gif\" alttext=\"%PUBURLPATH%/%SYSTEMWEB%/JQueryPlugin/images/nobody.gif\"}$percnt$n\"}$percnt"
   separator=""
   limit="%URLPARAM{"limit" default="10"}%"
   nonoise="on"
   web="%USERSWEB%"
}%%ENDSECTION{"user"}%

Example

Query fetcher

Perform a %QUERY asynchronously (requires Foswiki 1.1 or later).

Client section

INCLUDE Parameters

ID: id of an element to bind an onclick event to
SOURCE: topic to get the field from
QUERY: query to perform

%STARTSECTION{"queryfetcher"}%<literal>
%ADDTOZONE{"script"
  tag="query::js"
  requires="JQUERYPLUGIN"
  text ="
<script type=\"text/javascript\">
jQuery(function($){
  $(\"#%ID%\").click(function() {
     $.get(\"%SCRIPTURL{"view"}%/%SYSTEMWEB%/JQueryAjaxHelper?section=query;source=%SOURCE%;query=%QUERY%;skin=text\",
         function(data) {
             // This is the function that will be executed when the
             // data is fetched
             alert(\"Value is '\" + eval(data) + \"'\");
         });
  });
});
</script>
"}%
</literal>%ENDSECTION{"queryfetcher"}%

Server section

URL parameters

source: source topic
query: query to perform

%STARTSECTION{"query"}%%QUERY{
  "%URLPARAM{"query" default="query missing"}%"
  topic="%URLPARAM{"source" default="source missing"
  style="json"}%"
}%%ENDSECTION{"query"}%

Example

to get the parent of this topic asynchronously (should be 'JQueryPlugin')

Other selectors

Server sections for some other selectors that are common in wiki applications.

Formfield

Fetch a formfield from a topic asynchronously. Uses FORMFIELD, which is deprecated in Foswiki 1.1. Foswiki 1.1 and later should use QUERY

URL Parameters

source: source topic
formfield: name of formfiled to retrieve

Server section

%STARTSECTION{"formfield"}%%FORMFIELD{
  "%URLPARAM{"formfield" default="does not exist"}%"
  topic="%URLPARAM{"source" default="does not exist"}%"
}%%ENDSECTION{"formfield"}%

User photo

This one returns an <img...> to a user's photo. See the User selector example above.

URL Parameters

name: name of user
height: image height, defaults to 50

Server section

%STARTSECTION{"userphoto"}%<img src='%FORMFIELD{"Photo" topic="%USERINFO{"%URLPARAM{"name" default="does not exist"}%" format="$wikiusername"}%" default="%PUBURLPATH%/%SYSTEMWEB%/JQueryPlugin/images/nobody.gif" alttext="%PUBURLPATH%/%SYSTEMWEB%/JQueryPlugin/images/nobody.gif"}%' alt='%URLPARAM{"name"}%' height='%URLPARAM{"height" default="50"}%' />%ENDSECTION{"userphoto"}%

Expand TML

expand a TML expression in the given scope

Server section

URL parameters

expression: TML to be evaluated; will be wrapped into %...% before executing it
scope: optionally defines the topic within which the expression is expanded

%STARTSECTION{"expand"}%%EXPAND{"$percnt%URLPARAM{"expression"}%$percnt" scope="%URLPARAM{"scope" default="%BASEWEB%.%BASETOPIC%"}%"}%%ENDSECTION{"expand"}%

Example extension based implementations

The following implementations of some of the server sections depend on the installation of optional extensions.

`user_fast`

Foswiki:Extensions.DBCachePlugin implementation of the user selector server section.

%STARTSECTION{"user_fast"}%%DBQUERY{
   "uc(topic) =~ uc('^%URLPARAM{"q" default="does not exist"}%')"
   format="$percntUSERINFO{\"$topic\" format=\"<nop>$dollarwikiname|$dollaremails|$expand(Photo or '%PUBURLPATH%/%SYSTEMWEB%/JQueryPlugin/images/nobody.gif')$n\"}$percnt"
   separator=""
   limit="%URLPARAM{"limit" default="10"}%"
   web="%USERSWEB%"
}%%ENDSECTION{"user_fast"}%