Web Resource Transformer Module

Available:

Confluence 3.4 and later.

On this page:

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

Required

Description

Default

class

(tick)

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').

enabled

i18n-name-key

The localisation key for the human-readable name of the plugin module.

key

(tick)

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.

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

N/A

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.

false

Child Elements of web-resource-transformer

Name

Required

Description

Default

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

Required

Description

Default

extension

(tick)

All the transformers in the transformation block apply to resources with this extension.

Child Elements of transformation

Name

Required

Description

Default

transformer

(tick)

Defines a transformation process.

Attributes of transformer

Name

Required

Description

Default

key

(tick)

The value of this attribute must match the key attribute of the web-resource-transformer element.

(others)

You can add your own attributes as required, to pass information to your implementation of the transformer.

Child Elements of transformer

Name

Required

Description

Default

(others)

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.

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

Hello world "bob"
and 'friends'

The JavaScript resulting from the transformation is:

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.

RELATED TOPICS

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

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport