RenderPlugin

Render TWikiApplications asynchronously

Description

Powered by WikiRing Consultants

This plugin implements three simple REST handlers to get content from TWiki. For example, these can be used to easily replace a server-side INCLUDE with a functinal 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 TWikiMarkup on the server and return a HTML preview back to the browser.

The REST handlers of this plugin have been designed 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 of 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 TWikiApplication 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 TWikiApplications (see examples below).

Syntax

The available REST handlers are:

Handler	Parameters	Description
expand	text	expands common variables in the submitted text fragment
render	text	same as expand but also renders TWikiMarkup converting it to HTML
tag	name, param, <named-params>*, render	this is a convenience function to expand one specific TWikiVariable instead of having to build up a snippet of TWiki 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 (see expand) or if it should be renderd into HTML; default is off, that is only expand common tags but don't interpret TWikiMarkup

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>

<script type="text/javascript">
$(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 where TWiki is running.

Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.

• If you have TWiki 4.2 or later, you can install from the configure interface (Go to Plugins->Find More Extensions)
  • See the installation supplement on TWiki.org for more information.
• If you have any problems, then you can still install manually from the command-line:
  1. Download one of the .zip or .tgz archives
  2. Unpack the archive in the root directory of your TWiki installation.
  3. Run the installer script ( perl <module>_installer )
  4. Run configure and enable the module, if it is a plugin.
  5. Repeat for any missing dependencies.
• If you are still having problems, then instead of running the installer script:
  1. Make sure that the file permissions allow the webserver user to access all files.
  2. Check in any installed files that have existing ,v files in your existing install (take care not to lock the files when you check in)
  3. Manually edit LocalSite.cfg to set any configuration variables.

Plugin Info

Plugin Author:	TWiki:Main.MichaelDaum
Copyright ©:	2006-2008, Michael Daum http://michaeldaumconsulting.com
License:	GPL (GNU General Public License)
Plugin Version:	0.1
Change History:
11 Jul 2008:	initial version
Dependencies:	Name Version Description TWiki::Plugins::JQueryPlugin >=0.5 Optional.
Plugin Home:	TWiki:Plugins/RenderPlugin
Feedback:	TWiki:Plugins/RenderPluginDev
Appraisal:	TWiki:Plugins/RenderPluginAppraisal