%META:TOPICINFO{author="ProjectContributor" comment="save topic" date="1283353795" format="1.1" reprev="9" version="9"}%
%META:TOPICPARENT{name="JQueryPlugin"}%
<!--
Hidden form definition
|*Name*  |*Type*  |*Size*  |*Values*  |*Tooltip message*  |*Attributes*  |
| Example | text | 40 | | | |
-->
<literal>
%JQREQUIRE{"chili"}%
%JQREQUIRE{"autocomplete"}%
</literal>
---+!! %TOPIC%

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
=[[VarINCLUDE][%<nop>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][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:
<verbatim>
%INCLUDE{
 "%SYSTEMWEB%.JQueryAjaxHelper"
 section="topicselector"
 INPUT_NAME="newtopic"
 EXCLUDE="Web*"
}%
</verbatim>

%TOC%

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
<verbatim class="tml">
%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"}%
</verbatim>

---+++ 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
<verbatim class="tml">
%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"}%
</verbatim>

---+++ Example
<form>
<div class="foswikiFormSteps">
<div class="foswikiFormStep">
<h3 >Select a topic:</h3>
%INCLUDE{"%TOPIC%" section="topicselector" INPUT_NAME="newtopic" EXCLUDE="FamFamFamMint*"}%
</div>
</div>
</form>

---++ 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
<verbatim class="tml">
%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"}%
</verbatim>

---+++ Server section
*URL parameters*
   * =q=: search term substring typed so far
   * =limit=: number of search results to return, defaults to 10
<verbatim class="tml">
%STARTSECTION{"web"}%%FLEXWEBLIST{
  include="^%URLPARAM{"q" default="does not exist"}%.*"
  limit="%URLPARAM{"limit" default="10"}%"
  format="<nop>$web"
  separator="$n"
  subheader="$n"
}%%ENDSECTION{"web"}%
</verbatim>

---+++ Example
<form>
<div class="foswikiFormSteps">
<div class="foswikiFormStep">
<h3 >Select a web:</h3>
%INCLUDE{"%TOPIC%" section="webselector" INPUT_NAME="newweb"}%
</div>
</div>
</form>

---++ 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
<verbatim class="tml">
%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"}%
</verbatim>
The following section is used by the section above; it adds a special Javascript function to the page.
<verbatim class="tml">
%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"}%
</verbatim>
---+++ Server section
Uses the =[[#Topic_selector][topic]]= server section, defined above.

---+++ Examples
---++++ Jump to a topic in the current web
<form>
<div class="foswikiFormSteps">
<div class="foswikiFormStep">
<h3 >Local Jump:</h3>
%INCLUDE{"%TOPIC%" section="jumpbox"}%
</div>
</div>
</form>
---++++ Jump to a topic in any web
<form>
<div class="foswikiFormSteps">
<div class="foswikiFormStep">
<h3 >Global Jump:</h3>
%INCLUDE{"%TOPIC%" section="jumpbox" GLOBAL="on" INPUT_NAME="globaljumpbox"}%
</div>
</div>
</form>

---++ User selector 
---+++ Client section
*INCLUDE Parameters*
   * =INPUT_NAME=: name of text input field
   * =INPUT_VALUE=: preselected user
<verbatim class="tml">
%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"}%
</verbatim>
The following section is used by the section above; it adds a special Javascript function to the page.
<verbatim class="tml">
%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"}%
</verbatim>
---+++ Server section
*URL parameters*
   * =q=: search term substring typed so far
   * =limit=: number of search results to return, defaults to 10
<verbatim class="tml">
%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"}%
</verbatim>

---+++ Example
<form>
<div class="foswikiFormSteps">
<div class="foswikiFormStep">
<h3 >Find user:</h3>
%INCLUDE{"%TOPIC%" section="userselector" INPUT_NAME="user" MULTI="true"}%
</div>
</div>
</form>

---++ Query fetcher
Perform a =[[VarQUERY][%<nop>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
<verbatim class="tml">
%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"}%
</verbatim>

---+++ Server section
*URL parameters*
   * =source=: source topic 
   * =query=: query to perform
<verbatim class="tml">
%STARTSECTION{"query"}%%QUERY{
  "%URLPARAM{"query" default="query missing"}%"
  topic="%URLPARAM{"source" default="source missing"
  style="json"}%"
}%%ENDSECTION{"query"}%
</verbatim>

---+++ Example
%INCLUDE{"%TOPIC%" section="queryfetcher" ID="jqQueryExample" SOURCE="%TOPIC%" QUERY="parent.name"}%
<input type="button" id="jqQueryExample" value="Click here" /> to get the parent of this topic asynchronously (should be '%QUERY{"parent.name"}%')

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

---+++ Formfield
Fetch a formfield from a topic asynchronously.
Uses [[VarFORMFIELD][FORMFIELD]], which is deprecated in Foswiki 1.1. Foswiki 1.1 and later should use [[VarQUERY][QUERY]]

*URL Parameters*
   * =source=: source topic 
   * =formfield=: name of formfiled to retrieve

---++++ Server section
<verbatim class="tml">
%STARTSECTION{"formfield"}%%FORMFIELD{
  "%URLPARAM{"formfield" default="does not exist"}%"
  topic="%URLPARAM{"source" default="does not exist"}%"
}%%ENDSECTION{"formfield"}%
</verbatim>

---+++ User photo
This one returns an =&lt;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
<verbatim class="tml">
%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"}%
</verbatim>

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

<verbatim class="tml">
%STARTSECTION{"expand"}%%EXPAND{"$percnt%URLPARAM{"expression"}%$percnt" scope="%URLPARAM{"scope" default="%BASEWEB%.%BASETOPIC%"}%"}%%ENDSECTION{"expand"}%
</verbatim>

---++ 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][user selector]] server section.
<verbatim class="tml">
%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"}%
</verbatim>

%META:FORM{name="JQueryAjaxHelper"}%
%META:FIELD{name="Example" attributes="" title="Example" value="example field value"}%
