5 Curiosities about Placeholders in Word Content Controls (for developers)

Content Controls are an excellent way to provide 'prompt' text for users. The 'prompt' text (eg "Click here and type the manager's name" or "Choose the date of your report") is provided through a placeholder.

This article discusses some of the oddities about these placeholders in the Word object model.

PlaceholderText is an object, not text

A ContentControl object has a PlaceholderText property. You'd be forgiven for thinking it would return a String. But you'd be wrong!

A Word content control's .PlaceholderText is a BuildingBlock object.

To set the placeholder text, you need something like:

MyContentControl.SetPlaceholderText Text:="Click here and type the report title"

Or, you can set the placeholder text to refer to a range or an existing building block.

To read the placeholder text, use the .Value property:

MsgBox MyContentControl.PlaceholderText.Value

The PlaceholderText object is prone to disappearing

You can't count on the PlaceholderText object being available. It frequently disappears. So wrap all references to the .PlaceholderText object in some error checking. Something like this:

Dim cc As ContentControl

    'Assume there is at least one content control in the document
    Set c = ActiveDocument.ContentControls(1)

    'Set the placeholder text
    If Not cc.PlaceholderText Is Nothing Then
        cc.SetPlaceholderText Text:="My text here"
    End If

Word often doesn't know if a content control is displaying its placeholder text

According to Microsoft's documentation, the .ShowingPlaceholderText property

Returns a Boolean that indicates whether the placeholder text for the content control is displayed. Read-only.

My experience is that the return value for .ShowingPlaceholderText is wrong about half the time. Or, it's right about half the time.

Sometimes the document will display the placeholder text, but .ShowingPlaceholderText will deny this. Sometimes .ShowingPlaceholderText will allege that the document is showing the placeholder text, but it is not.

You just can't rely on it. So to determine whether the document is showing the placeholder text, compare the .PlaceholderText.Value with the ContentControl.Range.Text.

However you can't compare the text of an image with the placeholder's image. So it does not seem possible to determine in the object model whether an image content control is showing the placeholder.

Some content controls can have a PlaceholderText object, but no placeholder text

Image controls, Group controls and (in Word 2010) checkbox controls have a PlaceholderText object, but never have a .Value, perhaps for obvious reasons. Be careful of this if you're cycling through all the content controls in the document. The .Value property applied to an image, group or checkbox content control returns an error (91: 'Object variable or With block variable not set') no matter what the content control is showing in the document.

Word does not properly report the style used by placeholder text either in the object model or in the user interface

By default, Word displays placeholder text using the built-in Placehoder Text style. You can modify this style as you can any built-in paragraph style. That is, you can modify the style to make it green or pink or underlined or whatever.

You can apply any other paragraph style to the placeholder text (specifically, it must be a so-called linked paragraph style), or you can apply direct formatting.

What I can't do, is find any way to determine what style has been applied to placeholder text.

And therefore, we can't write a routine to 'clean up' content controls in a document by re-applying placeholder text to content controls.