Documentation

Version 2.8.0 (November 2022) contains an issue that prevents automatic updates from showing up. Please update manually to the latest version.

1. What ISC does and how it works

Image Source Control (ISC) allows you to manage image copyright information for all images on your website. In relevant places in your backend, you will find additional metadata input fields for each image. Among other options, this will be the copyright owner and their web address.

You may choose one or more of the following methods to show image sources:

• display an overlay with the credits on top of individual images
• display a list with credits for all images of the current page or post—the Per-page list
• display a site-wide register of all image sources on a dedicated page—the Global list

Behind the curtains, ISC creates an index of pages and posts and the images they contain. This index is used when the plugin warns about missing sources or creates the full image source list.

This “page–image index” is created when someone visits the page or post for the very first time after the indexing process started. Depending on the number of posts and visitors it might take some time to create the full index.

2. Installation

After your purchase, you will find the download link for ISC both on the confirmation page and inside your confirmation email. These links will be valid for 7 days.

As long as your license is valid, you may also log into your account and find the ZIP file linked in the Purchase history table. Click “View Details and Download” and scroll down to the end of the page for the download link.

If you have trouble downloading the files please see the Troubleshooting section.

2.1 Install ISC

In your WordPress backend go to Plugins > Add New > Upload Plugin^(?) and from your hard drive select the still zipped plugin file that you have downloaded in the previous step. After uploading the plugin file click on “Install Now”.

Make sure that any other versions of Image Source Control are disabled.

After installing click “Activate Plugin” or visit the Plugins overview to activate the plugin.

2.2 Activate the license key

You will find your license key on the confirmation page or in the confirmation email you receive after your purchase.

Go to Settings > Image Sources^(?) > License key and enter the license key for the plugin into the corresponding field. Click on the “Activate License” button.

Once the license is successfully activated the license key field turns uneditable.

2.3 Update ISC

Please note that a valid and activated license key is required to update Image Source Control.

If automatic updates are enabled, they will work just like the updates WordPress provides for other plugins.

You will see if a new version is available either in the Plugins overview or under Dashboard > Updates.

You may also find the latest version of Image Source Control on your account pages and run a manual install.

If you experience any troubles updating the plugin, please see the Troubleshooting section.

2.4 Do your first steps

This is totally optional but before you put any work into setting up Image Source Control we’ll quickly check whether the plugin works as intended. Please follow these simple steps:

1. Go to Settings > Image Sources^(?)
2. Under Per-page list check the boxes for “Insert below the content”
3. Under Overlay check the box for “Overlay”
4. Skip all other options
5. In Media > Library, select any editorial image that is placed in the main content of a page or post on your site and fill in the relevant “Image Source …” fields
6. Go to the page or post in which you are using the image; you should find the Per-page list injected at the bottom of the page or post and the Overlay above the image; if not and if you have caching by WordPress plugin or server software enabled, clear the corresponding cache
7. See the Troubleshooting section if you are experiencing any issues
8. Reach out to us if you need further help
9. You may uncheck all options from steps 2 and 3 until you’ve finished setting up Image Source Control

3. Plugin settings

All relevant settings will be made in Settings > Image Sources^(?). Don’t forget to save your changes at the very bottom of the settings page.

3.1 Position frontend elements

In this section, you will choose how and where ISC displays image sources. Each method comes with additional options to fine-tune it.

We generally recommend setting up and including the Global list and combining it with either the Overlay or the Per-page list—limited to one of both methods—if you like.

3.1.1 Overlay

This option will display the image source in the form of credits as an overlay on individual images. The credits have the format (Pre-text) (Copyright owner with link) | (License with link).

The Overlay should always be combined with either Per-page list or Global list since script and theme conflicts might cause it to not show up without you noticing.

The single option under “(Position of the image sources) Overlay” enables the Overlay for all images that meet the criteria set in the next step, site-wide.

Further down, under “Overlay”, there are four options to consider:

• Overlay pre-text
  Decide on which prefix, if any, you’d like to set before the author’s name. Popular choices are the copyright symbol (©) or the terms “Source:” or “Image source:”.
• Layout
  If you’re experienced in using Hypertext Markup Language and Cascading Stylesheets you may choose to disable all of ISC’s styling for the Overlay element and apply your own through this option. You can then use the isc_overlay_html_source hook to add your own markups and styling.
