Customizing UPK outputs (Part 3 - Document Outputs)

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.

Overview:
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.

Template Formatting:
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.

.

UPK Toolbar:
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


Comments:

I have msoffice 2010 and after i publish it says it is looking for office 2007. Is there a way /patch to get this to work with 2010. I am sorry, I also have UPK 3.6

Posted by sunil on July 30, 2010 at 11:14 AM PDT #

Hi Sunil - We do not support Office 2010 at this time, but are looking into supporting it for a future UPK release. In the interim, I recommend you publish your documents using Office 2003 or Office 2007. Regards, Maria

Posted by Maria Cozzolino on August 01, 2010 at 09:55 PM PDT #

How does one change the template for screen prints in the printed Word version of the training guides? The default prints the screen shots too small when printed and we spend a lot of time manually changing the size on each page. Thanks.

Posted by Deborah Jindra on February 14, 2011 at 11:34 PM PST #

Hi Deborah - When you open the printtemplate.docm file for the training guide, you will notice several images. Scroll down to the image that appears after the "Procedure" heading - this is the image for the topic screen shots. You can use Word's image sizing functionality to make the screen prints a better size. Good luck! Regards, --Maria

Posted by Maria Cozzolino on February 17, 2011 at 09:05 PM PST #

I see that Office 2010 is not supported. Is this why I get error messages when I publish various print materials and are unable to view them? These are my error messages: 1673847682 and 677421808.

Posted by Kelly Miller on May 09, 2011 at 06:04 AM PDT #

Hi Kelly - Office 2010 is supported in UPK 3.6.1 ESP 3, which is available on E-Delivery. If that does not help, feel free to submit a support ticket, so we can look at your issue in more detail.

Posted by Maria Cozzolino on May 09, 2011 at 06:33 AM PDT #

Hi, I'm updating the Header on the job Aid. Ihave changed the image but now I want to inluce toe TopicName in the header. When I try and pull the Topic Name into header All I see is topicName<>?

Any suggestions

Posted by Ashanti on December 12, 2011 at 02:18 AM PST #

is there any way to customize the header of a template? we'd like to add the outline name to the header of a job aid.

Thanks

Posted by Sabrina on September 12, 2012 at 01:09 PM PDT #

One of the most common items to customize is the header and footer of any of the document types. You can change the logo, insert any Microsoft Word fields, or add static text. Note that you cannot insert bookmarks from the toolbar in the header or footer, only standard Word fields such as page number or document name. If you do put bookmarks in the header or footer, they will not be processed and will appear as static text in the published document.

Posted by Peter Maravelias on September 14, 2012 at 03:16 PM PDT #

Post a Comment:
  • HTML Syntax: NOT allowed
About

The authors of this blog are members of the UPK product development, management, and marketing teams. On this blog, you'll find UPK news, tips/tricks, upcoming events, and general information on UPK - the easy-to-use, comprehensive content development, deployment, and maintenance platform for increasing project, program, and user productivity.

Search

Archives
« February 2015
SunMonTueWedThuFriSat
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
       
       
Today