%META:TOPICINFO{author="ProjectContributor" date="1276070380" format="1.1" reprev="1.1" version="1.1"}%

HijaxPlugin

AJAX integration

This plugin offers a simple way of using the foswiki scripts, including Oops, Login to authenticate and Strikeone Validation handling, via an AJAX interface. It makes sure that certain params persist regardless of what happens in the data flow, i.e. with cover=ajax the completePageHandler can parse the relevant content into a JSON string that the client-side js can make unambiguous sense of. So, if an OopsException is thrown, for example, that can also be returned as JSON which the js waiting on the other side of the originating ajax call can present to the user as an error because the context variable is set as oops and the content variable contains the error message. Likewise, if a redirect to login is made, the login form is presented and hijaxed for submission over ajax.

It uses the redirectCgiQueryHandler so it'll only work if there are no other plugins earlier in the alphabet that also use the redirectCgiQueryHandler This needs to be updated to remove the use of this deprecated handler.

How does it work?

It uses a simple ajax COVER that wipes the entire page but puts %TMPL:DEF{}% templates like content in tags that a completePageHandler can parse out and return to the client in a JSON object. Using COVER also means that VIEW_TEMPLATES are inherently respected.

Associated parameters

By default there are certain parameters that are always returned in the JSON object:

• location contains the complete url of the returned page,
• head and body contain the respective ADDTOZONE content,
• context is the script of the returned page.

There are two multiple parameters that refer to templates that you want to be returned to the browser. These are:

• tmplp - this refers to %TMPL:DEF{}% templates that are parsed out when the skin template is read, i.e. common to each page. By default, content is always returned unless it hasn't been specifically requested and another tmplp or hijax has been requested. The view.ajax.tmpl cover also has templates that are available for request: revisions, queryparamstring, revarg and revtitle because these are handled by the view script only and are not part of the main rendering task.
• hijax - this refers to user defined templates that contain TML that is intended to work with the current %BASEWEB%, %BASETOPIC% etc. There is an example of this in the HijaxPluginTemplate topic. hierarchy is used by the HierarchyBuilder application which is included in the download as a demonstration of the HijaxPlugin.

You can define additional templates to be referenced by the above parameters in the UserHijaxTemplate topic. This needs to be created by you.

• Define tmplp relevant templates with the following syntax:

%TMPL:DEF{"usertmplptemplates"}%
%TEMPLATE:<name1>%
%TMPLP:P{<name1>}%
%TEMPLATE:<name2>%
%TMPLP:P{<name2>}%
%TEMPLATE:<name3>%
%TMPLP:P{<name3>}%
...
%TMPL:END%

• hijax relevant templates just need to be wrapped in %TMPL:DEF{}%%TMPL:END%

returntemplate is the third associated parameter. If this is set and it's not an oops script and there's no redirect cache, the redirectCgiQueryHandler adds template= to the url. There is a nocontent template provided which wipes out the content and ajaxhead templates for performance purposes, e.g. you're saving an %ACTION{}% to your action list topic and you only want to know that it worked, i.e. a redirect to the view script, you don't want the core to put effort in to parsing all those actions so you use this flag.

The hijax.js javascript

By default, every native link on the page that does not have the nohijax class is given a hoverIntent event so that when hovering over it with intent a small menu customised to the href of the link appears above it with options to Preview, Raw edit, Raw view, History and Create new topic. Clicking on one of these menu links triggers the request over ajax and presents the result in a jQuery UI Dialog: for each page the HijaxPlugin defines two jQuery UI Dialogs, one for oops responses and one for all other responses (excl. login responses which always get their own dialog). The response dialog maintains a history which can be traversed via the Forward and Back buttons, and the page being currently viewed in the dialog can be launched to its own tab/window via the Launch button.

Note that if the link being hovered over has parameters, then only the option to Preview is presented.

HTML select elements with the class 'userlist' are sorted into alphabetical order by default.

