These attributes are usable on all elements.
Each of these attributes has an image attribute counterpart:
data-background
is equivalent to data-src
data-background-focus
is equivalent to data-src-focus
data-background-step
is equivalent to data-src-step
data-background-transform
is equivalent to data-src-transform
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:
some_url_1
with no specific focus point and with an auto
transformationsome_url_2
with a focus point of 56px17p
and with a cover=WxH
transformationDefault 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.
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>
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>
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>