Picturefill.WP

A WordPress plugin to use picturefill.js to load images mimicking the proposed HTML5 picture spec.

Author:Kyle Reicks (profile at wordpress.org)
WordPress version required:3.2
WordPress version tested:3.9.1
Plugin version:1.3.5
Added to WordPress repository:17-04-2013
Last updated:03-08-2014
Warning! This plugin has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues when used with more recent versions of WordPress.
Rating, %:100
Rated by:7
Plugin URI:http://github.com/kylereicks/picturefill.js.w...
Total downloads:8 834
Active installs:80+
plugin download
Click to start download

Note: This is an implementation of Picturefill.js version 1.2.x. For an implementation of Picturefill.js 2.x, see the master branch of the GitHub repository.

Picturefill.WP is a simple and option-less plugin to serve HDPI and responsive images on a WordPress website.

This plugin parses post and page content replacing images with a special syntax similar to the proposed syntax for the HTML5 picture element, then uses an adapted version of picturefill.js to load the appropriate image to the browser.

Considerations before installing

Slow Loading on Activation

The first time a page or post is loaded after activating Picturefill.WP, new @2x size images will need to be created for the images in the post or page content. This can take several seconds and will take longer on image heavy posts. Once these images are created, posts should load at least as fast or faster than they do without the plugin.

If you are installing Picturefill.WP on a large and image heavy site, you may want to consider using another plugin like Regenerate Thumbnails to create the new image sizes for existing posts and pages.

500 or 504 server errors

These errors are related to the slow loading listed above. If the server reaches its timeout limit before it is finished processing new images, it will return a 500 or 504 error. Refreshing the page usually gives the server the time it needs to finish processing the images. On some image-heavy posts, it may take more than one refresh.

Image Sizes

By default, WordPress creates as many as 3 images of different sizes for each uploaded image ("large", "medium", and "thumbnail"), in addition to the "full" image size.

This plugin adds responsive breakpoints based on the width of the image. The largest available image will display unless the browser width is less than the image width + 20px, in which case the next size down is displayed.

To use this plugin most effectively, set the default image sizes ("large", "medium", and "thumbnail") to reflect useful breakpoints in your theme design.

Errors and Warnings

As of version 1.3.3 Picturefill.WP suppresses errors and warnings in parsing the DOM. Errors and warnings can now be collected via the picturefill_wp_syntax_present_libxml_errors and picturefill_wp_get_images_libxml_errors filters.

add_filter('picturefill_wp_get_images_libxml_errors', 'handle_errors');

function handle_errors($errors){
  foreach($errors as $error){
    // Handle errors here.
  }
}

Theme CSS

As described in the Details section, the picturefill.js syntax uses nested span elements. If a theme's CSS applies styles to un-classed span elements, you may notice some of these spans showing up unexpectedly on the page after activating Picturefill.WP. If possible, it is best to remove the offending code from your theme files, but adding the flowing to the bottom of your theme's CSS file should also work to reset these styles.

span[data-picture]{display:inline;margin:0;padding:0;border:0;}
span[data-picture] span{display:inline;margin:0;padding:0;border:0;}

Caching

To improve performance, especially in image heavy posts, Picturefill.WP uses transient caching. The cache will be refreshed automatically every time a post is updated or Picturefill.WP is updated. The cache can be manually refreshed by deactivating and reactivating Picturefill.WP from the plugins menu.

If you suspect that Picturefill.WP's caching is causing trouble with another plugin or theme feature, first try deactivating and reactivating Picturefill.WP. If problems persist, try lowering the priority for Picturefill.WP to be executed by adding the following to your functions.php file:

remove_filter('the_content', array(Picturefill_WP::get_instance(), 'apply_picturefill_wp_to_the_content'), 11);
add_filter('the_content', array(Picturefill_WP::get_instance(), 'cache_picturefill_output'), 9999);

If you still encounter problems with other plugins or theme features, you may want to disable caching all together. See the subsection on how to disable caching under the "Extending Picturefill.WP" section of the GitHub repository.

FAQ
ChangeLog