DocWiki2.4: ResourceRequests

Edit
More...

Any plugin, filter, template, or other component can request resources (e.g. CSS or Javascript) to be included in the resulting page. These are called Resource Requests.

Introduction#

This article is meant for any plugin, filter, or template developer. When developing an advanced module, often it is necessary to include some external resources, like CSS files or other things. Since a plugin can only modify a very particular part of a page, you may have a temptation to modify commonheader.jsp, but that is not a good idea, since it is a key component of JSPWiki architecture, and should not be changed. This is even true if you're developing a template.

Therefore there is a mechanism called "Resource Requests", which allow the developer to arbitrarily add the most common resources to the generated page. You can add CSS, Javascript, inline CSS, or even arbitrary HTTP Headers.

ResourceRequests are managed by the TemplateManager. First, it is suggested that you read through HowWikiEngineWorks to get an overview on how things are managed.

Requesting a Resource - example#

Here is a simple example of how you could possibly use a resource request in your plugin (preamble omitted for brevity):

public class MyPlugin implements WikiPlugin
{
    public String execute( WikiContext ctx, Map params )
    {
        TemplateManager.addResourceRequest( ctx,
                                            TemplateManager.RESOURCE_SCRIPT,
                                            "scripts/myplugin.js" );
        return "";
    }
}

When put on the page using

[{MyPlugin}]

The resulting HTML will include the following line between the <head></head> -elements:

<script type='text/javascript' src='scripts/myplugin.js'></script>

As you can see, this is an easy way for a plugin to "announce" what kind of resources it needs on a dynamic basis, without you having to edit the commonheader.jsp.

Including resources#

JSP pages#

On JSP pages (such as your own templates), you can request a resource using the RequestResourceTag. For example:

   <wiki:RequestResource type="script" path="scripts/myplugin.js"/>

Which would have the same effect as the ~MyPlugin, above.

Plugins, filters#

On programmatic code, you should use the TemplateManager.addResourceRequest()-method.

Types of Resource Requests#

Javascript#

Javascript requests are easy to add using the "script" (TemplateManager.RESOURCE_SCRIPT) resource request. Take good care of the path name - in many cases it might be a good idea to ensure the proper path by calling context.getURL() to get the correct URL to your resource.

Automatically run Javascript functions#

There is a special resource request named "jsfunction" (TemplateManager.RESOURCE_JSFUNCTION), which defines which functions should be called when the page loads. In practice, JSPWiki always executes page.onload() with a set of functions, and this request just adds the function to that list. For example:

TemplateManager.addResourceRequest( ctx,
                                    TemplateManager.RESOURCE_JSFUNCTION,
                                    "runOnLoad()" );

would result in the method "runOnLoad()" to be run every time the page is loaded.

CSS#

Cascading Style Sheets are also easy to include with the "stylesheet" (TemplateManager.RESOURCE_STYLESHEET) request. They work exactly the same way as Javascript, so you probably wish to make sure you use the WikiContext.getURL() -method to get the proper URL.

For example

    String url = wikiContext.getURL( WikiContext.NONE, "css/my.css" );
    TemplateManager.addResourceRequest( ctx,
                                        TemplateManager.RESOURCE_STYLESHEET,
                                        url );

Inline CSS#

Sometimes you wish to generate the CSS dynamically and just add it into the request. Then the "inlinecss", or TemplateManager.RESOURCE_INLINECSS helps you. Any resource request here gets added between <style>...</style> -tags in the <head> of the resulting HTML file.

For example:

    TemplateManager.addResourceRequest( ctx, TemplateManager.RESOURCE_INLINECSS,
                                        ".myplugin { margin-top: 2px; }\n.myplugin a { color:blue }" );

results in

<style>
.myplugin { margin-top: 2px; }
.myplugin a { color:blue }
</style>

Note that there is no checking of whether this is actually correct.

HTTP Response headers#

NB: This functionality is available from JSPWiki 2.6 onwards!

You can also add arbitrary response headers by using the "httpheader" (TemplateManager.RESOURCE_HTTPHEADER) resource request. For example

    TemplateManager.addResourceRequest( ctx, TemplateManager.RESOURCE_HTTPHEADER,
                                        "Pragma: no-cache" );

would result in the addition of "Pragma: no-cache" header being added to the response.

Some warnings#

Include only once#

One thing you have to be careful about is that you want to be sure the content is only included once. If you call addResourceRequest() multiple times, you end up having multiple resources included or inserted.

Don't change commonheader.jsp#

It is not a good idea to change commonheader.jsp. If you do, it's possible that you break the entire resource request system. This mechanism was developed just so that you didn't need to change commonheader.jsp.