Actions, filters and developer options of ShortPixel Adaptive Images
ShortPixel Adaptive Images calls the following actions and filters. Here you can also find other configurations that you can add to your website as a developer.
Custom replacement rules
As you know, every time one of your website's pages is visited, ShortPixel Adaptives Images (SPAI) analyzes the code and replaces the URL of each original, non-optimized image with the URL of the right-sized optimized image. Each replaced image is served from the ShortPixel CDN.
The plugin looks in the most typical places where image URLs are located, such as in the src
attribute of img
tags. However, if your URLs aren't recognized correctly by our plugin, you can add your own replacement rule.
First, add this filter to the functions.php file of your theme:
add_filter('shortpixel/ai/customRules', 'my_custom_spai');
The my_custom_spai
function is given an array and should append elements of type ShortPixel\AI\TagRule
to it: [ 'tagName', 'attrToBeChecked', 'classFilter', 'attributeFilter', false (reserved), 'attributeValueFilter', isEager (bool), 'type', callback (bool), quickMatch (bool), frontEager (bool) ]
.
The elements of the array are, in this order:
tagName
– The name of the HTML tag.attrToBeChecked
– The attribute to be replaced.classFilter
– A class filter. If it's set, only elements with this class will be replaced. The default isfalse
.attributeFilter
– An attribute filter. If it's set, only elements with this attribute will be replaced. The default isfalse
.false
- Reserved.attributeValueFilter
– An attribute value filter. If it's set, only elements with this attribute value will be replaced. The default isfalse
.mergeAttr
– Advanced usage (see plugin code). The default isfalse
.isEager
– Iftrue
, the image will be replaced server-side and not lazy-loaded. Otherwise the image will be lazy-loaded.type
– Advanced usage (see plugin code). The default is‘url’
. It can also be‘srcset’
if the image has asrcset
structure.callback
– Advanced usage (see plugin code). The default isfalse
. Must be‘replace_custom_srcset’
if the type issrcset
.quickMatch
– Advanced usage (see plugin code). The default isfalse
.frontEager
– Advanced usage (see plugin code). The default isfalse
.
Example 1
Here's a real-world example of custom image attributes, a custom srcset
and a custom JSON data attribute:
add_filter('shortpixel/ai/customRules', 'spai_to_iconic'); function spai_to_iconic($regexItems) { //lazy-loaded data-iconic-woothumbs-src attribute $regexItems[] = new ShortPixel\AI\TagRule('img', 'data-iconic-woothumbs-src'); //eager attribute $regexItems[] = new ShortPixel\AI\TagRule('img', 'data-large_image', false, false, false, false, true); //lazy srcset style attribute. $regexItems[] = new ShortPixel\AI\TagRule('img', 'srcset', false, false, false, false, false, 'srcset', 'replace_custom_srcset'); $regexItems[] = new ShortPixel\AI\TagRule('div', 'data-default', 'iconic-woothumbs-all-images-wrap', false, false, false, false, 'srcset', 'replace_custom_json_attr'); return $regexItems; }
Example 2
Imagine you have this section
tag on your website:
<section id="hero" data-images="["https:\/\/deltidsbrandman.se\/wp-content\/uploads\/2022\/12\/brandman-2.jpg"]" class="hero-slideshow-wrapper hero-slideshow-normal"></section>
As you can see, this example is a bit more complicated because the image is contained in an array. In this case, we'd insert the snippet as follows:
add_filter('shortpixel/ai/customRules', 'spai_handle_section_data_images'); function spai_handle_section_data_images($regexItems) { $regexItems[] = new ShortPixel\AI\TagRule('section', 'data-images', 'hero-slideshow-wrapper', false, false, false, true, 'srcset', 'replace_custom_json_attr'); return $regexItems; }
Example 3
Suppose we have images in tags like this one:
<a href="....." data-rl_title>
In this case, the snippet to add is:
add_filter('shortpixel/ai/customRules', 'spai_lightbox'); function spai_lightbox($regexItems) { $regexItems[] = new ShortPixel\AI\TagRule('a', 'href', false, 'data-rl_title', false, false, true); return $regexItems; }
Filenames with size suffix
If you have main images (not thumbnails) in the Media Library whose filename ends with the usual thumbnail size suffix (e.g. -100×100
), please add this in the wp-config.php file:
define('SPAI_FILENAME_RESOLUTION_UNSAFE', true);
JavaScript post-processing
If you want to do post-processing in JavaScript after the image/tag has been updated by ShortPixel AI, you can add a callback like this:
jQuery( document ).ready(function() { ShortPixelAI.registerCallback('element-updated', function(elm){ // elm is the jQuery object, elm[0] is the tag console.log("element updated: " + elm.prop('nodeName')); }); });
Change original URL
To change the original URL of the image detected by ShortPixel, use this filter that receives the original URL:
add_filter('shortpixel/ai/originalUrl', 'my_function');
Force cropping
Sometimes, when the Smart crop option is enabled, ShortPixel AI thinks it is not safe to crop an image, but you want to crop it anyway. Please add this attribute to force cropping:
<img data-spai-crop="true" ....