Documentation

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. Download and install ISC

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

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. Customize your 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 3.1.3 Global list and combining it with either the 3.1.1 Overlay or the 3.1.2 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 3.1.2 Per-page list or 3.1.3 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.
  • 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.

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.

For archive pages there are a few caveats to keep in mind:

  • Even if your theme doesn’t display post thumbnails on archive pages, the source might still be displayed
  • If other parts of your site query the excerpt, the source string might also appear there; see how to address this in the section for experienced users

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 on suitable existing pages such as “Imprint”.

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

Further down, under “Global list”, there are three options to consider:

  • Use thumbnails
    Decide on whether to have each list item—images and their sources—listed with an image thumbnail. Uncheck this to keep it lean and clean.
  • Thumbnails max-width (self-explanatory)
  • Thumbnails max-height (self-explanatory)

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 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.3 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.4 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

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.

Choose to either 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

Choose to either 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

5. Display your image sources

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


5.1 Display in Overlay

There are no individual display options, the Overlay feature can only be switched on or off site-wide for all specified images in Settings > Image Sources > Position of the image sources > Overlay, as explained in section 3.1.1 Overlay.


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


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


6.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 -scaledrotated, or other additional classes added by WordPress.

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


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

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


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


6.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)

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:

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)

6.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 3.1.2 Per-page list.

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


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


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

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

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.

Restoration of ISC input fields

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.


7.4 Debugging

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

7.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 mentioned above. 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.

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