OpenWGA 7.10 - OpenWGA Concepts and Features

Design and development » File derivates

Querying file derivates

As designer of an OpenWGA design you can specify places in your WebTML code where the usage of derivates is appropriate/desired instead of the original. Choosing derivates is always up to the design of OpenWGA, never up to the author of content.

However you as a designer are seldomly in the situation that you can choose a specific derivate for a file as your code in most situations must cope with many different files with varying size, types etc. Instead you choose a derivate indirectly by specifying a derivate query. This is a query that describes the metadata of a derivate that would be appropriate for your usage. The result of a derivate query is either the choice of a derivate that matches the terms or a failure, meaning there are no matching derivates.

An example usage where derivate queries can be specified is the attribute derivate on <tml:image>.

<tml:image item="img" derivate="<derivate-query>"/>

This <tml:image> tag reads the image to display from an item and then queries the derivates of this image for something that matches the query.

Other places where derivate queries can be directly specified for individual files:

It is important to note that normally the derivate query is not executed when <tml:image> or <tml:url> is rendered but when the image/file is actually retrieved by the browser via request. The derivate query is passed on to this requests URL as URL parameter "derivate", so OpenWGA can execute the derivate query on this request. If the query fails OpenWGA will return an HTTP error status 412 "Precondition failed".

This is different with TMLScript function WGA.selectDerivate() which executes derivate query directly and presents the metadata of the best matching derivate.

 Derivate queries consist of a number of comma-separated terms:

<term>,<term>,<term>

To match the query a derivate must match the conditions in all given terms. Derivates that do not match one term are not considered.

Each term consists of a name, an operator and a value:

<name><operator><value>

Term names are predefined and identify the metadata that you want to query. For example: The name "usage" queries for a derivate of a certain usage type:

usage=poster

Every derivate is assigned a usage, which describes its relation to the original file. Currently the following usages are predefined in OpenWGA:

  • poster - An image representation of any file, showing its contents as it would be displayed on the screen in some typical viewing application, maybe available in multiple sizes. So: The contents of the first page of some PDF document, a smaller version of some image, the frame image of some video. This is by far the most important usage. OpenWGA automatically creates scaled down versions of attached PNG, JPG and BMP images under "poster" usage. Optional OpenWGA plugins may create "posters" for additional file types
  • icon - An image representation of any file, representing the type of the file, like file managers in operating systems often display for the same purpose.

The term above selects derivates of usage "poster". This usage has one special behaviour: If the original file is also an image then it is also considered when choosing an adequate "poster" derivate. If the original image matches the query terms better than any other derivate (or no derivate is available) then it may be returned as the "derivate" of choice. So it is safe to query for this usage regarding images as the original may still get returned if it matches the query best.

If a derivate query contains no "usage" term then usage "poster" is assumed as default. It is not possible to do a derivate query without a querying a usage, either explicitly or implicitly.

As the most frequent use of derivates is to display scaled down "posters" of images and other files we should also specify the size that we prefer. You can do this with term names width and height specifying the desired pixel sizes of these dimensions. For example:

width=1024

As the "equal" operator is in most situations of little use here - you seldomly know the configured sizes for the derivates to create and most likely must also cope with images that may be smaller than your desired size - both terms can be combined with some other operators. These are:

  • > or < or >= or <= - Specifying that the derivate must bigger/smaller than the specified value, optionally including the value itself. Derivates that are closer to the given value are preferred. Derivates that do not match this condition are not considered.
  • ~  - Specifies that the derivate should be bigger than or equal the given value. However this may also return smaller images if no bigger ones are available. In both cases sizes closer to the given value are preferred.

The "about" operator ~ is the one most frequently used. You do not need to know the concrete derivate size as it also selects bigger images. These bigger images are preferred over smaller images as they can be scaled down by the browser with little quality impact. However if an original image is actually smaller than desired by you it still is displayed (albeit not very pretty).

So this is a very typical use of a derivate query:

<tml:image item="img" derivate="usage=poster,width~1024"/>

In order to ensure that your image is really always displayed width 1024 pixel width you may want to combine the derivate query with some CSS style that enforces this width. For example:

<tml:image item="img" derivate="usage=poster,width~1024" cssstyle="max-width:1024"/>

The query terms "name", "width" and "height" are only three of the possible query term names. See all supported query term names in the following table:


Name Value and purpose Operators Example
<customFieldName> String. Value of a custom field stored as metadata on the file derivate. = myCustomField=myCustomValue
clear None. Instructs this derivate query to ignored a predefined derivate query and query a derivate using only the current terms. See "Predefined derivate queries for ranges". None clear
height Number. The height of images or videos in pixels. =
<
<=
>
>=
~
height~768
height>=768
id String. The ID of the derivate. = id=ff80818144d51c6a0144d52512ce0052
none None. Instructs this derivate query to ignored a predefined derivate query and return the original instead. See "Predefined derivate queries for ranges". None none
type String. A MIME media type. Either only the main type without slash, or main and subtype. = type=image
type=image/png
usage String. A valid derivate usage. Predefined are:
  • poster
  • icon
= usage=poster
width Number. The width of images or videos in pixels. =
<
<=
>
>=
~
width~1024
width>=1024