• Overlay position
  Seven options for easy repositioning of the Overlay element in reference to the image.

• Included images
  Which option to select here depends a lot on your specific site, your theme, and whether you have any copyright-protected imagery placed outside of the editorial content—for example in the navigation bar or in sidebars. When in doubt, select the strongest option, “Images on the whole page”. Compare to the Per-page list option of the same title.
• Developer options
  Experienced users can enable caption overlays also for background images within inline styles or between <style> tags. These options are described in detail in Displaying Image Captions for Background Images.

ISC offers additional options for the Overlay for experienced users.

3.1.2 Per-page list

This option enables the display of a source list of all images used on the current page or post. Under “(Position of the image sources) Per-page list” you may decide on placing the list manually using the shortcode—which we’ll describe later—or to have ISC automatically inject it below each page or post.

Here you may also choose whether and how to display image sources on archive pages like the category feed.

Further down, under “Per-page list”, there are two options to consider:

• Headline (self-explanatory)
• Included images
  Which option to select here depends a lot on your specific site, your theme, and whether you have any copyright-protected imagery placed outside of the editorial content—for example in the navigation bar or in sidebars. When in doubt, select the strongest option, “Any image URL”.

ISC offers additional options for the Per-page list for experienced users.

3.1.3 Global list

The Global list is a list of all images on all pages or posts of your whole website. Hence, it’s usually placed on a dedicated “Image sources” page or relevant existing pages such as “Imprint.”

Since the Global list is injected manually through shortcode—which we’ll go into shortly—, there’s nothing to set under “(Position of the image sources) Global list”.

Further down, you can choose the Included data in the “Global list.” When you enable thumbnails, you will also have a chance to select their size.

Bitte beachte, dass die Spalte „Angezeigt unter” nur Beiträge und Seiten aufführt, in deren Hauptinhalt Image Source Control das Bild gefunden hat. Wenn es dynamisch hinzugefügt wurde nachdem ISC den Inhalt bereits im Index hat, kannst du die Seite mit einer kleinen Änderung einfach neu speichern, so dass ISC sie erneut auf Bilder durchsucht.

Please note that the “Attached to” column only lists posts and pages where Image Source Control found images in their main content. If an image was dynamically added after ISC indexed the content, you could re-save the page with a minor change so that ISC searches for images again.

ISC offers additional options for the Global list for experienced users.

3.1.4 Manage licenses

ISC allows you to add individual licenses and optional links to the corresponding full license texts which will be available as choosable options when filling out copyright metadata on images.

The license name, linking to the full license text if applicable, will appear in all display varieties next to the copyright owner’s name.

Under “Image licenses” there are two options to consider:

• Enable licenses (self-explanatory)
• List of licenses
  This offers an editable list for you to add, modify, or delete licenses. We have supplied a pre-composed list but feel free to go wild. Note that the link to the full license text is optional. Stick to the format (License name)|(optional full URL) and don’t forget to save your changes at the very bottom of the settings page.

3.1.5 Miscellaneous settings

These aren’t priority settings but might come in handy later after you’ve gotten to know the base features of Image Source Control.

3.1.5.1 Define a standard source

Instead of handling the source of each image manually, you can define a standard source used for a number of images at the same time. This is an excellent option for when more than just a few of your images are licensed from a singular copyright owner or when they’re your own photos.

Under “(Miscellaneous settings) Standard source” there are two options to consider:

• Behavior of images marked with “Use standard source”
  Choose whether to display the uploader’s name (as displayed in the image’s metadata in the media library under “Uploaded by”), show custom text, or to display no source at all.
• Show the standard source for all images that don’t have a source
  This is a useful “catch-all” option to prevent any image to appear without at least some kind of copyright info.

You may activate or override the standard source when uploading images or later in the media library—we’ll go into this in the usage section.

3.1.5.2 Block options

The options to manage an image’s source information on a post edit page are either displayed in the media library overlay or in the block options for image-related blocks.

Enable the Block options setting to manage image source information in the block editor. Disable it if you experience problems with that feature or want to manage them in the media library overlay.

Please note:

• Changing image source information for featured images is only possible in the media library overlay.
• Block options only work for WordPress core blocks, not third-party blocks.

3.1.5.3 Elementor

Enable this option to show image sources for Elementor background images. Find out more on Elementor image captions.

3.1.5.4 Warn about missing sources

Tracking and handling missing source info is one of the key features of Image Source Control. This option will simply enable a warning to be displayed in your backend when ISC’s algorithms track down an image with its source info missing.

3.1.5.5 Enable the debug log

Here, the debug log function is activated. Ignore it for now, we’ll go into this in Troubleshooting.

3.1.5.6 Delete data on uninstall

If you ever consider uninstalling Image Source Control out of frustration, please contact us so we can figure out what went wrong and help you get out of our product what you expected to in the first place. Or more!

This option deletes ISC’s settings—meh, can be redone—but it also erases the image source metadata tables generated through ISC for your whole site. Which could be catastrophic for well-kept sites with hundreds or thousands of images. Ergo:

Do not enable this option unless you are one-hundred percent, absolutely, positively certain that you will never, ever again have use for the display of image sources by Image Source Control.

3.1.6 Use other methods

ISC offers several additional methods to display image sources. Please refer to the section for experienced users.

4. Fill in your image sources

Next, we’ll go through the places where you can fill in the necessary image source data.

4.1 Use the image block

This applies if you have the “Block Options” setting enabled.

When uploading or editing the image using the image block in the block editor, you will find the “Image Source …” fields in the block settings on the right.

Enter specific image source info or treat the image using the “Standard source” option.

4.2 Use the media library

You can also edit the image source in the media library.

1. Go to Media > Library
2. Click on the image’s thumbnail
3. Find the “Image Source …” fields on the right

Enter specific image source info or treat the image using the “Standard source” option.

4.3 Use batch-editing in the media library

This one’s a real timesaver, you’ll love it! In order to edit multiple images’ copyright metadata at the same time, ISC offers image source input fields on each item in the media library’s overview.

1. Go to Media > Library
2. Switch to list view and apply any filters needed
3. In the newly added “Image Sources” column, fill in the necessary copyright information for each item
4. Any information entered will be automatically saved, no need to press any save buttons

Choose to either enter specific image source info or treat the image using the “Standard source” option.

If you can’t see the image source column, flip open the “Screen Options” in the upper right corner and make sure that the box for “(Columns) Image Sources” is checked.

4.4 Track and handle missing sources

Image Source Control allows you to find images that don’t have source info associated with them, be it because they’re not placed on any page or post yet or because they’ve been placed with an external reference.

4.4.1 Images with unknown position

Here, ISC lists all images that …

• … are part of your WordPress media library but
• … haven’t had their source info registered yet

In order to track and handle these images follow these steps:

1. Go to Media > Image Sources
2. Find the images listed under “Images with unknown position”
3. Click on the image title to go to the image edit page
4. Enter the image source info and save

4.4.2 Additional images

Here, ISC lists all images that …

• … are not part of your WordPress’ media library and
• … haven’t had their source info registered yet

This generally applies to images that are hosted on external sites which you’ve placed in your pages or posts by referencing the external URL.

In order to track and handle these images follow these steps:

1. Go to Media > Image Sources
2. Find the images listed under “Additional images”
3. Click the button “Manage in the media library”
4. Now, under the hood, ISC will create a “virtual” post attachment dataset for this image so you may handle its source info in your WordPress’ media library as if it had been uploaded there
5. Enter the image source info and save

4.5 Use multiple links

You can use multiple links in your source string. For this to work, you need to separate the strings in the text field and URLs using commas. An empty URL value would skip one part of the source text.

E.g.,
Source: “Image Source Control, Features, Contact“
URLs: “https://imagesourcecontrol.com, , https://imagesourcecontrol.com/support/“
would become “Image Source Control, Features, Contact”

The additional URLs will be ignored if there are more comma-separated URLs than comma-separated texts.

5. Display your image sources

This section explains the usage of ISC’s own shortcodes and their parameters.

5.1 Display in Overlay

As described in section Overlay, the options under Settings > Image Sources^(?) > Position of the image sources > Overlay, apply to all images or images in specific HTML elements.

5.1.1 Disable the Overlay for specific images

You can disable the Overlay for specific images by adding the isc-disable-overlay class to them. You can do so on the <img> and <a> tags. For blocks with single images, i.e., no galleries, you can also add the class through the block options. Open Block > Settings > Advanced > Additional CSS class(es) to do so.

