For inserting a responsive <picture> element in your template, use the get_picture function or the get-picture API endpoint with the available parameters.

PHP

ResponsivePics::get_picture(id, sizes, classes, lazyload, intrinsic);

REST API

GET /wp-json/responsive-pics/v1/get-picture/<id>?sizes=<sizes>&classes=<classes>&lazyload=<lazyload>&intrinsic=<intrinsic>

Picture Parameters

For inserting a responsive <img> element in your template, use the get_image function or the get-image API endpoint with the available parameters.

PHP

ResponsivePics::get_image(id, sizes, crop, classes, lazyload, lqip);

REST API

GET /wp-json/responsive-pics/v1/get-image/<id>?sizes=<sizes>&crop=<crop>&classes=<classes>&lazyload=<lazyload>&lqip=<lqip>

Image Parameters

For inserting a responsive background image in your template, use the get_background function or the get-background API endpoint with the available parameters.

PHP

ResponsivePics::get_background(id, sizes, classes);

REST API

GET /wp-json/responsive-pics/v1/get-background/<id>?sizes=<sizes>&classes=<classes>

Background Parameters

The following image file formats are supported:

Any other image formats, will not be resizes or cropped.

The following syntax is available for each image size in the sizes parameter:

breakpoint:width

Since the <picture> element and background images support art directed images, the following full syntax is available for each image size in the sizes parameter:

breakpoint:width [/factor|height]|crop_x crop_y

You can use the following crop position shorthands in horizontal direction (x):

• l: left
• c: center
• r: right
• f: focal point (See the Focal Point section for more information)

And in vertical direction (y):

• t: top
• c: center
• b: bottom

If the vertical direction is not set, the horizontal direction x will be treated as a shortcut:

• c: center center
• t: top center
• r: right center
• b: center bottom
• l: left center
• f: focal point (See the Focal Point section for more information)

You can also use percentages as valid crop position syntax:

• 75 10: 75% from left, 10% from top
• 25 80: 25% from left, 80% from top
• 50 100: 50% from left, 100% from top (equals center bottom)

In this case both the coordinates x and y need to be passed.

When you want to crop an image but keep a certain area of the image in view, you can use the f(ocal) shorthand feature. In order to set this focal area of an image, we added a focal point picker interface to several views of the WordPress media framework.

Attachment Details

When clicking on a thumbnail from the WordPress Media Library grid view, you will see the Attachment details modal. This will be the most accurate view to select your focal point:

Featured Image

When setting or replacing an featured image in a page or post, you will see the Featured image modal. In this view you can select your focal point in the thumbnail at the top of the right sidebar:

Edit Image

When uploading or editing an image in the WYSIWYG editor or meta field in a page or post, you will see the Edit image modal. In this view you can select your focal point in the thumbnail at the top left:

There are 3 ways you can set the focal point of an image with the interface:

• By directly clicking on the desired focal point in the image.
• By dragging and dropping the focal point circle element on the image.
• By entering the Focal Point X & Y-axis values as percentages directly in the attachment input fields.

By using one of these options a post meta key named responsive_pics_focal_point will be added or updated to the attachment with an array value containing the x & y coordinates as percentages:

[
  'x' => '86',
  'y' => '39'
]

To use this value elsewhere in your theme, you can retrieve it by calling:

$focal_point = get_post_meta($attachment_id, 'responsive_pics_focal_point', true);

1. When visiting a front-end page and a ResponsivePics function call is made, this library will add the resize and/or crop image task as a job to the background process queue using Action Scheduler.
2. On every page load or on the next cron interval, Action Scheduler will run the next batch of jobs in the background process queue. See the Cron section for more information.
3. When a job is up next in the queue and ready to be processed it will execute the resize and/or crop task and save the image in the same location as the original image when successful and it will remove the job from the queue.
4. Once the image variation is created, it will skip the process of that variation on the next page load.
5. When you change one of the image size parameters, it will automatically try and create the new image variation on the next page load.
6. When the original image does not meet the dimension requirements of the requested image size, it will skip that image size variation and proceed to the next image size.
7. Alt text will automatically be added on the picture img element if the original image in the media library has one.

The background processing library Action Scheduler has a built in administration screen for monitoring, debugging and manually triggering scheduled image resize jobs. The administration interface is accesible via:

