OpenWGA 7.10 - OpenWGA Concepts and Features
Design and development » File derivatesPredefining derivate queries for ranges
Specifying derivate queries for individual published files may be tedious. Also it is only possible if you are in control of every published file. This however is not the case in some situations:
- When images get embedded by authors using content modules or richtext fields
- When your design is customizable and someone may create a customization overlay on it with custom WebTML code
In both cases you cannot specify derivates directly because you are not in control of the entity that publishes the file.
However WebTML features a way to predefine derivate queries for a whole range of WebTML code. It only works for images, but this is the most common use-case for derivate predefinitions. Imagine your design defines a website section that is only 1024 pixels wide:
<div style="max-width:1024">
... custom code here ...
<div>
It is only natural that images that are displayed inside this <div> should adhere to the width restrictions here. While it is no problem if those images are a bit larger than 1024 - the browser scales them down automatically - they should not become much larger than that to save bandwidth.
The way to predefine image derivate queries is the attribute imagederivates of tag <tml:range>:
<tml:range imagederivates="width~1024">
<div style="max-width:1024">
... custom code here ...
<div>
</tml:range>
Any WebTML image publishing functionality inside this range will now automatically use the given image derivate query (publishing of other file types is not influenced). If this functionality again specifies its own derivate query then OpenWGA will merge the predefined and the specific query together. Terms of the specific query "overwrite" terms of the predefined query of equal name. The specific query can also use query term "clear" to ignore the predefined query completely:
<tml:range imagederivates="width~1024">
<div style="max-width:1024">
<tml:image file="photo.jpg" derivate="clear,height~1024"/>
<div>
</tml:range>
This example would ignore "width~1024" for the <tml:image> and only search for derivates of "height~1024".
There are also situations where inside a range with predefined query you do not want to use a derivate at all. Instead you want to return the original. For example: Having a "zoom" panel which displays an image in full size. For this your specific derivate query should include the term "none" which instructs the functionality to always return the original:
<tml:range imagederivates="width~1024">
<div style="max-width:1024">
<tml:image file="photo.jpg" derivate="none"/>
<div>
</tml:range>
In this example the <tml:image> tag would return the original although a predefined query exists.
When defining derivate queries for ranges that include a width/height restriction it is important that the factual space that the images have in this range is never bigger than was requested in the derivate query. Otherwise this may result in derivates being displayed in different sizes on different display devices.
Reason for this is the fact, that the size of the actual derivate that is put out most times will not match the requested width/height exactly. It will only be the derivate closest to this value yet bigger. Combine this with the fact that some display devices because of their "device pixel ratio" may display the same image smaller than others and it is possible that different output devices see derivates in different sizes. For example:
- An image is available as derivate of 600px width
- It is requested in the derivate query with "width~300" in a place that actually allows a width of 400px
- A device of device pixel ratio 1 loads it and displays it with 400px width, as the image is actually 600px wide and there is space for 400px
- A device of device pixel ratio 2 device loads it and displays it in 300px width, as it uses 2 physical pixels for one logical pixel, resulting in an image of 300px width