A slightly customised version of the jQuery Supersleight plugin is provided and used to handle png images in IE6. DOM elements with the 'nossleight' class are skipped by default.

Customisation

The hijax menu, the CSS selector of the links not to hijax and the jQuery selector of the DOM elements containing png's that need to be fixed in IE6 are all defined in HijaxPluginTemplate and can be customised in UserHijaxTemplate.

What else can I do with it?

A suite of javascript helper functions are also provided as part of the foswiki.HijaxPlugin object.

• serverAction : can be considered almost as a 1:1 drop in replacement for the jQuery $.ajax() function in your code. It handles login, oops and validate (strikeone) responses. The arguments it accepts as part of a javascript object are:
  • async: default true,
  • cache: default false,
  • dataType: default "json",
  • type: default "POST",
  • url: the foswiki url you want to call over ajax,
  • data: the params to the url, can be as a javascript object or as a jQuery .serialize() string. serverAction ensures that the cover parameter contains 'ajax'. If a .serialize() string is passed in, it gets objectified, checked, and rejoined into a string. To avoid the objectify step, it is recommended to use the HijaxPlugin asObject function which takes a jQuery selection as its arguement.
  • loading: a jQuery identifier of the DOM element over which a spinner will appear during the ajax request, default is the browser window,
  • nooverlay: set to true to prevent an opaque overlay during the ajax request, default false,
  • success: the function to execute upon a successful foswiki action, i.e. not an oops . The JSON object is passed as the only argument.
  • error: the function to execute on an oops response but be careful because an oops is not always an error is Foswiki . The JSON object is passed as the only argument.
  • target and targetmethod: these are related parameters and are relevant when there has been a successful foswiki action and you want to add the response to the page. See their descriptions under loadContent below. Note that if a target as well as a success function are specified, then both are executed.
• showResponse : this is the function used by hijax as the success action passed into serverAction . See the description above.
• showOops : this is the function used by hijax to present an oops response to the user. See the description above.
• loadContent : this is the low-level function used by showResponse and showOops . It takes three arguments:
  • response: if this is an object it is assumed to be the JSON object returned by the HijaxPlugin on the server and used to retrieve the content parameter, and the head and body parameters (from ADDTOZONEs). Each element of the head and body content is checked, if it is inline css or js it gets added to the respective zone, and if it is a file, it is checked to see if it is already on the page and added if not. response can also be a string.
  • $target: this is a jQuery identifier of the DOM element that should contain the response,
  • method: this is the jQuery method for how the response should be added to the $target: 'replaceWith', 'append', 'prepend' or 'html'. Default is html .
• sortUserlists : alphabetically sorts select elements that have the class 'userlist'.
• parseURL : this is a customisation of a function by James Padolsey. As well as exposing the usual elements of a URL in a js object it also exposes the Foswiki relevant web, topic and script.

See the hijax.js file for further comments and functions. Lots of code examples can be found in the javascript of the FullCalendar and Object plugins.

The %RAND% macro

This provides a random integer from the base 999999. With elements being incrementally added to a page via ajax, applications can use this as a way of having a simple unique identifier.

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.

Info

Plugin Author:	Foswiki:Main.DavidPatterson
License:	GPL (GNU General Public License)
Release:	1.2
Version:	8534 (2010-08-18)
Change History:
17 Aug 2010:	problem with JQueryPlugin compatibility so moved addDefaultsToPage out of init into commonTagsHandler
06 Aug 2010:	javascript framework added to help using Foswiki over ajax, hijax.js
15 Apr 2010:	quick fix to make it work - was trying to get query params from the response object
25 Nov 2009:	initial release
Dependencies:	Name Version Description JSON >=2.21 Required. JSON::XS >=2.29 Recommended for performance. Foswiki::Plugins::JQueryPlugin >=3.51 Required.
Home:	Foswiki:Extensions/HijaxPlugin
Support:	Foswiki:Support/HijaxPlugin