Javascript library to integrate Pixboost into a web application that working directly on DOM tree (without shadow DOM), e.g. using JQuery, Backbone or other libraries.

Table of Contents:

• Usage
  • Responsive images
    • Operations
    • Supporting Breakpoints
    • Alt text
  • Non-responsive images
  • CSS Background images
  • Lazy Loading
• Configuration
  • Replacing on document load
  • Custom domain name
  • Reloading
    • Custom reload events
  • Disabling
  • Enabling by cookie
• Browsers Support
• Build
  • Using Docker

The easiest way to start using the library is to include it on the page and turn on autoload:

<script 
  type="text/javascript" 
  src="https://pixboost.com/libs/pixboost.bundle.min.js"
  id="pb-script"
  data-api-key="<YOUR PIXBOOST API KEY>"
  data-autoload=""
></script> 

pixboost.bundle.min.js script includes picturefill library that adds support of <picture> element to old browsers, lozad.js for lazy loading and matchMedia.js for supporting matchMedia() call in IE9.

autoload option will run picture(), image() and background() functions (see below) on document load.

Alternatively, you can include all components separately:

<!--Responsive images-->
<script type="text/javascript" src="https://pixboost.com/libs/picturefill.min.js"></script>

<!-- Lazy loading-->
<script type="text/javascript" src="https://pixboost.com/libs/lozad.min.js"></script>

<!-- Match media-->
<script type="text/javascript" src="https://pixboost.com/libs/matchMedia.min.js"></script>

<script type="text/javascript" src="https://pixboost.com/libs/pixboost.min.js"></script> 

Library provides three main functions:

• picture() - to deal with responsive images.
• image() - to optimise all images that are device agnostic.
• background() - for images that using CSS background

Library replaces all elements that have data-pb-picture attribute with <picture> tag. Picture tag will include different sources (images) for different CSS breakpoints (screen sizes).

For instance, for this element:

<div data-pb-picture
    data-lg="optimise"
    data-lg-url="https://yoursite.com/doggy.png"
    data-md="resize?size=300"
    data-md-url="https://yoursite.com/doggy.png"
    data-sm="fit?size=100x100"
    data-sm-url="https://yoursite.com/doggy.png"/>

when you run picture() function from the library:

    window.Pixboost.picture({apiKey: 'API_KEY'})

then div will be replaced with <picture> tag:

<picture>
    <source srcset="https://pixboost.com/api/2/img/https://yoursite.com/doggy.png/optimise?auth=API_KEY" 
        media="(min-width: 990px)">
    <source srcset="https://pixboost.com/api/2/img/https://yoursite.com/doggy.png/resize?size=300&auth=API_KEY" 
        media="(min-width: 640px)">
    <img src="https://pixboost.com/api/2/img/https://yoursite.com/doggy.png/fit?size=100x100&auth=API_KEY">
</picture>

Operations (data-<BREAKPOINT> attribute):

• optimise
• resize
• fit
• asis
• hide

You can specify operation arguments by adding them after operation name, e.g. fit?size=100x100

See more about operations here.

If you have the same source image for all operations then you can specify default URL:

<div data-pb-picture
    data-url="https://yoursite.com/doggy.png"
    data-lg="optimise"
    data-md="resize?size=300"
    data-sm="fit?size=100x100"/>

• lg - Large devices (desktops, 990px and up) @media (min-width: 990px)

• md - Medium devices (tablets, 640px and up) @media (min-width: 640px)

• sm - Small devices - everything below tablets

You can specify alt text for responsive images using data-alt attribute:

<div data-pb-picture
    data-alt="doggy"
    data-url="https://yoursite.com/doggy.png"
    data-lg="optimise"
    data-md="resize?size=300"
    data-sm="fit?size=100x100"/>

You can use library with <img> tag as well. Below is an example of image that will be replaced with resized version:

<img data-op="resize?size=x600" data-src="https://yoursite.com/doggy.png" data-pb-image/>

To process all images:

    window.Pixboost.image({apiKey: 'API_KEY'})

Background images are often used for hero banners or in cases where you need to put content on top of an image.

Below is a simple example of a hero banner:

<style>
    .hero {
        height: 600px;
        background-image: url("https://yoursite.com/hero.jpg");
        background-size: cover;
    }
</style>

<div class="hero" >
    <div class="content">This text is displayed on top of the image.</div>
</div>

In this example, we created hero banner and using "background-image" CSS rule to setup an URL for the image.

Using this library, you can optimise this image and also make it responsive. The syntax is exactly the same as for responsive images, but instead of using data-pb-picture attribute you should use data-pb-background:

<style>
    .hero {
        height: 600px;
        background-size: cover;
    }
</style>

