This plugin implements a couple of REST handlers to feetch content from a Foswiki backend.
This can either be returned as plain content (via the template handler) or encoded in a JSON object that logs required
css and js in addition to the content block (via the jsonTemplate handler).
These can be used to easily replace a server-side INCLUDE with a
functional equivalent using a javascript 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).
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()
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
Usage
TODO: come up with some examples for the non-deprecated handlers
The REST handlers are called like this:
%SCRIPTURLPATH{"rest"}%/RenderPlugin/render?text=%ENCODE{"This is _very_ cool."}%
foswiki.loadTemplate: JavaScript API to load JSON content
The foswiki.loadTemplate() function can be used to load content from the backend using the jsonTemplate handler and inject it into the current DOM
including all JavaScript and CSS as required by the collected content (via Foswiki::Func::addToZone() or %JQREQUIRE or %ADDZOZONE). These additional assets
will be added to the respective zones of the page if not already present.
foswikiDialogLink: load jQuery dialogs as JSON content
While JQueryPlugin comes with a dialog loader of its own, it lacks the additional handling of assets required to render
the dialog properly, i.e. JavaScript to initialize it. This is mitigated using the CSS class foswikiDialogLink on
an anchor element or any other clickable button.
Example:
Add
%JQREQUIRE{"FoswikiTemplate"}%
to process all foswikiDialogLink elements of the current page.
such as
<a href="#backlinks" class="foswikiDialogLink">Display backlinks of the current topic</a>
If a user clicks on this link will it
load the backlinks template and return the TMPL:DEF{"dialog"} definition as a JSON object
inject the dialog into the page and open it.
The backlinks.tmpl content must have a jqUIDialog definition similar to:
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
Berichte