Displaying Image Captions for Background Images

How to implement image source captions for CSS background images.

Background images pose the greatest challenge for Image Source Control when it comes to displaying image sources as captions directly on the image. This is primarily due to the fact that the insertion of new HTML can disrupt the code of the entire page.

Until now, the only official solution was to incorporate the image sources via the Per-page list below posts or in the Global Source List on a dedicated page. But now, I have succeeded in displaying these directly on the element with the background image.

In addition to an already existing solution for image captions in Elementor, I have now developed two more solutions for the following scenarios:

  • style attributes within HTML tags, e.g. <div style"…">
  • Contents of <style> tags.

The underlying use case for this was the compatibility with Kadence Blocks, namely Galleries and Kadence Related Content Carousel.

In the following, I explain how these options can be used to display image sources for background images. The options described here and the code listed should best be used by developers who understand the side effects. Customers of the “Small Agency” package can also ask our support for help with customizations.

Settings

The settings for the options mentioned here can be found under Settings > Image Sources > Overlay > Included Images > Developer Options.

Developer options to display image sources and captions for CSS background images.

The options are deactivated by default. You will learn below when and how you can use which option.

Limitations

Images are found based on the option chosen under Overlay > Included Images, i.e., in the post content or in the entire source code.

Both solutions currently only work with one image URL per attribute or tag.

The image URL must be surrounded by url(). However, it does not matter whether and which quotation marks are used.

The URL must contain a valid image file extension.

Line breaks and additional spaces in the code can affect the detection of the URLs. To adjust the detection, we need more concrete examples. You can send these to us via support.

Always check the output of the overlay carefully. Also, look into the source code to see if it appears in the correct place. Dynamically adding HTML to an existing page can always cause problems, which is why we only recommend the functions mentioned here to developers.

Notes about Styling

The output of the code with the source information in the frontend is unstyled by default. You can adjust the position and layout with your own CSS.

An unstable way to style and place the source information for inline styles and style blocks like normal images is to give the parent element the class isc-source. So for inline styles, the styled HTML tag. Otherwise, the parent element of the .isc-source-text element.

In most cases, our script for automatic placement of the source overlay code leads to layout shifts. Therefore, we have decided against automatic styling.

Sometimes it helps to give the element with the isc-source class, a display: block;.

Background images for the Group block

WordPress 6.4 introduced background images for the Group block.

You can find a dedicated tutorial on how to show captions and style them in How to display and style captions for group background images.

Avada Builder

Image Source Control supports background images for the Avada Builder. Displaying and styling them works similarly to the information given on this page.

For more information, see also Avada Builder (Compatibility).

Inline Styles

“Inline Styles” are CSS styles that are embedded directly into the HTML tag. An example of an inline style with a background image would be:

<div style="background-image: url('backgroundimage.jpg');"></div>Code language: HTML, XML (xml)

By default, Image Source Control displays the image source for backgroundimage.jpg in the Per-page list below the content, if you have activated the option Per-page list > Included Images > Any Image URL in the settings. An overlay does not show up, even if the Overlay option is enabled. This is possible with the help of the following two options:

  • Load the overlay text for inline styles
  • Display the overlay within HTML tags that use inline styles

Load the overlay text for inline styles

This option loads the text for the overlay into the data-isc-source-text attribute of the HTML tag. Our example above would then look like this:

<div style="background-image: url('backgroundimage.jpg');"
  data-isc-source-text="(c) Author’s Name"></div>Code language: HTML, XML (xml)

The content of data-isc-source-text corresponds to the source information as it would also appear in the Per-post list, including escaped HTML for the links.

You can now decide for yourself where and how you want this image source to appear. The following JavaScript code creates a new <span> tag within our <div> container and then writes the image source into it.

<script>
  window.onload = function() {
    // Select all div elements with data-isc-source-text attribute
    var elements = document.querySelectorAll('div[data-isc-source-text]');

    elements.forEach(function(el) {
      // Create a new span element
      var span = document.createElement('span');

      // Add class to the span
      span.classList.add('isc-source-text');

      // Get the text from the data-isc-source-text attribute
      var text = el.getAttribute('data-isc-source-text');

      // Set the text of the span element
      span.innerHTML = text;

      // Append the span element to the div
      el.appendChild(span);
    });
  };
