Publishing Word Fields, Instructions, and Switches
Word fields in Word documents are used as placeholders for data that might change in a document (called the field result). Arbortext Styler contexts can be mapped to Word field codes. For example, the contents of a document's author element could be mapped to a Word field { AUTHOR [ "NewName" ] }. Content that is all or partially generated can be mapped to an appropriate Word field.
Fields are typically composed of instructions and switches that combine to produce a dynamically-generated field result. Instructions are single string values, written in double quotes if enclosing ASCII spaces. Simple switches are boolean arguments that are either on or off based on their presence. Value switches are arguments with a string value.
Arbortext Styler automatically creates fields for certain element types when publishing to RTF, and these are listed below. Note that the elements nominated to represent these types in the document must be configured in the document type and given the relevant style in the Arbortext Styler stylesheet for these mappings to function correctly - for example an xref element must be configured and styled as Cross Reference:
Fields Created for Element Types During an RTF Export Process
|
Element / attribute
|
Word field created
|
|
Element with Arbortext Styler-generated ID
|
bookmark
|
|
Element with user-defined ID attribute
|
bookmark
|
|
link
|
HYPERLINK
|
|
cross reference
|
REF
|
|
graphic (linked)
|
INCLUDEPICTURE
|
|
table of contents
|
TOC
|
|
division title
|
TC
|
|
index term
|
XE
|
Mapping of Word fields does not depend on the use of a Word template during the publishing process.
For further details on Word fields, and each field's instructions and switches, refer to the online help accompanying Microsoft Word. The location of this information in the help in different releases of Word varies, but finding Field Types and Switches in the help Table of Contents should display a reference to fields.
Publishing Fields
When specifying fields, consider the different structure types involved with Word fields. Some fields are simple text fields much like generated text in XML, where the field wraps some dynamically created text. In these fields, such as AUTHOR, the source for the generated text might be a Word document property. If you publish text as the content of the field (such as Jane Doe), the text will display in Word. But when fields are updated, for example via a CTRL+A+F9 refresh, the text might be dynamically changed to use a different name depending on the author currently editing the Word document.
Likewise, a field such as EDITTIME, which displays the amount of time spent editing the document, can be published with a value such as 20.0 which represents 20 minutes of editing. However, the value published by Arbortext Import/Export will not be valid for very long, because the editing time is constantly changing. Bear in mind, Word does not automatically update fields in the same way as Arbortext Editor when automatically updating generated text. You must manually update fields in Word via a CTRL+A+F9 refresh, or via a macro function saved as part of your Word editing environment.
|
|
Certain Word fields depend upon real-time information created by Word when a document is saved. For example, EDITTIME, LASTSAVEDBY, TIME, NUMCHARS, NUMWORDS, and other fields depend on Word-based information and cannot be supplied by Arbortext Import/Export in any meaningful way. If dynamic fields such as these are published, be aware their result strings may changes every time the document is saved by Word.
|
Mapping a Context to a Field
1. In the Elements list, highlight the context you wish to map to a field.
2. In the RTF category, choose Edit in the RTF field area. The Field dialog box is displayed.
3. From the Field name list, choose the field to be published for the context. A description of the field is displayed in the Field description field and the Field instructions and switches table is filled with the instructions and switches pertinent to the selected field.
Specify the characteristics of one or more Word fields to be exported with the selected context
4. Enable boolean switches by clicking in the Use column for the switch.
5. Enable value switches by highlighting the switch:
a. Press F2 or double-click on the highlighted switch to edit simple text strings.
b. Choose the
Edit Value button to launch the Generated Text Editor, which allows you to enter sophisticated expressions for computing, extracting, or locating the value of the switch using the array of tools available. Refer to
Generated Text Overview for details on using the Generated Text Editor.
6. After entering a value, ensure that the box in the Use column for that switch is checked.
7. Required instructions or switches are denoted using gray check boxes which cannot be unchecked. You must enter a value for instructions or value switches where marked as required, otherwise the field may display an error in Word or exhibit other unexpected behavior.
Contexts can be mapped to output styles, fields, or both. For example, an author context in a document can be mapped to a Word paragraph style called Author. That same context can also be mapped to an author field. The resulting document would contain a formatted paragraph with the style name Author containing the author field result.
Preventing PCDATA From Being Published as a Field Result
If a #PCDATA element is published as a field, the default behavior in Arbortext Import/Export is to publish the #PCDATA as the field result string, even though at some later date the result string may change when fields are updated.
Use this procedure to suppress the #PCDATA and prevent its output as the field result:
1. In Arbortext Styler select the context for which you wish to suppress the #PCDATA.
2. In the Text category for the Elements list, set the Hidden option to Yes.
3. Create a User Formatting Element (UFE), with a name of your choice, to serve as a placeholder in generated text. The UFE will be responsible for publishing the desired field.
4. In the Generated text category, insert the newly-created UFE. Use RTF Stylesheet Properties.
5. Select the UFE's default context and specify the desired field.
6. The #PCDATA of the main context will be suppressed because the Hidden property is enabled, but the field will be published because generated text is always published, regardless of the setting of the Hidden property.
Limitations when Publishing Fields
The following limitations apply in Arbortext Import/Export when publishing fields:
• The following fields are not supported:
◦ ADDRESSBLOCK
◦ ASK
◦ AUTOTEXT
◦ AUTOTEXTLIST
◦ BIDIOUTLINE
◦ DATABASE
◦ DDE
◦ EMBED
◦ GREETINGLINE
◦ MERGEFIELD
◦ MERGEREC
◦ MERGESEQ
◦ NEXT
◦ NEXTIF
◦ PRINT
◦ SKIPIF
• Nested fields are not supported.
• When referencing XML id attributes in Word fields, the XML ID values may not contain characters which are illegal in Word bookmark names. Arbortext Import/Export automatically filters illegal characters before publishing as Word bookmark names. The only characters allowed as the first character of a Word bookmark names are alpha characters. The only characters allowed as non-first characters in Word bookmark names are alpha characters, numerals (0 - 9) and the underscore (_) character. Illegal characters are escaped using the underscore character (_), followed by the two-digit hexidecimal value of the character. This means that underscores are themselves escaped as _5F, as well as any other punctuation characters. Unicode characters are allowed in bookmark names, as well as 8-bit characters between 128 and 255.
• Not all Word fields are automatically updated when a document is first opened. Consequently, field results may not be immediately visible in published documents. To update the fields in an RTF (or Word) document, open the document, press CTRL+A to highlight the entire document, and press F9 to refresh. This process can be automated with a post-publishing hook, which can load the RTF document into Word, update the fields, and save the changes to RTF or to a binary (.doc) format.
