Background Attributes

These attributes are usable on all elements.

Each of these attributes has an image attribute counterpart:

The main difference is that each background attribute can accept a list of comma-separated values since CSS supports multiple background images per element.

As with CSS background properties, there is a one to one correspondence from one attribute to the next: the nth element of one attribute works in conjunction with the nth elements of the other attributes.

For instance, given:

<div
    class="twic"
    data-background="
        url(some_url_1),
        url(some_url_2)
    "
    data-background-focus="
        none,
        56px17p
    "
    data-background-transform="
        auto,
        cover=WxH
    " 
></div>

We know the element has two background images:

  1. some_url_1 with no specific focus point and with an auto transformation
  2. some_url_2 with a focus point of 56px17p and with a cover=WxH transformation

data-background

Default value: "none"

Specifies the urls of the background images.

<!-- single background -->
<img class="twic" data-background="url(some_url)">

<!-- multiple backgrounds -->
<img class="twic" data-background="url(some_url_1), url(some_url_2)">

The Script will only recognize and handle urls in the form of url(<value>) where <value> is a non-quoted, single-quoted, or double-quoted url. As such, it allows mixing automatically handled background images with non-image backgrounds, like so:

<div class="twic" data-background="linear-gradient(rgba(0, 0, 255, 0.5)), url(some_url)"></div>

Also note that the value of a url can be a placeholder expression.

<!-- single background -->
<img class="twic" data-background="url(placeholder:auto)">

Using a placeholder expression makes it very easy to spy on the actual dimensions of your background image whenever you're in doubt.

data-background-focus

Default value: "none"

Specifies the focus points for transformations. The values of this attribute must be valid coordinates or none.

<!-- single background -->
<div
    class="twic"
    data-background="url(some_url)"
    data-background-focus="152x467"
></div>

<!-- multiple backgrounds -->
<div
    class="twic"
    data-background="url(some_url_1), url(some_url_2)"
    data-background-focus="50px25p, none"
></div>

data-background-step

Default value: none (any value that is not a number or none will be ignored)

Enables overriding the default stepping value as specified in data-twic-step. Of course, if no value is provided, the default is used.

Stepping will round the computed width of background images to the closest multiple of data-src-step while also changing the height in order to respect the original aspect ratio as closely as possible.

Overriding the default may be useful to ensure pixel-perfect resizing or to limit the number of potential variants generated on different devices for this specific element (see data-twic-step for more details).

<!-- Pixel pefect -->
<div
    class="twic"
    data-background="url(some_url)"
    data-background-step="1"
></div>

<!-- A lot less variants -->
<div
    class="twic"
    data-background="url(some_url)"
    data-background-step="1000"
></div>

<!-- Both on multiple backgrounds -->
<div
    class="twic"
    data-background="url(some_url_1), url(some_url_2)"
    data-background-step="1, 1000"
></div>

data-background-transform

Default value: "auto"

Specifies the manipulations to be applied to each background image. The attribute accepts the full manipulation API.

<!-- single background -->
<div
    class="twic"
    data-background="url(some_url)"
    data-background-transform="resize=600x400"
></div>

<!-- multiple backgrounds -->
<div
    class="twic"
    data-background="url(some_url_1), url(some_url_2)"
    data-background-transform="cover=1:1/resize=200, contain=300x300"
></div>

As an addition, the Script provides two values, W and H, that represent the widths and heights of each background image in accordance with the background sizes computed by CSS. Those aliases can be used wherever the manipulation syntax accepts a number.

<!-- single background -->
<div
    class="twic"
    data-background="url(some_url)"
    data-background-transform="resize=WxH"
></div>

<!-- multiple backgrounds -->
<div
    class="twic"
    data-background="url(some_url_1), url(some_url_2)"
    data-background-transform="cover=WxH, contain=(W/3)x(H/3)"
></div>

Please note those values are rounded by default (see data-background-step).

As a convenience, the Script adds shortcut transformations contain, contain-max, contain-min, cover, cover-max, cover-min, max, min, resize, resize-max and resize-min which are equivalent to contain=WxH, contain-max=WxH, contain-min=WxH, cover=WxH, cover-max=WxH, cover-min=WxH, max=WxH, min=WxH, resize=WxH, resize-max=WxH and resize-min=WxH respectively.

<img class="twic" data-background="some_url" data-background-transform="contain">

<img class="twic" data-background="some_url" data-background-transform="cover">

The Script also provides an additional transformation which is used by default: auto. What this transformation does depends on the value of the various CSS background properties for the current image element. For instance, when background-size is cover, the auto transformation is equivalent to cover=WxH.

The auto transformation can be used into the data-background-transform attribute as part of more elaborate manipulations:

<!-- single background -->
<div
    class="twic"
    data-background="url(some_url)"
    data-background-transform="auto/max=600"
></div>

<!-- multiple backgrounds -->
<div
    class="twic"
    data-background="url(some_url_1), url(some_url_2)"
    data-background-transform="auto/resize=25p, auto/step=12"
></div>