Tools > Scheduled Actions

Every resize job will be grouped by it’s wordpress image id.

When you are using the built-in WP-Cron, the background process queue will only process any tasks on every page load.

If you have disabled WP-Cron in your setup and you are using your own cron job on your server, Action Scheduler will use the interval set in that cron job to process the next batch of jobs.

define('DISABLE_WP_CRON', true);

If you’re using Trellis like us ❤️, the default cron interval is set to every 15 mins.
You could override this to for example 1 mins with an environment variable per wordpress site like this:

In for example trellis/group_vars/development/wordpress_sites.yml:

wordpress_sites:
  example.com:
    site_hosts:
      - canonical: example.test
        redirects:
          - www.example.test
    local_path: ../site # path targeting local Bedrock site directory (relative to Ansible root)
    admin_email: admin@example.test
    multisite:
      enabled: false
    ssl:
      enabled: false
      provider: self-signed
    cache:
      enabled: false
    cron:
      interval: 1

In trellis/roles/wordpress-setup/tasks/main.yml:

- name: Setup WP system cron
  cron:
    name: "{{ item.key }} WordPress cron"
    minute: "*/{{ item.value.cron.interval | default(15) }}"
    user: "{{ web_user }}"
    job: "cd {{ www_root }}/{{ item.key }}/{{ item.value.current_path | default('current') }} && wp cron event run --due-now > /dev/null 2>&1"
    cron_file: "wordpress-{{ item.key | replace('.', '_') }}"
    state: "{{ (cron_enabled and not item.value.multisite.enabled) | ternary('present', 'absent') }}"
  with_dict: "{{ wordpress_sites }}"

Don’t forget to re-provision your server after changing this value.

If an error occurs during the resizing process or if there’s invalid syntax, ResponsivePics will display or return an error.

PHP

ResponsivePics errors
- breakpoint xxs is neither defined nor a number

REST API

{
  "code": "responsive_pics_invalid",
  "message": "breakpoint xxs is neither defined nor a number",
  "data": {
    "xs": 0,
    "sm": 576,
    "md": 768,
    "lg": 992,
    "xl": 1200,
    "xxl": 1400
  }
}

When enabling the lazyload option in the ResponsivePics::get_picture() or ResponsivePics::get_image() functions or API endpoints, this library automatically:

• adds a lazyload class to the <img> element.
• swaps the srcset with data-srcset attributes on the picture <source> or the <img> elements.

This will enable you to use a lazy loading plugin such as Lazysizes or Lozad.

You can also set your own lazyload class by passing it to ResponsivePics library in your theme’s functions.php:

if (class_exists('ResponsivePics')) {
	ResponsivePics::setLazyLoadClass('lozad');
}

To install Lazysizes in your wordpress theme as a node module, run the following command from your theme directory:

npm

npm install --save lazysizes

Yarn

yarn add lazysizes

And import the package in your theme’s global javascript file:

import 'lazysizes';

see example

When enabling the lqip option in the ResponsivePics::get_image() function or /responsive-pics/v1/get-image API endpoint, this library automatically:

• adds a blur-up class to the <img> element.
• adds a fallback src attribute on the <img> element with a low quality placeholder image with a default width of 100px.

This will enable you to style your placeholder image before the actual high quality image is loaded.

You can also set your own lqip class by passing it to ResponsivePics library in your theme’s functions.php:

if (class_exists('ResponsivePics')) {
	ResponsivePics::setLqipClass('blurred');
}

see example

When enabling the intrinsic option in the ResponsivePics::get_picture() function or /responsive-pics/v1/get-picture API endpoint, this library automatically:

• adds a intrinsic class to the <picture> element and a intrinsic__item class to the picture <img> element.
• adds data-aspectratio attributes on the picture <source> and <img> elements with the calculated source image ratio.

This will enable you to pre-occupy the space needed for an image by calculating the height from the image width or the width from the height with an intrinsic plugin such as the lazysizes aspectratio extension.

To use the Lazysizes aspectratio extension in your wordpress theme, first install lazysizes as a node module as described in the Lazyloading section and import the extension in your theme’s global javascript file:

import 'lazysizes/plugins/aspectratio/ls.aspectratio.js';

see example