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
3
<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

Namedescription
DescriptionThe 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
DescriptionDefines a transformation process.

*extension attribute is required

Child Elements of transformation

Name*transformer
DescriptionDefines a transformation process.

*transformer element is required

Attributes of transformer

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

*key attribute is required

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

Child Elements of transformer

Name(others)
DescriptionYou 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
3
4
5
6
7
8
9
10
11
12
13
14
15
<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
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