Data Picture

Looking for WET v3.1?

As of September 23, 2014, version 3.1 of the Web Experience Toolkit is no longer supported. The source code and documentation have been moved to the wet-boew-legacy repository.

Questions or comments?

Purpose

Allow a web page to specify different image sources to display based on media queries. The component is an event driven port of Picturefill.

Use when

Working example

English example

French example

How to implement

  1. Add a data-pic element for each image that will have multiple sources: 
    <span data-pic="data-pic" data-alt="Alt tag for the image">
  2. Nested inside the data-pic element, specify the default image, different images sources and fallback image:
    1. Default image: image that will be displayed if no media queries match or the browser doesn't support media queries: 
      <span data-src="img/default.jpg"></span>
    2. Different image sources: images that will be displayed if their media query matches: 
      <span data-src="img/small.jpg" data-media="(min-width: 0px)"></span>
<span data-src="img/medium.jpg" data-media="(min-width: 500px)"></span>
<span data-src="img/large.jpg" data-media="(min-width: 960px)"></span>
    3. Fallback image: image to display if JavaScript is not supported: 
      <noscript><img src="img/fallback.jpg" alt="Alt tag for the image"/></noscript>

When you're finished, you should have an element that looks like the following:

<span data-pic="data-pic" data-alt="Alt tag for the image">
	<!-- Default image -->	
	<span data-src="img/default.jpg"></span>
	
	<!-- Images for browsers with CSS media query support -->	
	<span data-src="img/small.jpg" data-media="(min-width: 0px)"></span>
	<span data-src="img/medium.jpg" data-media="(min-width: 500px)"></span>
	<span data-src="img/large.jpg" data-media="(min-width: 960px)"></span>
	
	<!-- Fallback content for non-JS browsers. -->	
	<noscript><img src="img/fallback.jpg" alt="Alt tag for the image"/></noscript>	
</span>

Configuration options

All configuration options of the plugin are controlled with data attributes:

Option Description How to configure Values
data-pic Identifies this as an element that uses the data picture plugin. n/a
data-picture
The only supported value for the attribute.
data-alt Provides an alt attribute value to the image element created by the plugin. Set to the string value to use as the alt attribute.
None (default):
The image element created by the plugin will not have an alt attribute.
String:
The string will be used as the image element's alt attribute.
data-class Provides a class attribute value to the image element created by the plugin. Set to the string value to use as the image's CSS attribute.
None (default):
The image element created by the plugin will not have a class attribute.
String:
The string will be used as the image element's class attribute.
data-src Image source that will be used if this element's media query (specified by data-media) matches. Set to the image resource path that should be displayed.
None (default):
No image will be displayed if the media query matches.
Image path:
The image that will be displayed if the element's media query (specified by data-media) matches.
data-media Media query that determines when a given image source should be displayed. Set to the media query that should cause this element's image (specified by data-src) to display.
None (default):
The element is considered the default image and will be displayed if no media queries match or the browser does not support media queries. There can only be one default image source per data-pic element.
Media query:
The media query to match and determine if the element's image (specified by data-src) should be displayed.

Events

Document the public events that can be used by implementers or developers.

Event Trigger What it does
wb-init.wb-pic Triggered manually (e.g., $( "[data-pic]" ).trigger( "wb-init.wb-pic" );). Initializes the plugin and determines which data-pic image source should be displayed. Note: the data picture plugin will be initialized automatically unless it is added after the page has already loaded.
wb-ready.wb-pic (v4.0.5+) Triggered automatically after Date Picture initializes. Used to identify where Data Picture was initialized (target of the event) 
$( document ).on( "wb-ready.wb-pic", function( event ) {
});
$( "[data-pic]" ).on( "wb-ready.wb-pic", function( event ) {
});
wb-updated.wb-pic (v4.0.5+) Triggered automatically each time the picture is updated. Used to identify which picture was updated (target of the event) 
$( document ).on( "wb-updated.wb-pic", "[data-pic]", function( event ) {
});
$( "[data-pic]" ).on( "wb-updated.wb-pic", function( event ) {
});
picfill.wb-pic Triggered during plugin initialization and manually (e.g., $( "[data-pic]" ).trigger( "picfill.wb-pic" );). Causes the data-pic element to determine which image source should be displayed. This could be called as part of a window resize event handler.
wb-ready.wb (v4.0.5+) Triggered automatically when WET has finished loading and executing. Used to identify when all WET plugins and polyfills have finished loading and executing. 
$( document ).on( "wb-ready.wb", function( event ) {
});

Source code

Data picture source code on GitHub

Date modified: