How to show image captions for non-standard image tags

Many customizations and advanced features in Image Source Control consist of adjustments for page builders, plugins, and themes to work with non-standard ways to display images, like Elementor or WP Bakery.

Since there are theoretically unlimited ways to do that, I cannot resolve them all within the plugin. However, I made it as simple as possible for other developers to add rules for custom HTML structures. If you struggle with it, consider hiring me.

Depending on your settings, Image Source Control recognizes any image URL and lists them in the Per-post and Global lists. This tutorial is about adding an image caption above or next to an image.

Please note that all the code examples are from the source code coming from your server, not how the browser interprets it. If you don’t understand these differences, please ask a developer for help.

Standard vs. non-standard images

The basic HTML to load an image is the img tag with a src attribute containing the URL to the image.

<img src="https://example.com/wp-content/uploads/garden.jpg">Code language: HTML, XML (xml)

Image Source Control also recognizes images in style attributes, which you can control and customize as described in Displaying Image Captions for Background Images.

<div style="background: url(https://example.com/wp-content/uploads/garden.jpg)">Code language: HTML, XML (xml)

The plugin also recognizes background images in the format of the Avada Builder:

<div data-bg="https://example.com/wp-content/uploads/garden.jpg">Code language: HTML, XML (xml)

The latter example would not display an image by default because the browsers don’t understand the data-bg attribute. Instead, these non-standard HTML codes often come with additional JavaScript to rewrite it into code the browser can understand. Unfortunately, at this point, it is too late for Image Source Control to add the caption code.

Tell ISC where to find the image URL

As a solution, you can use a filter to tell Image Source Control where to find the image URL and how to process it.

This needs a bit of custom coding and knowledge about regular expressions.

The filter to use for this is isc_pro_public_custom_attribute_processors. It accepts a multidimensional array with up to four attributes in each subarray. Let’s look at an example I built for a customer.

add_filter(
	'isc_pro_public_custom_attribute_processors',
	function ( $filters ) {
        // SPAN tag with data-bgsrc
		$filters[] = [
			'regex_pattern'        => '#<span[\x20|\x9|\xD|\xA]+[^>]*((data-bgsrc)="(.+)").*\/?>#isU',
			'replaced_match_index' => 1, // Index of the replaced string within the tag
			'url_match_index'      => 3, // Index of the URL in the regex match
			'enable_overlay'       => false,
		];

		// IMG tags mit data-img
		$filters[] = [
			'regex_pattern'        => '#<img[\x20|\x9|\xD|\xA]+[^>]*((data-img)="(.+)").*\/?>#isU',
			'replaced_match_index' => 1,
			'url_match_index'      => 3,
			'enable_overlay'       => true,
		];

		return $filters;
	},
	10,
	1
);
Code language: PHP (php)

The example adds two custom rules. Each rule has four attributes:

• regex_pattern is the regular expression to find the HTML element and the attribute that contains the image URL. I personally like to test regular expressions on regex.com.
• replaced_match_index is the index of the group containing the attribute and the image URL. Technically, it should be within the HTML element and end at a position where another HTML attribute can be added easily.
• url_match_index is the group index with the image URL without any surrounding characters. Image Source Control will look for the source of this image in the media library.
• enable_overlay is set to true if the image caption should be added to the HTML element and so become visible.

With the code above, the following examples

<span data-bg="https://example.com/wp-content/uploads/garden.jpg"><span>

<img data-img="https://example.com/wp-content/uploads/garden.jpg"/>Code language: HTML, XML (xml)

eventually become

<span data-bg="https://example.com/wp-content/uploads/garden.jpg" data-isc-source-text="©: Image Author Name" data-isc-images="123" />
  <span class="isc-source-text">©: Image Author Name</span>
</span>

<img data-img="https://example.com/wp-content/uploads/garden.jpg" data-isc-source-text="©: Image Author Name"/>Code language: HTML, XML (xml)

As controlled by the enable_overlay key in the array, the image source of the image in the span is printed, while the second example only loads it as an attribute into the original HTML.

Styling the image caption

Image captions added through this method are unstyled by default. You can use a custom CSS selector to style them. A matching selector for these elements and a basic styling is the following example:

*[data-isc-images] .isc-source-text {
    position: absolute;
	font-size: 0.9em;
	background-color: rgb(51, 51, 51);
	color: rgb(255, 255, 255);
	opacity: 0.7;
	padding: 0 0.15em;
	text-shadow: none;
	display: inline-block;
	right: 5px;
	bottom: 5px;
	z-index: 9999;
}Code language: CSS (css)

Using a custom plugin

You can use the code above in a new plugin, paste it into a custom code snippet manager or add it to your theme’s functions.php.

I’ve added the complete code for a custom plugin below for your convenience. Please create a new PHP file in your wp-content/plugins folder and paste the following code into it. Then, adjust the rules to your needs.

<?php
/**
 * Plugin Name: Image Source Control – Example.com
 * Description: Customizations for https://example.com/
 * Version: 1.0
 * Author: Thomas Maier, Image Source Control
 * Author URI: https://imagesourcecontrol.com/
 */
class ISC_Custom_Image_Elements {

	/**
	 * Constructor method for the class.
	 */
	public function __construct() {
		add_action( 'plugins_loaded', [ $this, 'plugins_loaded' ] );
	}

	/**
	 * Fires after all plugins have loaded.
	 */
	public function plugins_loaded() {
		// Check if ISC is enabled
		if ( ! defined( 'ISCPRO' ) ) {
			return;
		}

		add_filter(
			'isc_pro_public_custom_attribute_processors',
			function ( $filters ) {
				$filters[] = [
					'regex_pattern'        => '#<span[\x20|\x9|\xD|\xA]+[^>]*((data-bgsrc)="(.+)").*\/?>#isU',
					'replaced_match_index' => 1, // Index of the replaced string within the tag
        			'url_match_index'      => 3, // Index of the URL in the regex match
					'enable_overlay'       => true,
				];

				$filters[] = [
					'regex_pattern'        => '#<img[\x20|\x9|\xD|\xA]+[^>]*((data-img)="(.+)").*\/?>#isU',
					'replaced_match_index' => 1,
					'url_match_index'      => 3,
					'enable_overlay'       => false,
				];

				return $filters;
			},
			10,
			1
		);

		add_action( 'wp_head', [ $this, 'add_custom_css' ] );
	}

	/**
	 * Adds custom CSS to the head of the page.
	 */
	public function add_custom_css() {
		?>
		<style>
			*[data-isc-images] {
				position: absolute;
				font-size: 0.9em;
				background-color: rgb(51, 51, 51);
				color: rgb(255, 255, 255);
				opacity: 0.7;
				padding: 0 0.15em;
				text-shadow: none;
				display: inline-block;
				right: 5px;
				bottom: 5px;
				z-index: 9999;
			}
		</style>
		<?php
	}
}

// Initialize the plugin
new ISC_Custom_Image_Elements();
Code language: HTML, XML (xml)

Final notes

Keep the following in mind:

• The code examples here are from the source code delivered from your server, not your browser’s interpreted version.
• The layout will break if you inject an image source with a link into an HTML element wrapped in a link or a link itself. The only solution is to remove one of these links.

If you need help with custom coding, consider hiring me. You could also feed this tutorial into ChatGPT or other AI tools to help you with examples for your problem.