RenderPlugin

Render WikiApplications asynchronously

Description

This plugin implements three simple REST handlers to get content from Foswiki. For example, these can be used to easily replace a server-side INCLUDE with a functional equivalent using an ajax call to one of these REST handlers.

This comes in handy to asynchronously load content in a tabbed interface, loading subsequent content for a treeview, a menu widget, or tooltips.

You may also use it to just render a snippet of TopicMarkup on the server and return a HTML preview back to the browser.

The REST handlers of this plugin have been designed to be rather generic. So, besides some very basic parameter checking, most error handling is up to the callback analysing the return value of the REST handler. The main purpose is best described as being an intermediate transport device.

Compare this to other plugins that implement more specific REST handlers. As such, they are rather tailored to one specific service and thus will be dealing with error cases on the server side in much more detail.

The advantage of using this plugin's REST handler is that you don't have to implement service backends using perl. Instead, you can write TopicFunctions that contain the WikiApplication to be executed when it is called by an appropriate ajax request. This basically is the client side equivalent of a parametrized INCLUDE, as it is used on server side WikiApplications (see examples below).

Syntax

The available REST handlers are:

Handler	Parameters	Description
expand	text	expands common variables in the submitted text fragment, filename
render	text	same as expand but also renders TopicMarkup converting it to HTML
tag	name, param, *, render, filename	this is a convenience function to expand one specific variable instead of having to build up a snippet of code that you want to expand or render; The param parameter specifies the default parameters to this tag; the named-params are additional named parameters; the render flag indicates if the result is to be expanded only or if it should be renderd into HTML; default is off, that is only expand common tags but don't interpret TopicMarkup
template	name, expand, render, filename	this handler loads the template name and expands the macro given in expand; the render flag indicates whether the result is to be rendered in addition to common tags being interpreted
jsonTemplate	name, , expand, render	same as template handler, but returns a json object holding css and js zones required to properly format the template; used via foswiki.loadTemplate()

Usage

The REST handlers are called like this:

%SCRIPTURLPATH{"rest"}%/RenderPlugin/render?text=%ENCODE{"This is _very_ cool."}%

%SCRIPTURLPATH{"rest"}%/RenderPlugin/tag?name=INCLUDE;param=Applications.RenderWebTagCloud;search=screenshot

(equivalent to a %INCLUDE{"Applications.RenderWebTagCloud" search="screenshot"}%)

This can be schedule using jQuery like this:

<div id="container"></div>

<literal>
<script>
jQuery(function($) {
  $("#container").load("<url-to-rest-handler->");
});
</script>

Examples

Fetching a message

%STARTSECTION{"message"}%
*Hello World!* :)
%ENDSECTION{"message"}%

Previewing TML

Okay, your turn to create an example calling SEARCH.

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. "Extensions Operation and Maintenance" Tab → "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> 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 https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Foswiki::Plugins::JQueryPlugin	>=0.5	Optional.

Change History

14 Feb 2019:	make template loader available to javascript as a proper jQuery module
16 Jan 2017:	added filename to rest handler to override it in the content-dispisition header
29 Apr 2016:	added support for newer Foswiki engines
31 Aug 2015:	implemeted JSON-Template REST handler
04 Apr 2014:	flag rest handlers that don't require authentication
18 Mar 2014:	removed duplicate http header from render rest handler
01 Nov 2013:	added support for contenttype url parameter
10 Jan 2012:	some docu fixes
12 May 2009:	added template handler
24 Apr 2009:	converted to foswiki plugin
07 Jan 2009:	added upload rest handler; fixes for foswiki and FastCGIContrib
11 Jul 2008:	initial version