Customizing UPK outputs (Part 3 - Document Outputs)
By Maria Cozzolino on Jul 02, 2010
In version 3.5 of UPK, we expanded the capability for customization of the document outputs to support a broader range of functionality. My goal of this post is to demystify the underlying template, and provide a basic understanding of how it works. We can go into more details about how to customize in another post if clients are interested.
Each of the document outputs uses a Word 2007 template (printtemplate.docm) and some clever automation to build the document outputs. Bookmarks are inserted into the template, and during publishing, the bookmarks are replaced with the appropriate text from your concepts and topics. Since this is a Word template, any of the standard word functionality like inserting page breaks, is available. In addition, the UPK-specific functions can be inserted from our toolbar. When you open the template, it may look overwhelming at first. There's a lot of data in there! This is good in that you have a lot of flexibility in what can be modified, so it's worth getting a better understanding of the capabilities.
Before you begin:
Make a backup copy of each of the word templates you will be customizing. This is very important. Because these templates work with Word automation, a precise format is required to support document generation. If you miss something as small as an ending bracket, the document will not generate. Also, consider creating your own brand, since any product upgrades will change the document styles back to our default.
Tip: I have had luck making changes in small increments, and then testing to ensure the document still publishes. I keep around several "last known good" copies of templates, so I don't have to restart my customizations from ground zero each time.
When we designed a layout for the document outputs, we recognized that there are certain standard fonts and type sizes that work in a printed layout. Our document styles use standard fonts (Times New Roman and Arial) and have headings that are consistent with a book layout. However, we realize that you may prefer to use a different print format, or you may want your output to match how you formatted your material in the Developer. Thus, there are two types of formatting to choose from:
1. Format from the Word template (default). This means the text comes in from the Developer, but any fonts, color and alignment are taken from the Word template.
2. Format from Developer settings. This means the text uses the same fonts and sizes entered in the Developer.
Understanding the bookmarks:
There are several types of bookmarks that appear in the templates.
- Single fields - items like Topic Name represent a single data value. The bookmark is replaced with the appropriate topic name.
- Multi-field - items like the Required Fields can have multiple values with comments. This bookmark ensures that each required field is kept with its comments and that all the required fields are inserted into the table.
- Repeating bookmarks - How do you ensure you get all the frames in a topic when you don't know how many frames there are until publishing starts? We use repeating elements, which allows the system to add rows into the Word table until all the frames are included. These bookmarks have a begin and an end tag. Both tags must be present. In the templates, the bookmarks are pretty descriptive of their functionality, for example: ForEachFrame_Begin.
Other parts of the template:
In addition to bookmarks, there are several other parts in the templates.
- Image placeholders - These placeholders let you control the size and appearance of the screenshots, action areas, and graphics in concepts.
- Static Text - This is regular word text (for example the heading of JobAid, or End of Procedure.). If you change it, the new text will appear in the output. You can also add your own text to the template.
- Table of Action Steps - This table represents the location and format of the table that will include all the frame data. The table itself can be reformatted using Word's functionality.
- Defined bookmarks - These are used by the Developer to ensure the appropriate image placeholders get inserted. If these are deleted, the template will not work properly. Please do not delete these bookmarks.
The Developer publishing template toolbar appears in the Add-ins menu on Word 2007. Hint: You may need to enable macros for the toolbar to appear. It contains all the elements necessary to insert the standard UPK values into your template. For example, you could insert concepts into your JobAids. If you prefer to view the toolbar in a different language, you can change the language (but the bookmarks will still be inserted in English).
This is where the fun begins. :) You could create an entirely new document output style by mixing and matching the standard UPK data and metadata! When you combine this toolbar with Word's standard functionality, the possibilities are endless.
Want more details? Our documentation team has done a great job of explaining all the toolbar options and behaviors in the Content Development Guide (see the chapter on Customize Document Outputs)
I hope you have enjoyed this light reading to start a holiday weekend (for our US-based clients)! Feel free to add your feedback in the comments section. I'd be interested in hearing what you customize, and also if there are any challenges you are encountering. Have a happy and safe weekend!
Maria Cozzolino, Manager of Requirements and UI Design for UPK