ePub Image Automation 

Remember that an ePub document is similar in many respects to a web page. And, like a web page, the image is referenced within the text flow of the HTML document. Exactly where the image is referenced depends on how the image is placed within the original document, and the export options assigned.

Placing Images

For placing images in a document for ePub export, you have two options:

  • Anchor the image inside of the text
  • Place the image to the page unanchored

Anchoring Images

An anchored image flows with the text and can be anchored anywhere relative to its text story parent.

If an image has been placed on the page, one of the simplest ways to anchor it is to drag its little anchor box to the location desired within the text. (The anchor box is the little colored box at the top right of the image.)

Image alignment and spacing for the anchor can be determined in the Image panel of the EPUB Export Options dialog. Checking Settings Apply to Anchored Objects applies these settings to all anchored objects. However, these can be overridden by settings assigned to individual images using the Object Export Options menu item (in the Object menu).

Object Export Options

The Object Export Options dialog is one place you may visit frequently when working with images (as well as items you may wish to convert to images). Its first tab, Alt Text, is where you establish the alternate text that will be viewed by screen readers. And, yes, you do want all of your images to have meaningful alternate text. If you don’t determine the alternate text to use, Adobe InDesign kindly provides the image file name as the text. (This is most likely not what you want, but prevents the publication from failing validation.)

As you can see, there are a few hoops to jump through for each image you use in your document. Since this task may be repeated consistently it is an ideal candidate for automation.

Automation for EPub Images

A good place to start is with image processing. Here is another place that taking advantage of metadata can not only make your document more searchable, it can also be used to automate some processes. If the person who manages your images provides the necessary metadata, alternate text as well as image captions can be automated. Metadata can be added in Bridge or using the File Info panel in PhotoShop. In the minimum, you will want the author, description, title, and any pertinent copyright information included.

You can decide on the fields to use for the image caption and alternate text. Our sample script AnchorCenterWCap uses description for captions and title for alternate text.

The script expects an active insertion point within a document’s text flow. When run, the script automates the following:

  • Has the user choose the image from a pre-determined default location.
  • Places the chosen file and establishes its anchor settings.
  • If the file metadata includes a description, it adds a caption below the image.
  • If the file metadata includes a title, it assigns this as the alternate text.
  • If the file’s title metadata is not defined, it presents a dialog for entering the alternate text.

An outline of the script’s functionality is listed below:

AppleScript

set metaTitle to ""--initialize metadata title value
--get a reference to file chosen by user
set fileRef to choose file with prompt "Select file for placing"
--place the file and get its metadata
tell application "Adobe InDesign CC"
   set insertRef to item 1 of selection --assumes insertion point is selected
   tell insertRef
      set placedList to place fileRef --assumes placeable file was selected
      set imageRef to item 1 of placedList
      set containerRef to parent of imageRef
   end tell
   set linkRef to item link of imageRef
   set linkMeta to properties of link xmp of linkRef
   try 
      metaTitle to document title of linkMeta
   end try
   --add alternate text
   my addAltText (containerRef, metaTitle)
end tell

(*Sets alternate text for image if provided; otherwise user is presented dialog in which to enter text*)
on addAltText (containerRef, metaTitle)
   tell application "Adobe InDesign CC"
      set altSettings to object export options of containerRef
      if metaTitle is not "" then
         tell altSettings
            set alt text source type to source XMP title
         end tell
      else
         try
           set customText to my getString ("Please enter copy for alternate text", "")
           tell altSettings
              set alt text source type to source custom
              set custom alt text to customText
           end tell
         end try
      end if
   end tell
end addAltText

on getString (promptStr, dAnswer)
   activate
   set userResponse to display dialog promptStr default answer dAnswer
   if text returned of userResponse = "" then
      error "Valid string not entered"
   end if
   return text returned of userResponse
end getString

ExtendScript

var metaTitle = "" //initialize metadata title value
//get reference to file chosen by user
var fileRef = chooseFile("Select file for placing", "*.jpg", false);
//place image to active insertion point and get its metadata
var insertRef = app.selection[0];
var placedList = insertRef.place(fileRef);
var imageRef = placedList[0];
var containerRef = imageRef.parent;
var linkRef = imageRef.itemLink;
var linkMeta = linkRef.linkXmp;
try {
    metaTitle = linkMeta.documentTitle;
 } catch (e) {
     //do nothing
 }
//add alternate text
addAltText (containerRef, metaTitle);

//Sets alternate text for image if provided in metaTitle variable.
function addAltText (containerRef, metaTitle) {
   var altSettings = containerRef.objectExportOptions;
   if (metaTitle != ""){
       altSettings.altTextSourceType = SourceType.SOURCE_XMP_TITLE;
   } else {
       try {
           var customText = getString ("Please enter copy for alternate text", "", "Alternate Text");
           altSettings.altTextSourceType = SourceType.SOURCE_CUSTOM;
           altSettings.customAltText = customText;
      } catch (e) {
          alert ("Error: " + e);
      }
  }
}

//tests for string response from prompt dialog
function getString (userPrompt, defaultAnswer, dialogTitle){
   var userResponse = prompt (userPrompt, defaultAnswer, dialogTitle);
   if (userResponse == false || userResponse = "" || userResponse == undefined) {
      throw ("Invalid entry");
   }
   return userResponse;
}

//allows user to choose a file without validation 
function chooseFile (thePrompt, theFilter, multiSelect) {
   var localFileRef = File.openDialog(thePrompt, theFilter, multiSelect);
   if (localFileRef == null) {
      throw ("User cancelled");
   } else {
      return localFileRef;
   }
}

As you can see this code is just a skeleton of the script. What is important is the syntax for assigning metadata information as well as custom text for alternate text. This is found in the handler/function addAltText. Use this for your own super automation script. Watch for our sample scripts to be posted for download on both the AppleScript and ExtendScript pages.