Popular searches webpthecdncreditsapi
View Categories

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 ShortPixelAITagRule  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 ShortPixelAITagRule('img', 'data-iconic-woothumbs-src');
    //eager attribute
    $regexItems[] = new ShortPixelAITagRule('img', 'data-large_image', false, false, false, false, true);
    //lazy srcset style attribute.
    $regexItems[] = new ShortPixelAITagRule('img', 'srcset', false, false, false, false, false, 'srcset', 'replace_custom_srcset');
    $regexItems[] = new ShortPixelAITagRule('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 ShortPixelAITagRule('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 ShortPixelAITagRule('a', 'href', false, 'data-rl_title', false, false, true);
    return $regexItems;
}

Custom replacement rules (frontend only)

If you need a rule to be applied to the frontend only, you can use the following filter in the same way as for the filter above:

add_filter('shortpixel/ai/customFrontendRules', 'my_function');

This rule is applied only if the "New AI engine" option is enabled in SPAI's settings. It is useful when you have content that is rendered by JavaScript and you need to do the replacement after the content is rendered. This is because the customFrontendRules are only executed by the vanilla JS in the browser; they do not modify the HTML code that is sent to them, as the other rules do. This way, they are able to respond to content that is rendered dynamically, or content that is not easily identifiable by the PHP part of the plugin that does not render the page, such as a link that does not have a class or a specific attribute.

Example

Suppose we have images from an HTML link (<div class="et_pb_gallery_image"><a href="#">Example</a></div>) and it has no attribute other than href . The snippet would look like this:

add_filter('shortpixel/ai/customFrontendRules', 'spai_the_gallery_ahrefs');
function spai_the_gallery_ahrefs($regexItems) {
    $item = new ShortPixelAITagRule('div.et_pb_gallery_image a', 'href');
    $item->frontEager = true;
    $item->frontResize = false;
    $regexItems[] = $item; 
    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" ....