Documentation

1. What Image Source Control does and how it works

Image Source Control (ISC) consists of two significant features:

• Manage and display image copyright information
• Keeping track of where an image is used and identifying unused images

---

Behind the curtains, ISC indexes the public content and the images they contain. This index is used when the plugin warns about missing sources, creates the global image source list, or shows unused images.

2. Installation

After your purchase, you will find the download link for ISC on the confirmation page and inside your confirmation email. These links are valid for seven 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^(?). From your hard drive, select the still-zipped plugin file you 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.

Activate the license key

Your license key is on the confirmation page or in the confirmation email you receive after your purchase.

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

Once the license is successfully activated, the license key field will turn uneditable.

Updating the plugin

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

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

---

2.2 First steps

This is optional, but before you put any work into setting up Image Source Control, we’ll quickly check whether the plugin works as intended. Go to Settings > Image Sources^(?) and ensure the necessary modules are enabled. Then, follow the steps below.

Image Sources Module

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 “Enable.”
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.

Unused Images

1. Go to Media > Unused Images. The list might be pretty long. Don’t be irritated by that for now.
2. Click on the Run Indexer button at the top.
3. Start the indexer and let it finish.
4. Go back to Media > Unused Images. The list might be a lot shorter now.
5. Go to Media > Library and change into List View to see a list of all images and their appearance in the Appearance column. If you don’t see the column, enable it under Screen Options at the top right.

4. Fill in your image sources

Next, we’ll go through 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 bulk-editing in the media library

This one’s a real time saver—you’ll love it! To edit multiple images’ copyright metadata simultaneously, 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. Fill in copyright information in the Image Source Form column
4. Preview the information in the Image Source column
5. Any information entered will be automatically saved, no need to press any buttons

Choose to either enter specific image source info or treat the image using the Use standard option.

If you can’t see the image source columns, flip open the “Screen Options” in the upper right corner and check the appropriate boxes.

Filter by images source status

At the top of the Media Library in the list view, you can find a filter by the status of the image source, which makes it easy to identify images with missing or entered author information.

---

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”

You can also add a comma at the beginning of the source to leave the first section unlinked or a comma at the end to not link the last section.

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

5. Shortcodes

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

---

5.1 Display the 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)

You can list the image sources of a particular page using the id parameter. Replace 123 from the example below with the ID of your page.

[isc_list id="123"]Code language: JSON / JSON with Comments (json)

---

5.2 Display the 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 that 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.

Do the following before removing unused images:

1. Run the indexer under Media > Unused Images > Run Indexer
2. Run the Deep Check for each image. You can select multiple ones and use the bulk options.

Usage information

• Featured images are always considered “used,” even though it is possible that your current theme does not display them.
• There is a chance of false positives when an image ID equals a value in an option. E.g., imagine an option min_screen_size with the value 1200. If you had an unused image with the ID 1200, then the option name might pop up as a potential usage for that image. The combination of requirements makes this very rare, though.
• The pagination is built incrementally. I.e., it starts looking for the first 100 unused images starting with the lowest attachment IDs. You can navigate to page 2 of the list to see the next 100 images. From here, you can navigate to page 3, etc. ISC remembers the total number of pages you have already visited.

Media Library: Appearances

With the Unused Images module, you will also find the Appearances column in the media library list view. It shows the pages in which an image was found.

If you don’t see it, you can enable it under Screen Options at the top right of the screen.

Indexer

While the Deep Check looks for image URLs and IDs in the database, the Indexer goes through all published content in the frontend and looks for used image URLs.

For the first time or whenever you update a lot of content, you can go to Media > Unused Images > Run Indexer and run the index to update it. Please don’t close the page until the indexer finishes; you’ll need to restart it.

Whenever you add, update, or delete content, the index is updated the next time that content is visited in the frontend.

Limitations:

• Image URLs dynamically created, e.g., using JavaScript, are not indexed.
• Make sure that your frontend is accessible to users who are not logged in.

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 officially supports. If you find issues with official or upcoming PHP releases, please let us know.

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

See also Compatibility for known issues between WordPress plugins and themes.

---

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 types of indexes:

• Post meta values
  • isc_post_images stores the image IDs in the content of public posts. This index is used to build the Per-post list.
  • isc_image_posts stores the IDs of posts in which an image appears. This index is used to build the Global list.
• The table isc_index stores image-post relations for the Unused Images feature

Indexes are created when a post was visited for the first time or after it was updated.

When the post is visited for a second time, the index is not created again but taken from the stored value.

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 Global 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.

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 Display functions

Ideally, Image Source Control options are sufficient to insert image captions to your liking. In rare cases, you might want to use one of the public functions below to show an individual or list of image sources.

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.6 Code Snippets & Customization

See also Customizations and find more solutions in the following posts:

• Adding overlays to images with dynamic URLs
• Changing Plugin-generated Texts in the Frontend
• Displaying Image Captions for Background Images
• How to show a caption for a background image of the Group block
• How to show image captions for non-standard image tags
• The CSS to overlay text on images in WordPress

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.

See also Compatibility.

---

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

Image URLs in the frontend don’t match the Media Library

If image sources don’t show up, the cause might be that the URLs in the frontend don’t match the image URLs in the Media Library. This is always due to custom code in plugins or themes.

The problem and solution are explained in detail in Adding overlays to images with dynamic URLs.

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 Data missing after migration

Standard WordPress migration methods, including the built-in Tools > Export feature for Media, should transfer the ISC metadata along with your images. Ensure your migration process includes the wp_postmeta table.

Important: After migrating, the ISC index will be outdated or incorrect. You must rebuild the indexes on the new site.

• Go to Media > Image Sources > Tools
• Click the Clear image-post index button.
• The index will rebuild automatically as pages are visited, or you can run the indexer manually via Media > Unused Images > Run Indexer.

For specific tools like WP All Import, you may need to manually map ISC’s post meta keys during import configuration.

---

8.5 Debugging

8.5.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. Find the link to the log in the setting mentioned in step 1. Open the link to see the log file. It is different on each website.

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.5.2 Debugging options

Under Media > Image Sources, you will find some debug tools you can use when running into problems:

• Post Index > List post-image relations
  This will display a list of pages and posts and the images ISC found in their content. The Global List is generated from these entries. If you find some images missing, remove the row for that page here, and ISC will reindex it when next visited in the frontend.
• Post Index > List image-post relations
  This will display a list of images and the pages or posts they are placed in. The Per-page List is generated from these entries.
• Post > Index > 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 is visited in the frontend.
• Storage > Clear storage
  This will tell 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.6 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.