com.xpn.xwiki.plugin.skinx
Class AbstractSkinExtensionPlugin

java.lang.Object
  com.xpn.xwiki.plugin.XWikiDefaultPlugin
      com.xpn.xwiki.plugin.skinx.AbstractSkinExtensionPlugin

All Implemented Interfaces:

com.xpn.xwiki.plugin.XWikiPluginInterface

Direct Known Subclasses:

AbstractDocumentSkinExtensionPlugin, AbstractResourceSkinExtensionPlugin, CssSkinFileExtensionPlugin, JsSkinFileExtensionPlugin, LinkExtensionPlugin

public abstract class AbstractSkinExtensionPlugin
extends com.xpn.xwiki.plugin.XWikiDefaultPlugin

Skin Extensions base plugin. It allows templates and document content to pull required clientside code in the generated XHTML (or whatever XML) content.

The API provides a method SkinExtensionPluginApi.use(String), which, when called, marks an extension as used in the current result. Later on, all the used extensions are inserted in the content, by replacing the first occurrence of the following string: <!-- canonical.plugin.classname -->, where the actual extension type classname is used. For example, JS extensions are inserted in place of <!-- com.xpn.xwiki.plugin.skinx.JsSkinExtensionPlugin -->.

Version:

$Id$

See Also:

SkinExtensionPluginApi, JsSkinExtensionPlugin, CssSkinExtensionPlugin, LinkExtensionPlugin

Field Summary

protected String	contextKey The name of the context key for the list of pulled extensions.
protected String	parametersContextKey The name of the context key for the additional parameters for pulled extensions.

Constructor Summary

AbstractSkinExtensionPlugin(String name, String className, com.xpn.xwiki.XWikiContext context)
XWiki plugin constructor.

Method Summary

