Resting Anchor

The Anchorage

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

CC/V/BM & DP Tools Add-In (Ver. 4.0)
(A Microsoft Word Help & Tip page by Gregory K. Maxey)

DISCLAIMER/TERMS OF USE

The information, illustrations and code contained in my "Microsoft Word Tips" are provided free and without risk or obligation.

Click to acces PayPal Verification Service Click to acces PayPal Verification Service

However, the work is mine. If you use it for commercial purposes or benefit from my efforts through income earned or time saved then a donation, however small, will help to ensure the continued availability of this resource.

If you would like to donate, please use the appropriate donate button to access PayPal. Thank you!


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 versions 3.0 and 4.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)

Content Controls

Site Note IconNote:  "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.

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

Version 4.0

Long in coming due to the lack of an Office 64 bit Word application and incompatibility in that system with the standard TreeView control used in version 3.

Version 4.0 is compatible with both Office 32 bit and 64 bit applications.  This version would not have been possible without the use of a custom VBA TreeView control developed to replace the standard TreeView control by Peter Thornton and Jan Karel Pieterse of JKP Application Development Services http://www.jkp-ads.com/index.asp.  Jan and Peter have produced a pair of crown jewels in the form of class modules that were used to provide the TreeView now employed in the add-in.  For more on their remarkable work, see: http://www.jkp-ads.com/Articles/treeview.asp

Add-in Description

Site Note IconNotes:
    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.

mm_addin_1

mm_addin_2
Add-in ribbon user interface

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

  1. The user interface propagates on the Ribbon "Add-Ins" tab.
  1. Creates a new custom group "M & M Add-In."
  2. Adds a new large button control "CC/V/B & DP Tools." This initiates the primary add-in userform interface.
  3. Adds a new menu control "Options." This control displays options for the user to select when using the add-in.
  4. Adds a new normal button control "Info/Help." This control links this page.
  5. 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.
  6. A new toggle button control shows or hides a alternate "CC/V/B & DP Tools" control to the ribbon insert tab.
  7. A new toggle button control turns add-in feedback with sound on or off.
mm_addin_3
Add-in "Insert" tab control
  1. Optional display. Activates the primary add-in userform interface in the document.

Site Note IconNotes:
    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:

mm_addin_4

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.
  1. Allows users to select one of five featured document collections.  Collections have been arranged alphabetically in version 3.0.
  2. 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 .
  3. 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.
  4. Relocates the document selection to the bookmark or content control selected in the collection list.
  5. Inserts the appropriate cross reference field (REF, DocVariable or DocProperty) to the bookmark, variable, or document property at the selection in the document.
  6. 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.
  7. 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.
  8. Changes the value of the item selected in the collection list to a user entered new value in the "Content/Value" field.

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

  1. 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.
  2. Credits and link to this page.
  3. Multi-purpose "User Notification and Action Panel."
  1. A convenient control to access and make support donation via PayPal.
  2. Closes the add-in.

Site Note IconNote - 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:

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

Site Note IconNote: 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.

  1. 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.
  2. Notification of the action initiated and additional options.
  3. When selected this option will unlink all document fields cross referenced to the selected item and convert the field result to fixed text.
  4. When selected this option will delete all document fields (and field results) cross referenced to the selected item.
  5. When checked the selected bookmark is preserved in the document.
  6. When checked the content of the selected bookmark is deleted.

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

  1. Cancels the initiated "Delete" action.
  2. Executes an initiated "Delete" action.

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

mm_addin_6

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.

Site Note IconNote: 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.

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

Site Note IconNote: 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.

  1. Create the new custom document property as defined.
  2. Use text selected in the document to define the new custom document property value.
  3. Bookmark the selection in the document. This feature employs Word's built-in bookmark dialog.
  4. 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.
  5. "User Notification Panel" common to this page and the "Create/Manage Mapped Content Controls" tab page.

"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.

Site Note IconNote:  In June 2014, I combined most of the features described below into a new template add-in: Content Control Tools.  The new add-in includes all of the mapping features plus many new and useful tools.

mm_addin_7
Updated to illustrate version 3.1

mm_addin_7A

Updated to illustrate version 4.0

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.

Site Note IconNote: 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.

  1. 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.
  2. 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.
  3. Inserts a new sibling node in the customXMLPart immediately before the node selected in the tree-view control.
  4. 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.
  5. Appends a new child node after the last child node of the parent node selected in the tree-view control.
  6. Creates a new Word document which displays the text values of the customXMLPart data nodes.
  7. Resets (clears) the value stored in the node selected in the tree-view control.
  8. 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.
  9. 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.
  10. 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.
  11. 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.
  12. 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.

mm_addin_8

mm_addin_9

mm_addin_10

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.


mm_addin_12

Site Note IconNote: 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.

mm_addin_11A

Site Note IconNote: 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! 

mm_addin_13a

Site Note IconNote: 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.

mm_addin_15
mm_addin_16
mm_addin_17

mm_addin_18

Site Note IconNote: 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.

mm_addin_19

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.

Site Note IconNote: 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.

mm_addin_20

mm_addin_21

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

mm_addin_22

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

Site Note IconNote - 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.

Site Note IconNote: 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.

  1. You can opt to delete the control (leave the content), the content (restore placeholder text) or both.
  2. Executes the delete content controls action as defined.
  1. The "Selected in Document" frame lets you select a mapped content control to delete from within the document.
  2. 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.

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

  1. Executes the delete content controls action as defined.
  2. The "All" frame lets you delete all mapped content controls from your document.
  3. You can opt to delete all mapped controls, the content of all mapped controls or both.
  4. Executes the delete all content controls action as defined.

Site Note IconNote:  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:

mm_addin_22_A

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:

mm_addin_23

Site Note IconNote: 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.

mm_addin_24

Site Note IconNote: 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.

Version 3.3 of 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.

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

Version 4.0, replaces the standard TreeView controls with a VBA version described above.  Reference to the Windows Common Controls ActiveX Control DLL is no longer required.

Conclusion

That's it. I hope you find the add-in helpful and as much fun to use as it was to create!! Until I get more feedback on version 4.0, I'm making both versions 3.3 and 4.0 available for download. Download version 3.3 and the associated files here: CC/V/BM & DP Tools.  Download version 4.0 here:  CC/V/BM & Tools V4.

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.

Share Stumbleupon

PAYMENTS/DONATIONS

Click to acces PayPal Verification Service Click to acces PayPal Verification Service

Do you want to make a payment for consulting work or donate to help support this site?

PayPal is a safe, easy way to pay online.

Use the appropriate currency "Donate" button to make a payment or donation.


Search my site or the web using Google Search Engine

Google Search Logo

Or

JustAnswerAsk a Word Expert OnlineSubmit