How-to library · Developer docs

How-to library

Task-shaped pages: a title that starts with a verb, the situation in a few lines, the steps, the working code in both engines, and why this way rather than another. Found from a search, done, and left.

How-to Images

Import a legacy site's externally hosted images during a migration

Published

Turn on Import external images, re-save the migrated records, check the file manager, and turn it off again. Every image hotlinked in rich text is copied in at its source path and the content pointed at the copy.

Context

Context. Migrated rich text still points at the old site's images, and breaks the day that site is switched off. With Import external images on, saving a rich-text area in the admin or through the API downloads each embedded image from another host into the file manager, at the same path it had on the old site, and rewrites the content to the local copy. It is off by default, and should be on only for the duration of the migration.

Steps

  1. Turn on Import external images in the image settings.
  2. Re-save every migrated record: in the admin, or through the API by writing the record's content back unchanged. Each image is fetched during the save, with up to five seconds allowed per image, so a long page saves slowly.
  3. Check the file manager for the imported folders and spot-check a few pages signed out.
  4. Turn the setting off. Left on, anything an editor pastes from anywhere is copied into the site, whether or not it may be.

Code

HTML 
<!-- before the re-save -->
<p><img src="https://old.example.com/uploads/2019/team.jpg" alt="The team"></p>

<!-- after: the copy is stored at the source path under /files/ and the content updated -->
<p><img src="/files/uploads/2019/team.jpg" alt="The team"></p>
Template code 
{* nothing changes in templates: rich text renders as it always did *}
{$page->body}
{{ page.body }}

Why this and not that

Not a script that rewrites the HTML to new paths and uploads separately: the setting does both in one save and keeps the image's original path, so any other content linking the same image resolves to the same file. Not leaving it on: copyright, slow saves and path collisions, where two sites that both had /images/logo.png share one file, and the second import shows the first site's logo. During a re-run, set the duplicate strategy to Update so a re-imported image replaces the earlier copy behind the same filename instead of being renamed.

Go deeper
GuidePicture tags and responsive sources GuideFolders, filenames and file revisions

Was this page helpful?

Your answer goes to the docs team.