5.2 Display in Per-page list

You can find the option to have ISC automatically inject the Per-page list on each page, post, and archive page in Settings > Image Sources^(?) > Position of the image sources > Per-page list.

To manually place the Per-page list into any page or post, use the shortcode block to place the following shortcode in the specified page or post:

[isc_list]Code language: JSON / JSON with Comments (json)

There are no parameters available for this shortcode.

5.3 Display in Global list

To place the Global list that lists all images used on your whole site, either edit an existing static page or create a new one and place the following shortcode in it using the shortcode block:

[isc_list_all]Code language: JSON / JSON with Comments (json)

There are several parameters available. Simply append one or more to the shortcode, sticking to the format:

[isc_list_all parameter1="value1" parameter2="value2"]Code language: JSON / JSON with Comments (json)

• included="(all|included)"
  Use included="all" to list all images from your media library, including those not actively used in any posts and pages.
• per_page="(numeric value)"
  Use per_page="25" to have ISC list 25 images per page. If there are more, ISC will create additional pages and elements to navigate them.
• prev_text="(string value)"
  Use prev_text="« Previous" to have the corresponding element spell “« Previous” in the page navigation generated by ISC
• next_text="(string value)"
  Use next_text="Next »" to have the corresponding element spell “Next »” in the page navigation generated by ISC

As mentioned, you may append as many parameters as you want. For example:

[isc_list_all included="all" per_page="25"]Code language: JSON / JSON with Comments (json)

6. Unused Images

Take a look under Media > Unused Images to find an overview of images, which Image Source Control cannot find attached to any page or post.

Use the Deep Check to search for the image in post meta data and options. Images, not found by that check, can normally be removed.

Usage information

• Featured images are always considered “used”, even though it is possible that your current theme does not display them.

7. For experienced users

The information in this section is meant for developers who want to learn how Image Source Control works under the hood. It also contains examples for customizations.

Also, for users fairly fluent in the PHP scripting language, ISC offers several ways to further customize the plugin’s output.

7.1 Compatibility

ISC is supposed to work with the PHP versions that WordPress is officially supporting. If you find issues with official or upcoming PHP releases, then please let us know.

ISC supports browsers according to the WordPress Core Browser Support. I. e., Internet Explorer up to version 11 is not supported.

7.2 How ISC searches for images

ISC stores image source info as post meta for the attachment. When creating the source list in the frontend, ISC looks for attachment IDs in the frontend code following a few patterns created by WordPress standards.

In addition to that, the plugin also looks for image URLs. If they are missing an attachment ID the plugin tries to identify them based on the URL in the database. It looks for a match in the _wp_attached_file post meta field.

When looking for the original image URL in the database, ISC automatically removes strings only available for images in the frontend, like -scaled, rotated, or other additional classes added by WordPress.

If the image URL is changed in other ways, ISC might not be able to find it.

7.3 Where ISC searches for images

All display options—Overlay, Per-page list, and Global list—offer to include images that are placed on two or three levels of mark-up. Each method also covers the images found on the previous level:

Level 1—Images in the content

Available for Overlay, Per-page list, and Global list.

• any img tag in the content
• images in the WordPress gallery block
• images in the WordPress cover block

In addition, the Per-page list and the Global list will include featured images.

Level 2—Images on the whole page

Available for Overlay, Per-page list, and Global list.

• any img tag within the body tags
• including images in any sidebar

Level 3—Any Image URL

Available for Per-page list and Global list.

• background image—as set in WordPress—that is within the head tags
• image URL in a data attribute—for example
  <div class="e-gallery-image elementor-gallery-item__image" data-thumbnail="https://example.com/wp-content/uploads/2020/07/image.png" data-width="300" data-height="169" alt="…"></div>

7.4 How ISC indexes

ISC creates two indexes, which are stored as post meta values. The internal procedure is as follows:

1. A post with images in the content is visited for the first time
2. ISC looks through the content and creates an index that associates the post and all images with each other
3. ISC creates source captions if that option is enabled
4. ISC creates the list of sources below the content if that option is enabled; this is taken from the stored index created in step 2

