Available: | Atlassian Plugin Framework 2.5 and later. |
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.
To use a web resource transformer, you need the following elements in your atlassian-plugin.xml
file:
<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>
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.
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.
In the example, The value of this attribute must match the |
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
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. |
transformation
Name* | extension |
Description | Defines a transformation process. |
*extension attribute is required
transformation
Name* | transformer |
Description | Defines a transformation process. |
*transformer element is required
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. |
transformer
Name | (others) |
Description | You can add your own child elements as required, to pass information to your implementation of the transformer. |
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 2Hello world "bob" and 'friends'
The JavaScript resulting from the transformation is:
1 2var testTemplate = "Hello world \"bob\"\nand \'friends\'";
Some information to be aware of when developing or configuring a Web Resource Transformer plugin module:
<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.<transformer>
element in the resource.Rate this page: