The Anchorage

Personal website of Gregory K. Maxey, Commander USN (Retired)

• Quarterdeck
• What's New
• Microsoft Word Tips
• Ask Word Expert
• Chain Locker
• Lucky Bag
• Contact
• Search

This Microsoft Word Tips & Microsoft Word Help page introduces and provides instructions for using the "Content Control/Variable/Bookmark & Document Property Tools (or CC/V/BM & DP)" Word template add-in.

Background

This add-in was originally developed with longtime friend and Word MVP Graham Mayor.  It is the culmination of well over a hundred hours of development and testing.  Unfortunately due to personal business and unplanned travel, Graham was unavailable to assist with the design and testing of  the features added in version 3.0.  His presence was sorely missed!!

However, as nature abhors a vacuum, friend and Word MVP Jay Freedman stepped in and on several occasions, he tried to break it and succeeded.  Jay's thorough, critical review and testing have been instrumental in the publication of version 3.0.

The impetus for this project is the lack of visibility and everyday user access to two very useful and powerful Word features; the "document variable" and the "mapped" content control.

Document Variables (or Variables)

• Variables can be used to store and exchange all manner of information for use in a document.
• While users who are familiar with variables can easily insert references to an existing document variable using a Word "DocVariable" field, Word does not provide a convenient method for managing the variables collection or the data they store.
• Until now, for many users, variables remained "Hidden Gems in Word."  Using the add-in you can easily manage and incorporate document variables in your document design and more fully utilize the power of Word.

Content Controls

• Content controls were introduced in Word 2007.
• Since their introduction, their real usefulness as windows and conduits to data in an XML file (customXMLPart imbedded in the document) is limited to advanced Word users familiar with both Visual Basic programming and XML data structure.
• Now using the add-in, even beginner users can quickly and effortlessly create and use all qualified types of mapped content controls.

Note:  "Qualified" types as mentioned in this tips page, refers to the types of content controls available in the applicable Word application version in use.

We have retained the features for working with bookmarks and document properties introduced in our, now obsolete, "Document Variables, Bookmarks & Properties" add-in. This results in a single compact and versatile add-in for working with all five principal data storage collections in your documents.

Version 3.0/3.3

Version 3.0 prompted by user feedback and my own peek at the soon to be released Word 2013, provides a significant upgrade and redesign of the add-in content control features.  A brief summary of the changes included in version 3.0 are provided below.

• Set-up options are now provided as ribbon toggle button controls and option buttons displayed on the add-in user interface.
• The new Content Control XML Mapping Tools simplifies and expands the user's ability to create and map content controls and manage the document customXMLParts collection.  With mapping tools, users can now map content controls to data nodes in any available document customXMLPart, add or delete customXMLParts, and insert, append, or delete individual XML data nodes.  For Word 2013 user's I've included tools for inserting and mapping rich text and the new repeating section controls. 
• Users can now delete cross reference fields to items in the variables, bookmark and custom properties collections while preserving the item and its value.
• The content control properties "Content control cannot be deleted, and Contents cannot be edited" are now overridden, if applied, when the user selects to delete or change content of a selected control using the add-in.
• During development and testing of version 3.0, several bugs and previously undetected shortcomings in versions 2.2 and earlier were corrected.

Version 3.3 provides bug fixes to the base version uncovered during additional testing and a few minor enhancements.

Add-in Description

Notes:
    1. Testing and development with this add-in has been limited to the U.S. English version of Microsoft Word 2007/2010/2013 (pre-release) in a Windows7 operating environment and the U.K. English version of Microsoft Word 2007/2010 in a WindowsXP operating environment. Lack of access, time and resources has prevented further testing. Unfortunately feedback confirms that the variances in other language versions of the Microsoft products involved can prevent the add-in from functioning properly in those versions.

    2. Items annotated using rose colored flags in the illustrations below indicate changes and additions introduced in version 3.0.

    3. With any large development work changes are inevitable. While the illustrations were current with the release of version 3.0, there may be future changes that are not fully or accurately illustrated.

When the add-in loads it alters the Ribbon as follows:

1. The user interface propagates on the Ribbon "Add-Ins" tab.

2. Creates a new custom group "M & M Add-In."
3. Adds a new large button control "CC/V/B & DP Tools." This initiates the primary add-in userform interface.
4. Adds a new menu control "Options." This control displays options for the user to select when using the add-in.
5. Adds a new normal button control "Info/Help." This control links this page.
6. Adds as new normal button control "Disclaimer." This control displays a disclaimer statement releasing the developers from any liability or obligation associated with use of the add-in.
7. A new toggle button control shows or hides a alternate "CC/V/B & DP Tools" control to the ribbon insert tab.
8. A new toggle button control turns add-in feedback with sound on or off.

1. Optional display. Activates the primary add-in userform interface in the document.

Notes:
    1. This feature may affect the normally displayed size of the built-in "Hyperlink, Bookmark and Cross-Reference" controls. These controls will display size "normal" when displayed with the add-in button control regardless of how they might display (i.e., large or normal) on their own.

    2. This feature was the single biggest point of contention between Graham and me during development. He wanted the controls on the Insert tab and I felt they belonged on the Add-Ins tab. The result is our form of compromise.

Add-in common elements and "Lists" tab page:

The add-in consists of a three part multi-page control and common elements. The functions of the common elements and the "Lists" tab page is described below:

1. Provides the name and version number of the add-in.
2. Three tabs across the top of the add-in provide the user with access to the three main functions of the add-in.

• Listing, navigating, referencing, editing or deleting elements of the five principal document data storage collections.
• Defining and creating new variables, custom document properties and bookmarks.
• Defining, creating and deleting mapped content controls.

3. Allows users to select one of five featured document collections.  Collections have been arranged alphabetically in version 3.0.
4. Displays a "collection list" that lists each member of the selected collection in the document. Bookmarks and Content Controls can be listed by location or alphabetically using option buttons (not shown) that appear below the list when the bookmarks or content control collections are listed. The Variables, Custom Document Properties and Built-in Document Properties (shown) collections are listed alphabetically only .
5. Manually refreshes the collection list. Use this feature if you perform other work in the document with the add-in active and you make changes in the document that would affect information displayed.
6. Relocates the document selection to the bookmark or content control selected in the collection list.
7. Inserts the appropriate cross reference field (REF, DocVariable or DocProperty) to the bookmark, variable, or document property at the selection in the document.
8. Enabled only when a mapped content control is selected in the list.  Inserts a new content control at the selection in the document. The new content control inherits properties of the content control selected in the collection list. Both controls are mapped to the same XML data node.
9. Initiates a delete action on the item selected in the collection list. Reconfigures the User Notification and Action Panel to provide additional user options and controls.
10. Changes the value of the item selected in the collection list to a user entered new value in the "Content/Value" field.

Note: Values in certain Built-in Document Properties are calculated values and cannot be changed.

11. Displays the value of the item selected in the collection list. When enabled, the user can modify the data and use the "Change Value" control to save and store the new value.
12. Credits and link to this page.
13. Multi-purpose "User Notification and Action Panel."

• Provides the user with informational prompts and notification of events.
• Used in conjunction with the "Delete" and "Change Value" controls to provide additional user options and action events.

14. A convenient control to access and make support donation via PayPal.
15. Closes the add-in.

Note - One or more command button or other control will be disabled depending on which collection option is selected.

The "User Notification and Action Panel" depicted below is is shown configured to delete the selected bookmark:

1. Options to sort collection items by name or location in the document.

Note: The location sort is based on the item's location in the various document story ranges starting with the main text range, then footnote range, followed by end note range etc., and not how the item might physically appear in the document.

2. Multi-purpose "User Notification and Action Panel" configured to delete the bookmark "Defendant," and any associated cross reference fields in the document. The configuration is initiated by selecting an item in the collection list and clicking the "Delete" command.
3. Notification of the action initiated and additional options.
4. When selected this option will unlink all document fields cross referenced to the selected item and convert the field result to fixed text.
5. When selected this option will delete all document fields (and field results) cross referenced to the selected item.
6. When checked the selected bookmark is preserved in the document.
7. When checked the content of the selected bookmark is deleted.

Note:  When "Delete content" is checked the "Preserve bookmark" checkbox is automatically unchecked and disabled.

8. Cancels the initiated "Delete" action.
9. Executes an initiated "Delete" action.

"Create Variables, Custom Properties or Bookmarks" tab page:

Using the "Create Variables, Custom Properties or Bookmarks" tab you can define and create new document variables, custom document properties or bookmarks.

1. Enter a unique name for the new variable you want to create.
2. Enter the value you want to assign to the new variable.
3. Create the new variable as defined.
4. Use text selected in the document to define the new variable value.
5. Select one of four data types for the new custom document property you want to create.
6. Enter the unique name for the new custom document property you want to create.

Note: Word provides 35 pre-defined custom document properties (without values). This field is a combo box which allows you to choose from one of the pre-defined properties and assign a value or define your own new property name.

7. Enter the value you want to assign to the new custom document property.

Note: Values for custom document properties are type dependent. For example, if you opt to create a "Date" type custom document property then the value you define must be in a valid recognizable date format.

8. Create the new custom document property as defined.
9. Use text selected in the document to define the new custom document property value.
10. Bookmark the selection in the document. This feature employs Word's built-in bookmark dialog.
11. After action add-in configuration. You can chose to remain on this page after each variable, custom document property or bookmark is created, or immediately return to the appropriate collection on the "Lists" page.
12. "User Notification Panel" common to this page and the "Create/Manage Mapped Content Controls" tab page.

• Displays informational notes.
• Displays notification of actions completed and invalid user actions.

"Create/Manage Mapped Content Controls" tab common elements and "Content Control XML Mapping Tools" tab page:

This portion of the add-in has been extensively modified.  Users can now create and map content controls directly to a targeted customXMLNode.  It also provides mapping capability for rich text controls (Word 2013 only) and the new repeating section control introduced with Word 2013.

The "Create/Manage Mapped Content Controls" tab page consists of a two part multi-page and a common "User Notification Panel."

1. The "Content Control XML Mapping Tools" tab page is used to define and map document content controls and provides functions to assist users work with the document customXMLParts collection.
2. Displays the second page of the two part multi-page "Delete Mapped Content Controls/Mapping Tools."
3. Lists the three built-in customXMLParts, which are a permanent part of all Open Office XML Format File documents (Word versions 2007 and higher), and any customXMLParts that have been added to the document.  The selected customXMLPart is used to define the tree-view (8) control display.
4. Opens an instance of Notepad and displays the text of the customXMLPart XML script.  You can save the file in Notepad using a new file name.

Note: The temporary XMLMapping.txt used for viewing is automatically deleted when the add-in is unloaded and closed. If you want to retain the file you can save it using a different file name while Notepad is open.

5. Adds a predefined basic customXMLPart to the document.  Beginning users can immediately take advantage of mapped content controls without any knowledge or experience creating an XML script file.
6. This is a dual function command button control that lets you delete the selected customXMLPart or delete an individually selected node in the tree-view control.
7. Inserts a new sibling node in the customXMLPart immediately before the node selected in the tree-view control.
8. Deletes all customXMLParts from the document excluding the built-in customXMLParts.  The built-in customXMLParts are required by the file structure and cannot be deleted.
9. Appends a new child node after the last child node of the parent node selected in the tree-view control.
10. Creates a new Word document which displays the text values of the customXMLPart data nodes.
11. Resets (clears) the value stored in the node selected in the tree-view control.
12. When working with templates you can create a building block from your mapped control. These building blocks are stored in the "Mapped Content Controls" category of the template's "CustomAutoText" gallery.
13. Displays the XML structure (parent and all child nodes) of the customXMLPart selected.  Users can select and map content controls to individual nodes or view node content.  Defines the action when the user clicks an individual node in the tree-view control.
14. Configures (13), the treeview control, for mapping content controls.  When this option is selected, the node type is defined in the User Notification Panel when a node is selected.  Selecting a node using the left mouse button displays a popup command bar used to map controls.
15. Configures (13), the treeview control, for displaying selected node values.  When this option is selected, the node value is displayed in the User Notification Panel.
16. Provides user information, displays selected node values, and additional functions described below.

Users can create their own XML script files and add customXMLParts to the document using the "Add new part ..." feature of the Custom XML Part list. This opens a dialog allowing the user to select the XML script file to load.

Mapping Controls

After selecting a customXMLPart, you can create and map content controls to the nodes.  Using the following illustrations, I will show you how to create and map content controls to a XML node.

• The "Map To Nodes" option configures the tree-view control for mapping when an individual node is selected. 
• Here I am going to create and insert a plain text content control mapped to the "Name" data node.  Right clicking the node name displays the pop-up menu that you use to insert mapped controls.
• This launches the content control properties dialog, where I enter a name and set other properties as desired.

Note: It is important that you define a unique title property to each content control that you create and map using this add-in. You should also assign a unique title property to any unmapped content control that you create using the controls in the Word Developer tab Controls group. Using duplicate titles, deleting titles or changing title property definitions of mapped content controls can affect the accuracy of the content control "Delete" processes used in this add-in.

• After clicking "OK," the mapped content control is inserted into the document. 
• The placeholder text is defined when the content control is created using the type and title of the control inserted.

• Here I am going to create and insert a Word 2013 repeating section content control mapped to the "MultiNode" data node.
• Repeating section content controls can only be mapped to parent/child nodes of the root node that contain one or more child nodes of their own.  For more on repeating section content controls, see my:  Content Control Enhancements — Word 2013 and Add, Map and Employ Repeating Section Content Control in Word 2013.

Note: Repeating section content controls are new and subject to change prior to official release of Word 2013.  I'm still learning about them myself and I'm not entirely convinced that Microsoft has gotten them right! 

• You can also map existing content controls in your document. Here I have selected an existing date picker control to map to the "DOB" data node.

Note: In Word 2007 and 2010, to select a content control in the document for mapping you must select the physical control (not just the control range). To select the physical control you select (click on) the control's title tab.

Viewing Node Values

By changing the tree-view configuration, you can select a node and the node's value is displayed either directly in the add-in (< 500 characters) or externally using Notepad.

 

Appending, Insert, Deleting, and Resetting Nodes

Using the the "Delete," Append," "Insert" or "Reset/Clear" node commands, you can modify the customXMLPart data structure and content.   In the following illustrations, I'll demonstrate inserting a node.

• Configure tree-view control for viewing node values.
• Select the node that will become next sibling node of the new node created.
• Click the "Insert XML Node" command.
• The User Notification Panel is immediately reconfigured.

• Enter the new node name.
• Enter node content (optional).
• Click the "Insert" command button.
• The new node is inserted immediately before its selected sibling node.

Note: There are a few rules associated with naming XML data nodes.
             1) Names can contain letters, numbers, and other characters.
             2) Names cannot start with a number or punctuation character.
             3) Names cannot start with the letters xml (or XML, or Xml, etc.)
             4) Names cannot contain spaces.  The add-in will automatically convert any spaces you enter into an underscore "_" character.

After inserting and mapping a picture content control to the new "Picture" node shown above, you can, if desired, view the node content.  Content that exceeds 500 characters is displayed using Notepad.

Note: The text shown below represents only a small part of the total text that defines a digital image.  Viewing content of a single node containing a picture definition or an entire XML Part containing pictures can take a long time for Notepad to process.

"Delete Mapped Content Controls/Mapping Tools" page tab:

Using the "Delete Mapped Content Controls/Mapping Tools" tab you can use several methods to remove unwanted mapped controls from your document.

Note - All delete actions initiated from this page tab override any "Content control cannot be edited", "Content control cannot be deleted" and unsecure (no password) document protection for forms.

1. The "Select from List" frame lets you select mapped content controls to delete from a convenient list.
2. Lists the title and number of like mapped content controls in your document.

Note: This is where unique title discipline mentioned earlier becomes important. When you insert a cross reference content control using this add-in or if you copy and paste a mapped content control in your document to another location in your document, you have created for all intents and purposes a clone. It is only logical that the clone will retain the title and XML mapping path. Should you later change title of a like mapped content control it could affect the accuracy of this list and the accuracy of the subsequent delete actions.

3. You can opt to delete the control (leave the content), the content (restore placeholder text) or both.
4. Executes the delete content controls action as defined.

5. The "Selected in Document" frame lets you select a mapped content control to delete from within the document.
6. You can opt to delete the selected control, the content of the selected control, both the selected control and content, like controls or like controls and content.

Note: By the nature of mapped controls if you delete the content in one the content is deleted from all like controls.

7. Executes the delete content controls action as defined.
8. The "All" frame lets you delete all mapped content controls from your document.
9. You can opt to delete all mapped controls, the content of all mapped controls or both.
10. Executes the delete all content controls action as defined.

Note:  This action affects all document mapped contents and is irrevocable (except for immediately closing a document without saving changes). Therefore we have added a confirmation step. When the command button is initially selected a confirmation notification is displayed and the command button caption is displayed in red lettering. Clicking the command button displaying a red letter caption executes the event without additional notification or warning.

Alerts & Notifications

The "User Notification Panels" provide various alerts and notifications. The add-in alerts the user to restricted or invalid events using red alert text in the appropriate "User Notification Panel" and an audible default system "Beep."  A typical alert notification is shown below:

Several processes in the add-in require documents protected for forms to be temporarily unprotected to complete. When a password is required the user is presented with the following form:

Note: These processes are performed automatically without any user interaction in unsecure (no password) protected forms.

Content Control Title Parsing

The add-in will parse the document for untitled and duplicate titled (non-mapped) content controls each time it is initiated. As content controls are listed by title they must have either a title property or a temporary label in lieu of a title property. Careful and thoughtful application of content control titles will eliminate this notification.

Note: It is intuitive and expected that like mapped content controls will have the same title.

Installation and Setup

This Word template add-in can be loaded manually from any template storage directory or automatically from your Word startup folder. For more on template add-ins and how to load them, see the heading: Organizing Your Macros/Template Add-ins at: Installing Macros.

The add-in employs a Microsoft TreeView Control 6.0 (SP6) to list the CustomXMLNodes available for content control mapping.  This control requires a library reference to MSCOMCTL.OCX (Windows Common Controls ActiveX Control DLL) which may be missing or require registering on your system, see: Add-In Technical Notes.  The file MSCOMCTL.OCX is included in the add-in installation package.  Where you locate/place this file will depend on your operating system.

• C:\WINDOWS\SYSTEM32 if you are using a 32-bit version of Windows
• C:\Windows\SysWOW64 if you are using a 64-bit version of Windows

Instructions for installing and registering the file are provided in the "Read Me" text file that is part of the installation package.

Conclusion

That's it. I hope you find the add-in helpful and as much fun to use as it was to create!! Download the add-in and associated files here: CC/V/BM & DP Tools.

I can't stress enough the encouragement and cooperation by Graham Mayor or the technical contributions he made. Please visit Graham's web page for his slant on the add-in, its features and tips for installation at: Graham's Add-In Description.

This page was last updated on December 02, 2012

Website Privacy Statement

Back to top    Back to Word Tips