When the post is visited for a second time, the index is not created again but taken from the stored value. Note that the index is created again on the next visit of the post if the content of the post was changed in the backend manually or automatically. Updating a post removes the index of isc_post_images.

Indexing behavior can best be examined when using the full source list:

• [isc_list_all] only shows images that are associated with a post already, i. e. indexed; you can see it growing with any new images indexed
• [isc_list_all included="all"] shows all images from the media library; the column for associated posts is empty when the index is not (yet) filled

Since the full source list is built from isc_image_posts, it will contain the information for posts that have been updated but not yet re-indexed by visiting it in the frontend. That data is updated as soon as the post is visited again.

Index “isc_post_images”

This index is stored with pages and posts. It contains an array of images that are either in the content of a given page or post or their featured image.

The list of image sources displayed below a page or post is built from this array.

Index “isc_image_posts”

This index is stored with images. It contains an array of IDs of posts in which images are either placed in the content or used as featured images.

Additional notes on indexing

Only images that are technically added to the content with a priority of lower than 20 for the_content are taken into account.

Indexing only works on single pages, not on archives. This decision was made to prevent cases in which some content on archive pages might be different from the original single page.

7.5 How ISC stores image URLs

ISC searches for the image ID of each image it finds in the frontend. When an image was added using the WordPress editors in the content of a post, the code often contains a hint to the image ID. If not, ISC takes the URL of the image and looks for it in the database. This needs additional database requests, which can take some time, especially when a site has many entries in the wp_posts table.

You can identify such queries using the Query Monitor plugin looking for the calls to attachment_url_to_postid() and ISC_Model::get_image_by_url(). They should only occur once for every time a new image is found.

The ISC storage is an index of image URLs and their corresponding image ID. ISC checks the storage before running a database query in wp_posts. Whenever an image URL was looked up, ISC adds it to the storage.

URLs of images that are not hosted in the media library are also stored so that they don’t cause unnecessary database requests.

The storage is permanent but can be cleared at any time under Media > Image Source > Debug > Clear storage. No critical data will be lost. The storage is saved in wp_options under the isc_storage key.

We advise clearing the storage if the URLs of your images change—for example when you move your site or the URL structure changes. If you don’t clear the storage then, it will add the new URLs on top, which causes the storage to grow unnecessarily.

The storage system is less critical if your site uses caching since that would prevent too many database queries after all.

7.6 Filter and action hooks

We’ll happily include more hooks to fit your needs—go ahead and contact us. To add your filter, proceed and use add_filter() as described in the WordPress Plugin API.

We recommend you look at the definition of the filters in the source code of ISC to learn how to use them exactly.

isc_images_in_posts

This allows you to register images with a post before the isc_post_images post meta information is saved—for example:

add_filter('isc_images_in_posts', 'your_images_in_posts_filter', 10, 2);
function your_images_in_posts_filter($image_ids, $post_id) {
	// look at the source code to see how the $image_ids array is structured
	return $image_ids;
}Code language: PHP (php)

isc_images_in_posts_simple

Similar to isc_images_in_posts above but to be used when saving the isc_image_posts meta. Register more posts that use a specific image—for example:

$image_urls = apply_filters('isc_images_in_posts_simple', $image_urls, $post_id);Code language: PHP (php)

isc_overlay_html_source

Use isc_overlay_html_source to add custom markup to the output of the Overlay source. Best used in combination with the “Remove markup and style” option—for example:

// Add custom output to the overlay
add_filter('isc_overlay_html_source', function($source = '', $image_id = 0) {
	return "<span class='image-source' style='font-weight: bold;'>$source</span>";
}, 10, 2);Code language: PHP (php)

This small plugin uses the filter and comes with sample CSS. Use it for your own experiments.

You can also use the isc_overlay_html_markup_before and isc_overlay_html_markup_after hooks to add a wrapper around the image that has the source. Check out the plugin’s source code to see how they are used.

isc_public_source_url_html

The isc_public_source_url_html filter can be used to manipulate the whole HTML that creates the source link—for example:

Remove “nofollow” from all source links

add_filter('isc_public_source_url_html', function( $source_link_html) {
	return str_replace('rel="nofollow"', '', $source_link_html);
});Code language: PHP (php)

Remove “nofollow” only from specific images

Please note: array(12, 123) just serves as an example and needs to be replaced with your own attachment IDs.