<div class="hero" 
    data-pb-background=""
    data-url="https://yoursite.com/hero.jpg"
    data-lg="optimise"
    data-md="resize?size=990"
    data-sm="resize?size=640">

    <div class="content">This text is displayed on top of the image.</div>
</div>

The snippet above renders 3 different sizes for different devices. We don't need background-image CSS rule anymore as it created by the library.

You can kick off optimisation by calling background() function or use autoload:

window.Pixboost.background({apiKey: 'API_KEY'})

Lazy loading is supported for background images as well.

Lazy loading will not load image until it becomes visible to a user. Pixboost.js supports lazy loading for both responsive and non-responsive images. To enable lazy load you need to add data-lazy attribute to <div> or <img> elements.

<div data-pb-picture
    data-lazy
    data-url="https://yoursite.com/doggy.png"
    data-lg="optimise"
    data-md="resize?size=300"
    data-sm="fit?size=100x100"/>

<img data-pb-image data-lazy data-op="resize?size=x600" data-src="https://yoursite.com/doggy.png"/>

Lazy loading in Pixboost.js implemented by using 3rd party library lozad.js. In order to make it work, you'll need to use pixboost bundle (see Usage section) or add the library with polyfill for the Intersection Observer feature if you want to have support in all browsers:

    <script type="text/javascript" src="https://pixboost.com/libs/intersection-observer.min.js"></script>
    <script type="text/javascript" src="https://pixboost.com/libs/lozad.min.js"></script>

WARNING: In case of using polyfill make sure that you test your application in all browsers. We found some issues in IE (before Edge) and Safari with absolute positioning when using polyfill.

This is a short table of supported options that you can pass to <script> tag as attributes:

You can turn on automatic replacement by setting up data-autoload attribute on <script> tag:

    <script type="text/javascript" src="https://pixboost.com/libs/pixboost.js" 
        id="pb-script" 
        data-api-key="API_KEY"
        data-autoload></script>

If you have custom domain name setup then you can pass domain to the script tag using data-domain attribute:

    <script type="text/javascript" src="https://pixboost.com/libs/pixboost.js" 
        id="pb-script" 
        data-api-key="API_KEY"
        data-domain="static.yoursite.com"
        data-autoload></script>

Or you can pass it to picture() call:

  window.Pixboost.picture({apiKey: 'API_KEY', domain: 'static.yoursite.com'})

If you are fetching content using AJAX then you might want to run picture() and image() once requests finished. You can do this manually using window.Pixboost.picture() and window.Pixboost.image() call or you can trigger pbUpdate event:

    var pbUpdateEvent = document.createEvent("Event");
    pbUpdateEvent.initEvent("pbUpdate", false, true);
    document.dispatchEvent(pbUpdateEvent);

The library supports native DOM events and JQuery. You can specify a list of events separated by the comma in data-events or data-jquery-events attributes. For example,

    <script type="text/javascript" src="https://pixboost.com/libs/pixboost.js" 
            id="pb-script" 
            data-api-key="API_KEY"
            data-events="contentloaded"></script>

Then to trigger update:

    var contentLoadedEvent = document.createEvent("Event");
    contentLoadedEvent.initEvent("contentloaded", false, true);
    document.dispatchEvent(contentLoadedEvent);

And with JQuery:

    <script type="text/javascript" src="https://pixboost.com/libs/pixboost.js" 
            id="pb-script" 
            data-api-key="API_KEY"
            data-jquery-events="contentloaded"></script>

Then to trigger update:

    $(document).trigger("contentloaded");

You can globally disable URL transformations using data-disabled attribute.

    <script type="text/javascript" src="https://pixboost.com/libs/pixboost.js" 
        id="pb-script" 
        data-api-key="API_KEY"
        data-disabled></script>

Sometimes you would want to enable optimized images only if cookie presents. This is useful if you are using Optimizely or other AB testing services, so you can turn on optimization for a small amount of your customers in the beginning and increase it through time.

    <script type="text/javascript" src="https://pixboost.com/libs/pixboost.js" 
        id="pb-script" 
        data-api-key="API_KEY"
        data-cookie-enable="optimized-images"></script>

Value of the cookie must be set to true.

The library supports all major browsers including Chrome, Firefox, Safari and Internet Explorer. Internet Explorer 9 requires polyfill for <picture> and matchMedia implementations. For picture support, we are recommending to use picturefill version 3. Pixboost-js has integration with it and will call window.picturefill() once replacements are done. For matchMedia, we highly recommend matchMedia.js.

Lazy loading is using Intersection Observer feature that supports by all major browsers except for Safari. You can use polyfill, but make sure that you are doing thorough testing (see more details in lazy loading section).

There is a prepare to build a minified version of the library. It will be run on npm install execution. Result files will be generated into dist/ folder.

If you don't have Nodejs installed locally then you can use docker:

$ docker build -t pixboost-js .
$ docker run -v $(pwd):/app --rm pixboost-js