Manipulate PositionedImage and wrap text around image in Google Docs

Question

I used the following snippet to insert an image into a Google Document:

// Source: http://stackoverflow.com/a/18859986/1536038
var doc = DocumentApp.openById         


        

Answer 1

Issue 1529 has been fixed. As of December 2015, Google Apps Script can manipulate PositionedImage objects in Google Docs.

---

They behave a little differently than InlineImage elements, as they need to be anchored to a ListItem or Paragraph element, while InlineImages can be added only to Body, FooterSection, HeaderSection or TableCell elements.

A PositionedImage is an object anchored in an element, while an InlineImage is itself an element of a document. This implies that you cannot convert one type of image directly to the other. (When you switch an image from "Wrap text" to "Inline" using the UI, the PositionedImage is removed from its anchor paragraph, then inserted into the body of the document outside of that paragraph. You could emulate that via script if necessary.)

Insert a PositionedImage

Here's an example of a PositionedImage inserted by the following script:

// http://stackoverflow.com/a/20661113/1677912
function DemoPositionedImage() {
  // Get handle on active document
  var doc = DocumentApp.getActiveDocument();

  // Find desired image file
  var matchedFiles = DriveApp.getFilesByName('apple-touch-icon.png');
  if (matchedFiles.hasNext()) {
    // Get image object from file
    var image = matchedFiles.next().getBlob(); 

    // Add image as a PositionedImage.
    var positionedImage = doc.getBody().getParagraphs()[0].addPositionedImage(image);

    // Adjust layout, etc. here

    // Log the ID of the new image
    Logger.log( positionedImage.getId() );
  }
}

The log shows the ID of the new image, like this:

[15-12-11 20:35:03:706 EST] kix.9dwnzjfapdy8

Be careful - if you add multiple images to the same element (e.g. Paragraph), with default layout, the newest image will overlay existing ones. Therefore, it may look like you have a single image when there are actually a pile of them.

Retrieve existing PositionedImages

Since a PositionedImage is not an element of a document, it does not appear in the element hierarchy with elements like paragraphs, tables, or InlineImages, and cannot be found through the document methods getChild(), getNextSibling(), and so on. Likewise, there is no Body.getPositionedImages() to parallel Body.getImages().

Instead, you can get a PositionedImage using its unique ID, e.g. kix.9dwnzjfapdy8 from the earlier example.

var positionedImage = getPositionedImage(storedId);

Alternatively, you can get all the PositionedImage objects in a containing element as an array.

var positionedImages = getPositionedImages();
for (var i=0; i<positionedImages.length; i++) {
  Logger.log( positionedImages[i].getId() );
}

Retrieving all the PositionedImages in a document requires traversing all the possible anchor elements. The following utility does just that.

/**
 * Get a list of all PositionedImages in a document.
 * See stackoverflow.com/a/20661113/1677912.
 *
 * @param {String} docId         (optional) ID of document to scan
 *
 * @returns {PositionedImage[]}  Array of PositionedImages in document
 */
function getAllPositionedImages( docId ) {
  // Open document if given ID, otherwise use active document.
  if (docId) {
    var doc = DocumentApp.openById(docId);
  }
  else {
    doc = DocumentApp.getActiveDocument();
  }

  // Get handle on document's body
  var body = doc.getBody();

  // array to hold all images in document
  var allPositionedImages = [];

  var numElems = body.getNumChildren();

  for (var childIndex=0; childIndex<numElems; childIndex++) {
    var child = body.getChild(childIndex);
    switch ( child.getType() ) {
      case DocumentApp.ElementType.PARAGRAPH:
        var container = child.asParagraph();
        break;
      case DocumentApp.ElementType.LIST_ITEM:
        container = child.asListItem();
        break;

      default:
        // Skip elements that can't contain PositionedImages.
        continue;
    }
    // Collect images from current container
    var imagesHere = container.getPositionedImages();
    allPositionedImages = allPositionedImages.concat(imagesHere);        
  }
  return allPositionedImages;
}

Layout control

Most of the layout controls for PositionedImages are well described in the documentation:

• Height: setHeight(), getHeight()
• Width: setWidth(), getWidth()
• LeftOffset: setLeftOffset(), getLeftOffset()
• TopOffset: setTopOffset(), getTopOffset()
• Layout: setLayout(), getLayout()

The PositionedLayout enum used with the Layout methods is unique to PositionedImages. At the time of launch of PositionedImage support however, it was not included in editor autocompletion, and the documentation contained no examples of its use. Let's fill that gap.

Here's how you can set the layout of a PositionedImage so that it is wrapped by text:

positionedImage.setLayout( DocumentApp.PositionedLayout.WRAP_TEXT );

The following utility function gets the English equivalent of a PositionedLayout enum.

/**
 * Get the string representing the given PositionedLayout enum.
 * Ref: https://developers.google.com/apps-script/reference/document/positioned-layout
 *
 * See stackoverflow.com/a/20661113/1677912.
 *
 * @param {PositionedLayout} PositionedLayout  Enum value.
 *
 * @returns {String}         English text matching enum.
 */
function getLayoutString( PositionedLayout ) {
  var layout;
  switch ( PositionedLayout ) {
    case DocumentApp.PositionedLayout.ABOVE_TEXT:
      layout = "ABOVE_TEXT";
      break;
    case DocumentApp.PositionedLayout.BREAK_BOTH:
      layout = "BREAK_BOTH";
      break;
    case DocumentApp.PositionedLayout.BREAK_LEFT:
      layout = "BREAK_LEFT";
      break;
    case DocumentApp.PositionedLayout.BREAK_RIGHT:
      layout = "BREAK_RIGHT";
      break;
    case DocumentApp.PositionedLayout.WRAP_TEXT:
      layout = "WRAP_TEXT";
      break;
    default:
      layout = "";
      break;
  }
  return layout;
}

Note: This has been concurrently posted on my blog.