add_filter('isc_public_source_url_html', function($source_link_html, $attachment_id) {
	// the example works for images with the ID 12 and 123
    if(!in_array($attachment_id, array(12, 123), true)) {
		return $source_link_html;
	}
	return str_replace('rel="nofollow"', '', $source_link_html);
}, 10, 2);Code language: PHP (php)

isc_public_excluded_post_ids

Use the isc_public_excluded_post_ids filter to disable ISC functions on certain posts – or any other post type single pages in the frontend.

Here is an example to exclude the post ID 1323:

add_filter( 'isc_public_excluded_post_ids', function( $excluded_post_ids ){
	$excluded_post_ids[] = 1323;
	return $excluded_post_ids;
});Code language: PHP (php)

When ISC is excluded from a given page, the frontend index is also not running, which means that the images exclusively displayed on this post are not listed in the global source list as well.

7.7 Display functions

isc_list

Instead of using the shortcode [isc_list] you may place the Per-page list with the PHP function isc_list()—for example:

<?php
	if ( function_exists( 'isc_list' ) ) {
		isc_list();
	}
?>Code language: HTML, XML (xml)

isc_image_source

In order to list a singular image source in your frontend or in your template, use the function isc_image_source and hand over the image’s ID as noted in the media library as parameter $att_id—for example:

<?php
	if ( function_exists( 'isc_image_source' ) ) {
		isc_image_source( $att_id ); 
	}
?>Code language: HTML, XML (xml)

isc_thumbnail_source

In order to list the image source of the featured image or thumbnail of a post in your template—single page or archive pages within the loop—use the function isc_thumbnail_source and hand over the post’s ID as parameter $post_id—for example:

<?php
	if ( function_exists( 'isc_thumbnail_source' ) ) {
		isc_thumbnail_source( $post_id );
	}
?>Code language: HTML, XML (xml)

This is the recommended way to prevent other parts of your site from querying the excerpt and having the source string appear there—as described in section Per-page list.

7.8 Code Snippets

You can find more solutions in the following posts:

• Changing Plugin-generated Texts in the Frontend
• Displaying Image Captions for Background Images
• How to display and style captions for group background images

8. Troubleshooting

They are few but there are some issues you might run into when using Image Source Control. We’ll address the ones known to us in this section, feel free to contact us if you ever run into anything not mentioned here.

8.1 Known limitations

Accelerated Mobile Pages (AMP)

On AMP pages, the Overlay displays below the image. Since they don’t support custom JavaScript, on AMP pages we had to remove the script that would move the Overlay on non-AMP pages.

Multiple image source lists

If multiple image source lists are placed on the page or post, only the last one is filled with sources. This could lead to unexpected behavior when using multiple image source lists—for example on archive pages. Additional source lists might only contain the sources for images in the main content. This is relevant if you show sources for images outside the main content.

German umlauts in image URLs

German umlauts (i.e., äöüß) could lead to image URLs not being recognized and appropriate sources not being attached.

WordPress automatically converts these special letters when uploading the file, so this is only an issue with significant manipulation or for external images.

A manual solution to show the overlay for these images is to add the class wp-image-IMAGEID to the <img> tag, with IMAGEID being replaced by the real image ID. E.g., <img src"…" class="wp-image-543">.

Extensionless external images in CSS backgrounds

Image Source Control will not recognize image files that exhibit all of the following traits:

• they do not possess a proper file extension, e.g., .jpg, .jpeg, .png or .gif
• they are located on an external server and have been imported through ISC’s “Manage in the media library” feature
• they are referenced on your page or post by a background-image CSS property

To alleviate this problem, consider one of the following solutions:

• rename the image file to be suffixed by a proper file extension
• manually upload the image file to your media library
• reference the image file’s URL in a regular block in the block editor, e.g., an image block

Please let us know if you notice ISC not recognizing image files in other constellations.

Other media types

Image Source Control does not work out of the box with image types that cannot be uploaded into the WordPress media library by default, including SVG files. As with other media types like videos, ISC could manage sources and display them in lists, but a caption would possibly break their markup.

8.2 Setup issues

Trouble downloading the plugin

Your browser might be set up to automatically unzip all ZIP files upon completion of the download. Since WordPress expects plugin files to come in ZIP format, just go ahead and re-zip them on your hard drive before trying to upload them.

