Support for Server products ended Feb. 15, 2024. Learn what this means for you.

Web Resource Transformer module

Available:

Confluence 3.4 and later.

Purpose of this Module Type

Web Resource Transformer plugin modules allow you to manipulate static web resources before they are batched and delivered to the browser. This means that you can get past the restrictions of straight JavaScript and CSS, including restrictions like no includes, no external resource support, no CSS variables, only one JS context, and so on.

Configuration

To use a web resource transformer, you need the following elements in your atlassian-plugin.xml file:

The transformer module: A <web-resource-transformer> element, defining the transformer plugin module. This module can be in the same plugin as the web resource, or in a different plugin.
Transformation elements in the web resource module: A <transformation> element and its child <transformer> element inside the <web-resource> block, making a particular transformer available to the web resource in the plugin.

Below is a description of the attributes and child elements for each of the above elements.

Attributes of `web-resource-transformer`

Name*	Description
class	The class which implements com.atlassian.plugin.webresource.transformer.WebResourceTransformer. This class is responsible for doing the resource transformation before it is served to the client. See the plugin framework guide to creating plugin module instances.
state	Indicate whether the plugin module should be disabled by default (value='disabled') or enabled by default (value='enabled'). Default: enabled
i18n-name-key	The localisation key for the human-readable name of the plugin module.
key	The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources. 1 2 `<component-import key="appProps" interface="com.atlassian.sal.api.ApplicationProperties"/>` In the example, `appProps` is the key for this particular module declaration, for `component-import`, in this case. The value of this attribute must match the `key` attribute of the `transformer` element in the `web-resource`.
name	The human-readable name of the plugin module.
system	Indicates whether this plugin module is a system plugin module (value='true') or not (value='false'). Only available for non-OSGi plugins. Default: false

*class and key attributes are required

Child Elements of `web-resource-transformer`


Name	description
Description	The description of the plugin module. The 'key' attribute can be specified to declare a localisation key for the value instead of text in the element body.

Attributes of `transformation`


Name*	extension
Description	Defines a transformation process.

*extension attribute is required

Child Elements of `transformation`


Name*	transformer
Description	Defines a transformation process.

*transformer element is required

Attributes of `transformer`


Name*	key
Description	The value of this attribute must match the `key` attribute of the `web-resource-transformer` element.

*key attribute is required


Name	(others)
Description	You can add your own attributes as required, to pass information to your implementation of the transformer.

Child Elements of `transformer`


Name	(others)
Description	You can add your own child elements as required, to pass information to your implementation of the transformer.

Example

Here is an example atlassian-plugin.xml file containing a web resource and a transformer that turns a static template file into a JavaScript variable. You could use this transformer for common components that need to use client-side templates.

1
2
<atlassian-plugin name="Hello World Resource" key="example.plugin.helloworld" plugins-version="2">
<plugin-info>
  <description>A web resource module with a transformer</description>
  <vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/>
  <version>1.0</version>
</plugin-info>
<web-resource key="testTemplate">
  <transformation extension="txt">
    <transformer key="template" />
  </transformation>
  <resource type="download" name="testTemplate.js" location="testTemplate.txt" />
  <resource type="download" name="testTemplate.css" />
</web-resource>
<web-resource-transformer key="template" class="com.atlassian.labs.template.TemplateTransformer" />
</atlassian-plugin>

The template testTemplate.txt file looks like this:

1
2
Hello world "bob"
and 'friends'

The JavaScript resulting from the transformation is:

1
2
var testTemplate = "Hello world \"bob\"\nand \'friends\'";

Notes

Some information to be aware of when developing or configuring a Web Resource Transformer plugin module:

The <web-resource-transformer> module can live in the same plugin as the <web-resource> module, or in a different module. The transformers are registered globally.
You can apply multiple transformers. Any subsequent transformer will process the result of the earlier transformation.
You can pass information to the transformer by adding arbitrary attributes and child elements to the <transformer> element in the resource.

Web UI Modules
Web Item Plugin Module
Web Section Plugin Module
Web Panel Renderer Plugin Module
Web Resource Module
Writing Confluence Plugins

Information sourced from Plugin Framework documentation