String	endParsing(String content, com.xpn.xwiki.XWikiContext context)
abstract Set<String>	getAlwaysUsedExtensions(com.xpn.xwiki.XWikiContext context) Returns the list of always used extensions of this type.
String	getImportString(com.xpn.xwiki.XWikiContext context) Composes and returns the links to the resources pulled in the current request.
abstract String	getLink(String resource, com.xpn.xwiki.XWikiContext context) Abstract method for obtaining a link that points to the actual pulled resource.
protected Object	getParameter(String parameterName, String resource, com.xpn.xwiki.XWikiContext context) Get a parameter value for a pulled resource.
protected Map<String,Object>	getParametersForResource(String resource, com.xpn.xwiki.XWikiContext context) Get the parameters for a pulled resource.
protected Map<String,Map<String,Object>>	getParametersMap(com.xpn.xwiki.XWikiContext context) Get the map of additional parameters for each pulled resource (of the plugin's type) for the current request.
Api	getPluginApi(com.xpn.xwiki.plugin.XWikiPluginInterface plugin, com.xpn.xwiki.XWikiContext context)
protected Set<String>	getPulledResources(com.xpn.xwiki.XWikiContext context) Get the list of pulled resources (of the plugin's type) for the current request.
abstract boolean	hasPageExtensions(com.xpn.xwiki.XWikiContext context) Determines if the requested document contains on page skin extension objects of this type.
protected void	initializeRequestListIfNeeded(com.xpn.xwiki.XWikiContext context) Initializes the list of pulled extensions corresponding to this request, if it wasn't already initialized.
protected String	parametersAsQueryString(String resource, com.xpn.xwiki.XWikiContext context) This method converts the parameters for an extension to a query string that can be used with getURL() and printed in the XHTML result.
protected String	sanitize(String value) Prevent "HTML Injection" by making sure the rendered text does not escape the current element.
void	use(String resource, Map<String,Object> parameters, com.xpn.xwiki.XWikiContext context) Mark a skin extension document as used in the current result, together with some parameters.
void	use(String resource, com.xpn.xwiki.XWikiContext context) Mark a resource as used in the current result.

Methods inherited from class com.xpn.xwiki.plugin.XWikiDefaultPlugin

beginParsing, beginRendering, commonTagsHandler, downloadAttachment, endRendering, endRenderingHandler, flushCache, flushCache, getClassName, getName, init, insidePREHandler, outsidePREHandler, setClassName, setName, startRenderingHandler, virtualInit

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

contextKey

protected final String contextKey

The name of the context key for the list of pulled extensions.

parametersContextKey

protected final String parametersContextKey

The name of the context key for the additional parameters for pulled extensions.

Constructor Detail

AbstractSkinExtensionPlugin

public AbstractSkinExtensionPlugin(String name,
                                   String className,
                                   com.xpn.xwiki.XWikiContext context)

XWiki plugin constructor.

Parameters:

name - The name of the plugin, which can be used for retrieving the plugin API from velocity. Unused.

className - The canonical classname of the plugin. Unused.

context - The current request context.

See Also:

XWikiDefaultPlugin.XWikiDefaultPlugin(String,String,com.xpn.xwiki.XWikiContext)

Method Detail

getLink

public abstract String getLink(String resource,
                               com.xpn.xwiki.XWikiContext context)

Abstract method for obtaining a link that points to the actual pulled resource. Each type of resource has its own format for the link, for example Javascript uses <script src="/path/to/Document">, while CSS uses <link rel="stylesheet" href="/path/to/Document"> (the actual syntax is longer, this is just a simplified example).

Parameters:

resource - the name of the wiki document holding the resource.

context - the current request context, needed to access the URLFactory.

Returns:

A String representation of the linking element that should be printed in the generated HTML.

getAlwaysUsedExtensions

public abstract Set<String> getAlwaysUsedExtensions(com.xpn.xwiki.XWikiContext context)

Returns the list of always used extensions of this type. Which resources are always used depends on the type of resource, for example document based StyleSheet extensions have a property in the object, use, which can have the value always to declare that an extension should always be used.

Parameters:

context - The current request context.

Returns:

A set of resource names that should be pulled in the current response. Note that this method is called for each request, as the list might change in time, and it can be different for each wiki in a farm.

hasPageExtensions

public abstract boolean hasPageExtensions(com.xpn.xwiki.XWikiContext context)

Determines if the requested document contains on page skin extension objects of this type. True if at least one of the extension objects has the currentPage value for the use property.

Parameters:

context - the current request context

Returns:

a boolean specifying if the current document contains on page skin extensions

getPluginApi

public Api getPluginApi(com.xpn.xwiki.plugin.XWikiPluginInterface plugin,
                        com.xpn.xwiki.XWikiContext context)

Specified by:

getPluginApi in interface com.xpn.xwiki.plugin.XWikiPluginInterface

Overrides:

getPluginApi in class com.xpn.xwiki.plugin.XWikiDefaultPlugin

use

public void use(String resource,
                com.xpn.xwiki.XWikiContext context)

Mark a resource as used in the current result. A resource is registered only once per request, further calls will not result in additional links, even if it is pulled with different parameters.

Parameters:

resource - The name of the resource to pull.

context - The current request context.

See Also:

use(String, Map, XWikiContext)

use

public void use(String resource,
                Map<String,Object> parameters,
                com.xpn.xwiki.XWikiContext context)

Mark a skin extension document as used in the current result, together with some parameters. How the parameters are used, depends on the type of resource being pulled. For example, JS and CSS extensions use the parameters in the resulting URL, while Link extensions use the parameters as attributes of the link tag. A resource is registered only once per request, further calls will not result in additional links, even if it is pulled with different parameters. If more than one calls per request are made, the parameters used are the ones from the last call (or none, if the last call did not specify any parameters).

Parameters:

resource - The name of the resource to pull.

parameters - The parameters for this resource.

context - The current request context.

See Also:

use(String, XWikiContext)

getPulledResources

protected Set<String> getPulledResources(com.xpn.xwiki.XWikiContext context)

Get the list of pulled resources (of the plugin's type) for the current request. The returned list is always valid.

Parameters:

context - The current request context.

Returns:

A set of names that holds the resources pulled in the current request.

getParametersMap

protected Map<String,Map<String,Object>> getParametersMap(com.xpn.xwiki.XWikiContext context)

Get the map of additional parameters for each pulled resource (of the plugin's type) for the current request. The returned map is always valid.

Parameters:

context - The current request context.

Returns:

A map of resource parameters, where the key is the resource's name, and the value is a map holding the actual parameters for a given resource. If a resource was pulled without additional parameters, then no corresponding entry is added in this map.

initializeRequestListIfNeeded

protected void initializeRequestListIfNeeded(com.xpn.xwiki.XWikiContext context)

Initializes the list of pulled extensions corresponding to this request, if it wasn't already initialized. This method is not thread safe, since a context should not be shared among threads.

Parameters:

context - The current context where this list is stored.

getImportString

public String getImportString(com.xpn.xwiki.XWikiContext context)

Composes and returns the links to the resources pulled in the current request. This method is called at the end of each request, once for each type of resource (subclass), and the result is placed in the generated XHTML.

Parameters:

context - The current request context.

Returns:

a XHMTL fragment with all extensions imports statements for this request. This includes both extensions that are defined as being "used always" and "on demand" extensions explicitly requested for this page. Always used extensions are always, before on demand extensions, so that on demand extensions can override more general elements in the always used ones.

getParametersForResource

protected Map<String,Object> getParametersForResource(String resource,
                                                      com.xpn.xwiki.XWikiContext context)

Get the parameters for a pulled resource. Note that a valid map is always returned, even if no parameters were given when the resource was pulled.

Parameters:

resource - The resource for which to retrieve the parameters.

context - The current request context.

Returns:

The parameters for the resource, as a map where the keys are the parameter names, and the values are corresponding parameter value. If no parameters were given, an empty map is returned.

getParameter

protected Object getParameter(String parameterName,
                              String resource,
                              com.xpn.xwiki.XWikiContext context)

Get a parameter value for a pulled resource.

Parameters:

parameterName - the name of the parameter to retrieve

resource - the resource for which to retrieve the parameter

context - the current request context

Returns:

The parameter value for the resource. If this parameter was not given, null is returned.

parametersAsQueryString

protected String parametersAsQueryString(String resource,
                                         com.xpn.xwiki.XWikiContext context)

This method converts the parameters for an extension to a query string that can be used with getURL() and printed in the XHTML result. The parameters separator is the escaped &amp;. The query string already starts with an &amp; if at least one parameter exists.

Parameters:

resource - The pulled resource whose parameters should be converted.

context - The current request context.

Returns:

The constructed query string, or an empty string if there are no parameters.

sanitize

protected String sanitize(String value)

Prevent "HTML Injection" by making sure the rendered text does not escape the current element. This is achieved by URL-encoding the following characters: '"<>

Parameters:

value - The string to sanitize.

Returns:

The unchanged string, if it does not contain special characters, or the empty string.

endParsing

public String endParsing(String content,
                         com.xpn.xwiki.XWikiContext context)

At the end of the request, insert the links to the pulled resources in the response, in the place marked by an XML comment of the format <!-- canonical.plugin.classname -->.

Specified by:

endParsing in interface com.xpn.xwiki.plugin.XWikiPluginInterface

Overrides:

endParsing in class com.xpn.xwiki.plugin.XWikiDefaultPlugin

See Also:

XWikiDefaultPlugin.endParsing(String, XWikiContext)