Class AbstractSkinExtensionPlugin
- java.lang.Object
-
- com.xpn.xwiki.plugin.XWikiDefaultPlugin
-
- com.xpn.xwiki.plugin.skinx.AbstractSkinExtensionPlugin
-
- All Implemented Interfaces:
com.xpn.xwiki.internal.cache.rendering.RenderingCacheAware
,XWikiPluginInterface
- Direct Known Subclasses:
AbstractDocumentSkinExtensionPlugin
,AbstractResourceSkinExtensionPlugin
,CssSkinFileExtensionPlugin
,JsSkinFileExtensionPlugin
,LinkExtensionPlugin
public abstract class AbstractSkinExtensionPlugin extends XWikiDefaultPlugin implements com.xpn.xwiki.internal.cache.rendering.RenderingCacheAware
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: ae3d23fa9637c0c8f17ed384b360c6ae4bcd0686 $
- See Also:
SkinExtensionPluginApi
,JsSkinExtensionPlugin
,CssSkinExtensionPlugin
,LinkExtensionPlugin
-
-
Field Summary
Fields Modifier and Type Field Description protected String
contextKey
The name of the context key for the list of pulled extensions.static String
DEFER_DEFAULT_PARAM
The name of the preference (in the configuration file) specifying what is the default value of the defer, in case nothing is specified in the parameters of this extension.protected String
parametersContextKey
The name of the context key for the additional parameters for pulled extensions.protected static String
QUERY_PARAMETER_DELIMITER
The URL delimiter part of query parameters.
-
Constructor Summary
Constructors Constructor Description AbstractSkinExtensionPlugin(String name, String className, XWikiContext context)
XWiki plugin constructor.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description String
endParsing(String content, XWikiContext context)
abstract Set<String>
getAlwaysUsedExtensions(XWikiContext context)
Returns the list of always used extensions of this type.com.xpn.xwiki.internal.cache.rendering.CachedItem.UsedExtension
getCacheResources(XWikiContext context)
protected org.xwiki.model.reference.DocumentReferenceResolver<String>
getCurrentDocumentReferenceResolver()
Used to resolve a document string reference to a Document Reference.protected org.xwiki.model.reference.EntityReferenceSerializer<String>
getDefaultEntityReferenceSerializer()
Used to convert a proper Document Reference to string (standard form).String
getImportString(XWikiContext context)
Composes and returns the links to the resources pulled in the current request.abstract String
getLink(String resource, XWikiContext context)
Abstract method for obtaining a link that points to the actual pulled resource.String
getLink(String resource, Map<String,Object> parameters, XWikiContext context)
Abstract method for obtaining a link that points to the actual pulled resource.protected Object
getParameter(String parameterName, String resource, XWikiContext context)
Get a parameter value for a pulled resource.protected Map<String,Object>
getParametersForResource(String resource, XWikiContext context)
Get the parameters for a pulled resource.protected Map<String,Map<String,Object>>
getParametersMap(XWikiContext context)
Get the map of additional parameters for each pulled resource (of the plugin's type) for the current request.Api
getPluginApi(XWikiPluginInterface plugin, XWikiContext context)
protected Set<String>
getPulledResources(XWikiContext context)
Get the list of pulled resources (of the plugin's type) for the current request.protected org.xwiki.skinx.internal.async.SkinExtensionAsync
getSkinExtensionAsync()
abstract boolean
hasPageExtensions(XWikiContext context)
Determines if the requested document contains on page skin extension objects of this type.protected void
initializeRequestListIfNeeded(XWikiContext context)
Initializes the list of pulled extensions corresponding to this request, if it wasn't already initialized.protected String
parametersAsQueryString(String resource, XWikiContext context)
This method converts the parameters for an extension to a query string that can be used withgetURL()
and printed in the XHTML result.void
restoreCacheResources(XWikiContext context, com.xpn.xwiki.internal.cache.rendering.CachedItem.UsedExtension extension)
protected String
sanitize(String value)
Prevent "HTML Injection" by making sure the rendered text does not escape the current element.void
use(String resource, XWikiContext context)
Mark a resource as used in the current result.void
use(String resource, Map<String,Object> parameters, XWikiContext context)
Mark a skin extension document as used in the current result, together with some parameters.-
Methods inherited from class com.xpn.xwiki.plugin.XWikiDefaultPlugin
beginParsing, beginRendering, commonTagsHandler, downloadAttachment, endRendering, endRenderingHandler, flushCache, flushCache, getClassName, getLocalization, getName, init, insidePREHandler, localizePlainOrKey, outsidePREHandler, setClassName, setName, startRenderingHandler, virtualInit
-
-
-
-
Field Detail
-
DEFER_DEFAULT_PARAM
public static final String DEFER_DEFAULT_PARAM
The name of the preference (in the configuration file) specifying what is the default value of the defer, in case nothing is specified in the parameters of this extension.- Since:
- 14.1RC1
- See Also:
- Constant Field Values
-
QUERY_PARAMETER_DELIMITER
protected static final String QUERY_PARAMETER_DELIMITER
The URL delimiter part of query parameters.- Since:
- 11.6RC1, 11.3.2
- See Also:
- Constant Field Values
-
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, 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(String,String,com.xpn.xwiki.XWikiContext)
-
-
Method Detail
-
getLink
public abstract String getLink(String resource, 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.
-
getLink
public String getLink(String resource, Map<String,Object> parameters, 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.parameters
- the parameters associated with 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. - Since:
- 10.11.9, 11.3.2, 11.6RC1
-
getAlwaysUsedExtensions
public abstract Set<String> getAlwaysUsedExtensions(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 valuealways
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(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 thecurrentPage
value for theuse
property.- Parameters:
context
- the current request context- Returns:
- a boolean specifying if the current document contains on page skin extensions
-
getPluginApi
public Api getPluginApi(XWikiPluginInterface plugin, XWikiContext context)
- Specified by:
getPluginApi
in interfaceXWikiPluginInterface
- Overrides:
getPluginApi
in classXWikiDefaultPlugin
-
use
public void use(String resource, 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, 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(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(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(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(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, 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, XWikiContext context)
Get a parameter value for a pulled resource.- Parameters:
parameterName
- the name of the parameter to retrieveresource
- the resource for which to retrieve the parametercontext
- 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, XWikiContext context)
This method converts the parameters for an extension to a query string that can be used withgetURL()
and printed in the XHTML result. The parameters separator is the escaped &. The query string already starts with an & 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, 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 interfaceXWikiPluginInterface
- Overrides:
endParsing
in classXWikiDefaultPlugin
- See Also:
XWikiDefaultPlugin.endParsing(String, XWikiContext)
-
getCacheResources
public com.xpn.xwiki.internal.cache.rendering.CachedItem.UsedExtension getCacheResources(XWikiContext context)
- Specified by:
getCacheResources
in interfacecom.xpn.xwiki.internal.cache.rendering.RenderingCacheAware
-
restoreCacheResources
public void restoreCacheResources(XWikiContext context, com.xpn.xwiki.internal.cache.rendering.CachedItem.UsedExtension extension)
- Specified by:
restoreCacheResources
in interfacecom.xpn.xwiki.internal.cache.rendering.RenderingCacheAware
-
getDefaultEntityReferenceSerializer
protected org.xwiki.model.reference.EntityReferenceSerializer<String> getDefaultEntityReferenceSerializer()
Used to convert a proper Document Reference to string (standard form).
-
getCurrentDocumentReferenceResolver
protected org.xwiki.model.reference.DocumentReferenceResolver<String> getCurrentDocumentReferenceResolver()
Used to resolve a document string reference to a Document Reference.
-
getSkinExtensionAsync
protected org.xwiki.skinx.internal.async.SkinExtensionAsync getSkinExtensionAsync()
-
-