Trouble activating the plugin’s license

Firstly, your license should stay active during any renewal. If not—for example, after performing a manual renewal of your license—, please re-establish your license under Settings > Images Sources > Licenses by clicking the “Update License” button.

During activation of your license, your server needs to connect with ours for a short exchange of the license key. This may cause problems in a few cases. Please try one or more of the following:

• Please check your account to see whether your license is still valid and whether you have a sufficient number of activations left
• If the button doesn’t react at all, it could also be caused by a JavaScript issue; please check your browser console for any errors and let us know if they are caused by Image Source Control

Trouble updating the plugin

You might run into a problem while trying to update Image Source Control. Please check if one of the following corresponds to it:

• Error message that resembles “The package could not be installed. PCLZIP_ERR_BAD_FORMAT (-10) : Unable to find End of Central Dir Record signature”:
  Please ask your site administrator or web host to install or update the cURL.
• Error message that resembles “Download failed: Unauthorized”:
  Please follow the steps explained in the previous subsection to check and activate your license.

8.3 General issues

Image sources are not showing up

When image sources aren’t displayed in your frontend, one reason might be that your website is cached—by one of the popular WordPress caching plugins or by your server software. ISC cannot create the page-image index for cached page views. You can either wait for your cache to update automatically or clear it manually to have it start indexing.

Contact your site administrator or web host if you can’t clear the cache by yourself.

Otherwise, to debug missing sources, please try the following and see when and where source information starts to show up:

• enable the Per-page as well as Overlay options
• switch to a default theme like Twenty Twenty Three
• if you are using a page builder like Divi or Elementor, create a new page / post without it
• change the ISC settings to display image sources for images outside the content

ISC input fields are not showing up

On rare occasions, the input fields of Image Source Control are missing from the block properties in the sidebar—for instance, after converting the content of a post from a Classic block to Blocks.

Simply select the image block, use the button “Upload external image” in the context menu of the block, and the ISC input fields return in their usual position.

8.4 Debugging

8.4.1 Debug log

The debug log helps you retrace the scripted steps ISC takes whenever a page or post is queried that contains ISC elements. Follow these steps to enable and consult the debug log:

1. Go to Settings > Image Sources^(?) > Miscellaneous settings > Debug log, check the box, and save the settings
2. In your frontend, open the page or post you would like to log
3. Append ?isc-log to the URL and hit return to reload it with debugging enabled—mind that you’ll see no change
4. Go to (your-site.tld)/wp-content/plugins/image-source-control-pro/isc.log or use an FTP browser to consult the log

Replace ?isc-log with &isc-log if the URL already contains other GET parameters.

Unchecking the box under Settings > Image Sources^(?) > Miscellaneous settings > Debug log will remove the log file.

8.4.2 Debugging options

Under Media > Image Sources > Debug you will find four options to consider when running into problems:

• “List post—image relations”
  This will display a list of pages and posts and the images they contain.
• “List image—post relations”
  This will display a list of images and the pages or posts they are placed in.
• “Clear image—post index”
  This will remove the correlation between images and posts. The index is rebuilt automatically when a page or post with images on it is visited in the frontend.
• “Clear storage”
  This will cause ISC to clear the internal index of image URLs and IDs from the media library to limit the number of database requests in the frontend.

8.5 Replicating issues

To debug an issue on a site that is not yours, you could copy the whole HTML output to your local environment:

• Use a “Custom HTML” block to debug issues that relate to the content of posts (which then would run through the_content)
• Alternatively, create a new post template in the theme and copy the output there instead of the dynamic content to open that “page” locally

When testing code for image recognition locally, you need to change the IDs of the images in the code to different IDs that are locally hosted in your database—for example:

<img class="aligncenter wp-image-123 size-medium" src="300x250.png" alt="" width="300" height="200">Code language: JavaScript (javascript)

This would look for the attachment with the ID “123”, which wouldn’t work if you don’t have an attachment with the same ID in your database. Removing wp-image-123 allows a local installation to find the image if it is located in the database with a different ID.

8.6 Theme and plugin compatibility

Toolset Plugin

The Toolset plugin might cause image source overlays to appear twice. The solution is to enable the option “Do not apply third-party filters to the output” in the WYSIWYG field settings.