</script>
Code language: HTML, XML (xml)

The result then looks like in the next section.

In line 4, you can adjust the selector if you are not using <div> tags or refine it to only target certain elements. In line 11, you can assign a different class than the standard one.

Display the overlay within HTML tags that use inline styles

Diese Option geht noch einen Schritt weiter als die obere und erzwingt die Ausgabe der Quellenangabe im Container mit Hilfe von PHP. Das Ergebnis sieht dann wie folgt aus.

This option goes one step further than the previous one, forcing the caption with the image source information in the container using PHP. The result then looks like this.

<div style="background-image: url('backgroundimage.jpg');" data-isc-images="123">
    <span class="isc-source-text">(c) Author’s Name</span></div>Code language: HTML, XML (xml)

It is possible that the output of the caption in the HTML element breaks a dynamic function. This is possible, for example, with sliders.

The data-isc-images attribute contains the ID of the found image. It is important for the technical process and can be ignored.

Style Elements

Mit “Style-Blöcken” meine ich <style> Tags mit enthaltenen CSS Regeln. Hier ein Beispiel mit einer CSS-Regel, die ein Hintergrundbild für einen Container festlegt.

By “Style Elements,” I am referring to <style> tags with CSS rules in them. Here is an example with a CSS rule that sets a background image for a container.

<style>
    .styled-container { background-image: url('backgroundimage.jpg'); }
</style>
<div class="styled-container"></div>Code language: HTML, XML (xml)

Image Source Control would also display the image source for backgroundimage.jpg in the Per-post list below the content, but not as a caption directly on the image. This is possible with the help of the following two options:

  • Load the overlay text for style tags
  • Show the overlay after style tags

Load the overlay text for <style> tags

This option loads the text for the overlay into the data-isc-source-text attribute of the <style> tag. Our example above would then look like this:

<style data-isc-source-text="(c) Author’s Name">
    .styled-container { background-image: url('backgroundimage.jpg'); }
</style>
<div class="styled-container"></div>Code language: HTML, XML (xml)

The content of data-isc-source-text corresponds to the image source information as it would also appear in the Per-post list, including escaped HTML for the links.

You can now decide for yourself where and how you want this source to appear. The following JavaScript code creates a new <span> tag below our <style> tag and then writes the image source into it.

<script>
  window.onload = function() {
    // Select all div elements with data-isc-source-text attribute
    var elements = document.querySelectorAll('style[data-isc-source-text]');

    elements.forEach(function(el) {
      // Create a new span element
      var span = document.createElement('span');

      // Get the text from the data-isc-source-text attribute
      var text = el.getAttribute('data-isc-source-text');

      // Set the text of the span element
      span.innerHTML = text;
      // Set the class of the span element
      span.classList.add('isc-source-text');

      // Add the span element after the style tag
      if (el.nextSibling) {
        el.parentNode.insertBefore(span, el.nextSibling);
      } else {
        el.parentNode.appendChild(span);
      }
    });
  };
</script>
Code language: HTML, XML (xml)

The result then looks like in the next section.

In line 4, you can adjust the selector if you are not using <style> tags or refine it to only target certain elements. In line 16, you can assign a different class than the standard one.

Show the overlay after <style> tags

This option forces the output of the image source information in the <style> tag, using PHP. The result then looks like this.

<style>
    .styled-container { background-image: url('backgroundimage.jpg'); }
</style>
<span class="isc-source-text">(c) Author’s name</span>
<div class="styled-container"></div>Code language: HTML, XML (xml)

In our example, the styled <div> container directly follows the style block. If that’s the case, a bit of CSS should help to overlay the caption over the styled element.

In reality, however, you will also find many style blocks that refer to an element in a completely different place in the source code. In this case, you must use the above method to load the source as an attribute into the tag and then move it to the correct place with the help of JavaScript.

Portrait of Thomas Maier, founder and CEO of Image Source Control

Questions? Feedback? How can I help?