Script

Learn how to use the TwicPics script to benefit from context-aware media optimization in your web pages.

The Script enables lazy loading together with automatic and dynamic sizing of your images. Lightweight and non-intrusive, this small piece of JavaScript only handles elements you specifically marked beforehand.

Setup

Installation

You simply have to include the Script from your own domain in your webpage. It is accessible through https://<sub>.twic.pics/?v1.

<script async defer src="https://<sub>.twic.pics/?v1"></script>

Replace <sub> with your own subdomain. You can find it in the "Domains" section of the back-office.

That's it, you're all set!

Integration

If you want the Script to handle the source of an img element, the poster of a video element or the background image of any DOM element, simply specify a data-twic-src, data-twic-poster or data-twic-background attribute respectively:

<!-- image -->
<img data-twic-src="image:<path_to_image>" />

<!-- poster -->
<video data-twic-poster="image:<path_to_image>">
  <!-- background -->
  <div data-twic-background="url('image:<path_to_image>')"></div>
</video>

Please note how src and poster turned into data-twic-src and data-twic-poster and how the background image is now specified in the data-twic-background attribute rather than in CSS.

In all cases, the source image is https://<subdomain>.twic.pics/<path_to_image> but the Script will make sure it is sized properly based on the CSS context of the element by generating the proper API calls for you.

Dynamic Behaviour

The Script will only issue an API call and actually load your image when the corresponding element becomes visible. So everything is lazy-loaded by default given you as fast an initial page load as possible.

You don't have to write any code. Everything is controlled declaratively using HTML attributes and CSS properties. Feel free to browse the script attributes reference for more information.

Lazy Loading

By default, the Script will load marked images only when needed. It will wait for an element to come into view before loading its source, poster or background images. This will help tremendously when it comes to the initial page load.

Sometimes, however, you may need images to be loaded in bulk, like in the case of a slideshow. In such a case, you can mark a container as a view:

<div data-twic-view>
  <!-- content -->
</div>

Every marked element inside the container will be loaded as soon as the container itself comes into view.

If, for any reason, you wish to disable lazy loading entirely, simply mark the body of your page as a view:

<body data-twic-view>
  <!-- no lazy loading! -->
</body>

DOM Manipulation

The Script is always observing changes in your document:

it will detect newly inserted elements with a data-twic-src, data-twic-poster, data-twic-background or data-twic-view attribute
it will react whenever a TwicPics attribute is modified
it will re-assess image sizes if dynamic changes occur in your layout

Global Configuration

The script can be configured by adding specific parameters to the Script URL. All parameters come with a default value that should suit most users.

anticipation

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

The Script will lazy-load media by default. To avoid too abrupt a transition with elements appearing into view and then media very obviously loading afterwards, the Script will "anticipate" lazy loading by a factor of the actual viewport. This behaviour is controlled by anticipation.

With the default of 0.2 and for a viewport 800 pixels wide per 600 pixels high, the Script will consider as visible any element within a rectangle going from coordinates (-160,-120) to coordinates (960,720). You could set anticipation to 1 and anticipate lazy loading by an entire screen: the rectangle where elements are considered visible would then go from (-800,-600) to (1600,1200).

<!-- anticipate lazy-loading by half a screen -->
<script async defer src="https://sub.twic.pics/?v1&anticipation=0.5"></script>

<!-- anticipate lazy-loading by an entire screen -->
<script async defer src="https://sub.twic.pics/?v1&anticipation=1"></script>

class

Default value: "twic"

In the rare occurrence where twic is already in use on your page and you wish to avoid any potential collision, you can use this script parameter to change twic into something else entirely.

Note that every occurrence of twic must be replaced with whatever name you set this script parameter to.

So, the following configuration:

<script async defer src="https://sub.twic.pics/?v1&class=batman"></script>

implies that:

attributes names are changed:
- data-twic-background becomes data-batman-background
- data-twic-background-* attributes become data-batman-background-*
- data-twic-bot becomes data-batman-bot
- data-twic-focus becomes data-batman-focus
- data-twic-poster becomes data-batman-poster
- data-twic-poster-* attributes become data-batman-poster-*
- data-twic-src becomes data-batman-src
- data-twic-src-* attributes become data-batman-src-*
- data-twic-step becomes data-batman-step
- data-twic-transform becomes data-batman-transform
views should be marked with data-batman-view rather than data-twic-view
lifecycle class names are changed:
- twic-loading becomes batman-loading
- twic-done becomes batman-done
- twic-error becomes batman-error
- twic-poster-loading becomes batman-poster-loading
- twic-poster-done becomes batman-poster-done
- twic-poster-error becomes batman-poster-error
- twic-background-loading becomes batman-background-loading
- twic-background-done becomes batman-background-done
- twic-background-error becomes batman-background-error

max-dpr

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

The Script will take the Device Pixel Ratio of the current device into consideration when determining the sizes of media to load. While this is the best approach in theory, it may clutter the bandwidth of portable devices with a high DPR but a fairly small screen surface relatively.

By default, the Script will not take a DPR greater than 2 into consideration. If the DPR of the device is higher than 2, the Script will assume it to be 2.

To alter this behaviour, change the value of max-dpr:

you can lower it (for instance by setting it to 1, effectively ignoring the DPR altogether)
or you can be more permissive (for instance by setting it to 3 or 4)

<!-- ignore DPR -->
<script async defer src="https://sub.twic.pics/?v1&max-dpr=1"></script>

<!-- handle DPR up to 4 -->
<script async defer src="https://sub.twic.pics/?v1&max-dpr=4"></script>

path

Default value: ""

The Script will prepend all your TwicPics image paths with the string provided through path. This is especially useful to easily switch from one environment to another (like between a staging and a production environment).

Let us take the following domain configuration as an example:

path	source images URL
`/staging`	`https://staging.my-company.com/`
`/prod`	`https://www.my-company.com/`

<!-- targets https://staging.my-company.com/ -->
<script async defer src="https://sub.twic.pics/?v1&path=staging/"></script>

<!-- targets https://www.my-company.com/ -->
<script async defer src="https://sub.twic.pics/?v1&path=prod/"></script>

The following image element:

<img data-twic-src="image:asset.jpg" />

will target

https://staging.my-company.com/asset.jpg if path is set to staging
https://prod.my-company.com/asset.jpg if path is set to prod

The value of path is added "as-is", so you have to be extra-careful with slashes and how you handle them. If all your image: URLs start with a slash, like image:/asset.jpg then path should not end with one. If, however, you do not have a leading slash in your image: URLs, as in image:asset.jpg , then path should end with a slash.

step

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

The default step for videos is 100. Any values below will be ignored.

To avoid requesting too may variants of the same medium (as could happen in the case of width: 100% elements for instance), the Script will round the width of media to the closest multiple of step. The height will then be computed so as to respect the original aspect ratio.

For instance, with the default of 10, if the Script is told by CSS the size of an element is 334x146, it will round it down to 330x144. Alternatively, for an element that is 336x222, it will round the size up to 340x225.

You can change this value to get as close or as far from a pixel-perfect resizing as desired:

lowering it to 5 would potentially double the number of variants requested,
lowering it to 1 would be pixel-perfect all the time,
adjusting it up to 1000 would greatly reduce the number of variants but would stress the scaling algorithms of browsers more.

Note that the stepping value can still be overridden on a per-element basis using the data-twic-step attribute.

<!-- Pixel perfect -->
<script async defer src="https://sub.twic.pics/?v1&step=1"></script>

<!-- Less variants -->
<script async defer src="https://sub.twic.pics/?v1&step=50"></script>

Components

Essentials