Stateless web-resource transforms and conditions
To achieve this, we have created new APIs for web-resource transforms and conditions. This page describes how to update your transforms and conditions to these new APIs.
On this page:
The core problem
- page-render-time: when rendering the HTML page, calculate and render the URLs for CSS
Under the new APIs, all the information required by the transformer or condition must be encoded in the URL. Do not assume that you will have a current user at resource-serve-time. To achieve this, we have deprecated the old web-resource transform and condition APIs and created new APIs:
- for transforms,
com.atlassian.plugin.webresource.transformer.WebResourceTransformerhas been deprecated in favour of
- for conditions, the use of
com.atlassian.plugin.web.Conditionin web-resources has been deprecated in favour of
com.atlassian.plugin.webresource.condition.UrlReadingCondition. (Note that the Condition class itself is not deprecated, as it is still relevant for web-fragments as opposed to web-resources.)
These APIs appear in
atlassian-plugins-webresources version 3.0.
How do I fix offending transforms?
There are two cases to fix here:
Transforms that do compilation
Examples include LESS and i18n transformation.
To fix these, convert from
WebResourceTransformerFactory (which produces
UrlReadingWebResourceTransformers). This enables you to contribute to the URL at page-render-time and read from that URL at resource-serve-time.
Taking the i18n transform as an example:
- the old i18n transform reads the user's locale at resource-serve-time
- the new i18n transform
- add the user's locale to the resource URL's querystring at page-render-time
- reads the locale from the querystring at resource-serve-time
Note that fixing the transform can be hard, as it may not be the transform class that is actually doing the cookie lookup; it may be something deeper in the dependency-injection hierarchy. For this reason, it is better to convert to the data API if possible (see below).
Transforms that do variable injection
To see this in action, see the new ContextPathProvider. This consists of three parts:
How do I fix offending conditions?
When looking at conditions, the first thing to consider is:
If you do need to convert it, the most common solution is to convert your conditions to a UrlReadingCondition.
Note one potential issue:
- UrlReadingConditions are included in the batch. This fixes a long-standing bug where resources with conditions are delivered as separate resources, breaking web-resource dependency order (and making dependency different between dev and prod mode). However, there is a strong chance that your code (especially CSS) was written knowing that this bug existed. You should test to ensure that this change in batch ordering has not affected your plugin.
If your plugin targets products using old versions of webresources but you want to make use of the transform2 / condition2, use the following techniques to be compatible:
Keep your transform1 implementation untouched and add a transform2 declaration with
alias-key = the key of the transform1.
The transform lookup algorithm for a key
my-key is as follows:
- Look for a transform2 with
key = my-key
- If not found, look for a transform2 with
alias-key = my-key
- If not found, look for a transforms1 with
key = my-key
In an old product, the
<url-reading-web-resource-transformer> will be ignored.
class2 attribute to your
In an old product,
class2 will be ignored.
In a new product, for a
web-resource only (ie not a
web-panel etc), the contract is to look for
class2 if it exists, otherwise use
class can be either a condition1 or a condition2 - in particular if you're implementing something for condition2 only,
class can be a condition2.