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 is false.
attributeFilter – An attribute filter. If it's set, only elements with this attribute will be replaced. The default is false.
false - Reserved.
attributeValueFilter – An attribute value filter. If it's set, only elements with this attribute value will be replaced. The default is false.
mergeAttr – Advanced usage (see plugin code). The default is false.
isEager – If true, 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 a srcset structure.
callback – Advanced usage (see plugin code). The default is false. Must be ‘replace_custom_srcset’ if the type is srcset.
quickMatch – Advanced usage (see plugin code). The default is false.
frontEager – Advanced usage (see plugin code). The default is false.

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