Skip to content

Latest commit

 

History

History
402 lines (296 loc) · 13.2 KB

README.md

File metadata and controls

402 lines (296 loc) · 13.2 KB

⚠️⚠️⚠️⚠️⚠️ THIS REPOSITORY IS ARCHIVED SINCE ALL POPULAR BROWSERS SUPPORT NATIVE LAZY LOADING AND THERE IS NO NEED TO LOAD ADDITIONAL JAVASCRIPT ⚠️⚠️⚠️⚠️⚠️

pixboost-js

Build Status

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

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

Responsive images

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

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"/>

Supporting Breakpoints

  • 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

Alt text

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"/>

Not responsive images

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'})

CSS background images

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

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.

Configuration

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

Option Description
data-api-key API key that will be used. If specified then no need to pass it manually to function calls
data-autoload If attribute presents then image() and picture() will be called automatically on document load
data-events List of DOM events (separated by comma) that will trigger update once fired.
data-jquery-events Similar to above data-events options, but using jQuery events
data-domain The domain name in case you set up a custom domain name for your account.
data-cookie-enable Name of the cookie that will need to be set to value “true” for images to be optimized.
data-disabled Will disable Pixboost and use original images.

Replacing on document load

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>

Custom domain name

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'})

Reloading

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);

Custom reload events

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");

Disabling

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>

Enabling by cookie

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.

Browsers Support

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).

Build

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.

Using Docker

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