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 parametrizedINCLUDE
, as it is used on server side WikiApplications (see examples below).
Handler | Parameters | Description |
---|---|---|
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() |
Deprecated 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 |
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."}%
%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>
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.
Parameter | Description | Defaults |
---|---|---|
name | name of the template to load (required) | |
expand | name of the TMPL:DEF to expand (required) | |
topic | Foswiki address from where to process the response | current web.topic |
url | url from where to load content | /bin/rest/RenderPlugin/jsonTemplate |
debug | boolean switch to enable debug output on the conosole | false |
render | switch on TML rendering on the backend | on |
zones | list of zones to return | script, head |
async | boolean flag to add the async attribute to script and style assets |
false |
cachecontrol | caching behaviour of loaded content: specifies the number of seconds the returned JSON content is to be cached by the browser | 0 |
… | any other parameter is passed to the REST handler as is |
Note that =foswiki.loadTemplate() returns a jqXHR promise:
foswiki.loadTemplate({ "name": "user", "expand": "photo" "topic": foswiki.getPreference("WIKIUSERNAME") }).done(function(data) { var $content = $(data.expand); $(body).append($content); });
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:
%TMPL:DEF{"dialog"}%<div class="jqUIDialog" data-modal="true" data-height="600" data-width="930" data-draggable="true" data-resizable="true" title="Backlinks to <nop>%WEB%.%TOPIC%"> ... <a class="jqUIDialogButton jqUIDialogClose" data-icon="ui-icon-cancel">%MAKETEXT{"Close"}%</a> </div>%TMPL:END%Note, the
foswikiDialogLink
can be customized using HTML5 data parameters such as in:
<a class="foswikiDialogLink" data-name="..." data-expand="..." data-...>Click me</a>See the list of parameters for the
foswiki.loadTemplate()
API.
%STARTSECTION{"message"}% *Hello World!* :) %ENDSECTION{"message"}%
Okay, your turn to create an example calling SEARCH.
cd /path/to/foswiki perl tools/extension_installer <NameOfExtension> installIf 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.
26 Jan 2024: | added support for id obfuscation |
29 Apr 2022: | deprecated expand and render REST handler, added whitelist of allowed macros to tag REST handler |
14 Oct 2020: | improved cacheability of rest handlers; new class foswikiDialogLink to ease creating dialogs |
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 |
Author | Michael Daum |
Version | 7.00 |
Release | 26 Jan 2024 |
Description | Render WikiApplications asynchronously |
Repository | https://github.com/foswiki/RenderPlugin |
Copyright | 2006-2024, Michael Daum |
License | GPL (GNU General Public License) |
Home | Foswiki:Extensions/RenderPlugin |
Support | Foswiki:Support/RenderPlugin |