Custom Programming – Custom Document Design in Version 8 Document Revision: 1

Custom Programming Documentation April 24, 2002

Creating Custom Documents in V8

Overview:

The version 8 document printer operates by receiving an XML document that contains the fields and values that are to be printed.

Any field that appears in the XML and has a corresponding field in the document design will be printed on the document.

Adding a custom field to a document therefore requires two steps: adding the custom field to the document design and adding the
custom field to the XML that is passed to the document printer.

Document Designer:

The available fields in the document designer are tied to the XML schema that is provided for each document type. However,
custom fields can be added to the document design without changing the schema provided by RTI. (In fact, it is NOT a good idea to
change the XML schema).

How to Add a Custom Field to a Document Design

1) Start document designer and select an existing design or start a new one.

2) Decide where the new field is going to be placed.

3) Select a field from the list of available fields and place it on the design.

4) Click on the new field on the design.

5) Go to the Properties tab of the document designer.

6) Change the Caption property to whatever name you want for the new field.

7) Change the Data Field Name to the name of the data field you want to use for the custom field. The Data Field Name is
used to match the values in the XML containing the document information.

For example, you want to add a field that contains the four-digit year of the system date at the time the document is
printed. You place a new field on the document and change the caption to “System Year” and then set the Data Field
Name to “SysYear”. Now if the XML passed to the document printer contains a value for “SysYear”, it will appear on the
document.

Nested (Repeating) Fields

The Data Field Name will also determine the level of “nesting” of the field using the standard “dot” structure for object models.

For example, on an invoice, receipt item data is nested one level below the receipt information. This is represented in the tree
structure of the Fields panel of the document designer where ReceiptItem is shown one level below Receipt.

If you wanted to add a custom field called ExtTax for each receipt item, the Data Field Name would be set to ReceiptItem.ExtTax.

The dot structure relates to the XML that will be passed to the document printer. For an invoice, the top-level node in the XML is
<Receipt>. If a field is added to an invoice document design with no “Name.” prefix, the document printer assumes the field is in the
top-level node of the XML.

However, if the “Level.FieldName” structure is used in the Data Field Name, the document printer assumes that the FieldName
occurs in a node named “Level” that is a child node of the top-level node in the XML.

For example, in the XML for a receipt, the item information is presented in a series of <ReceiptItem> nodes below the <Receipt>
node:

<Receipt>
<ReceiptItem>
</ReceiptItem>
<ReceiptItem>

Page 1 of 3
Custom Programming – Custom Document Design in Version 8 Document Revision: 1

</ReceiptItem>
… as many ReceiptItem nodes as there are items on the receipt
</Receipt>

NOTE: THE ONLY THING YOU CAN’T CHANGE IS THE TOP-LEVEL NODE NAME USED IN THE DESIGN. FOR EXAMPLE, ALL
INVOICE DOCUMENT DESIGNS ASSUME THAT THE XML WILL HAVE A <RECEIPT> NODE AS THE TOP-LEVEL NODE.

The dot structure can be extended to multiple nested levels. For example, the Data Field Name can be set to
Level1.Level2.FieldName. In this case, if the document printer finds FieldName in a node named Level2 below a node named
Level1 below the top-level node of the XML, the field will be printed.

It is also possible to create entire custom levels of information using this structure. The “level” node name does not have to appear
in the pre-defined levels available for that particular document.

For example, if the Data Field Names for three custom fields are set to “StoreInfo.Name”, “StoreInfo.Number” and
“StoreInfo.Heading” and the XML contains a “StoreInfo” node below the “Receipt” node, the Name, Number and Heading values will
be printed if the field names have values assigned.

Missing Fields and Nodes

If a FieldName or Level exists in the document design but is missing from the XML, the field will just not be printed. So, it is safe to
add custom fields to a document design that may not appear in the XML passed to the document designer.

Document XML:

Once the document design is adjusted to include the custom fields, the next task is to actually get the field values to the document
printer at run time.

The document printer receives its data in XML format. The document printer ONLY uses the XML and the document design to print
the document. So, the run-time values must be placed in the XML that is passed to the document printer at run-time.

Some knowledge of manipulating XML documents is necessary to perform this task.

Assigning Values to Fields

Assigning a value to a field in the XML is actually quite simple. Each Field Name is an attribute of a node and the attribute value is
the field value.

For example, the <Receipt> node for an invoice will contain attributes for each field in the receipt header. As an illustration showing
only the Store, Station, Workstation, InvcNum and DocPostDate fields:

<Receipt Store=”001” Station=”0” Workstation=”1” InvcNum=”10001” DocPostDate=”01/02/2002 3:41:13 PM”>

</Receipt>

If we wanted to add the “SysYear” custom field to this document, we would add an attribute and value to the Receipt node:

<Receipt Store=”001” Station=”0” Workstation=”1” InvcNum=”10001” DocPostDate=”01/02/2002 3:41:13 PM” SysYear=”2002”>

</Receipt>

One way to add the attribute is by using the SetAttrbute method for an XML Element Node. If xmlElement is set to the Receipt node
in the XML document, the following statement will add the SysYear attribute and value:

xmlElement.setAttribute "SysYear”, "2002"

Once the attribute and value are added to the node, the document printer will find it and print the custom field.

The same scheme works for child nodes. For example, receipt items appear as <ReceiptItem> child nodes of the <Receipt> node.
Each <ReceiptItem> node has attributes that describe the item on the receipt. Here is an illustration using only a few of the receipt
item attributes:

<Receipt Store=”001” Station=”0” Workstation=”1” InvcNum=”10001” DocPostDate=”01/02/2002 3:41:13 PM” SysYear=”2002”>

<ReceiptItem ItemLookup=”100” Desc1=”Item desc one” Desc2=”Item desc2” />
<ReceiptItem ItemLookup=”101” Desc1=”Item desc 101” Desc2=”Item desc2 101” />
</Receipt>

Page 2 of 3
Custom Programming – Custom Document Design in Version 8 Document Revision: 1

The “ExtTax” field could be added to each receipt item by adding the “ExtTax” attribute (and value) to each <ReceiptItem> node
under the <Receipt> node.

As another example, the entire “StoreInfo” level could be added to the invoice XML by adding <StoreInfo> nodes as children of the
<Receipt> node:

<Receipt Store=”001” Station=”0” Workstation=”1” InvcNum=”10001” DocPostDate=”01/02/2002 3:41:13 PM” SysYear=”2002”>

<ReceiptItem ItemLookup=”100” Desc1=”Item desc one” Desc2=”Item desc2” />
<ReceiptItem ItemLookup=”101” Desc1=”Item desc 101” Desc2=”Item desc2 101” />
<StoreInfo Name=”Store1” Number=”001” Heading=”Store1 Heading” />
<StoreInfo Name=”Store2” Number=”002” Heading=”Store2 Heading” />
<StoreInfo Name=”Store3” Number=”003” Heading=”Store3 Heading” />
</Receipt>

Modifying the XML:

Once you have determined what nodes and attributes must be added to the XML to define the custom fields, you have to change
the XML at run-time.

There are two ways to do this: use a script file or use a version 8 plug-in.

Script Files

You can access and change the XML that is passed to the document printer at run-time by creating a script file with the same name
as the document you are using and placing the script file in the same directory as the document design itself.

Document designs will appear under the RPro folder in the DocDesigns/[DocType] folder.

As an example, a new Receipt document design called “MyDesign” is created and saved in the RPro\DocDesigns\Receipt folder.
The design contains a custom field called “MyField” that is part of the receipt header information. At run-time you want to set the
value of “MyField” to “myname”.

This can be done by creating a VB Script file called “MyDesign.vbs” in the RPro\DocDesigns\Receipt folder. The VB Script file
contains the following code:

sub Main(xmlDoc) ‘The XML document is passed to sub(Main)

For Each xmlElement In xmlDoc.getElementsByTagName("Receipt") ‘Find the Receipt node in the XML.
xmlElement.setAttribute "MyField”, "myname" ‘ Add a MyField attribute with the value “myname”
Next
end sub

When a receipt is printed using the MyDesign document design, the script file is automatically executed, the MyField attribute is
added to the XML and “myname” appears on the document.

Note that the script file MUST be in the same directory as the document design.

The drawback to using the script file is that you only have access to the information that is already passed in the XML. You do not
have access to Retail Pro run-time values. Depending on the type of custom information you are setting, this may not be a problem.
But using V8 plug-ins is definitely more flexible.

Version 8 Plug-Ins

It is also possible to change the XML going to the document printer from a plug-in.

The plug-in should implement the BeforePrint function of the TOnPrint class. At run-time, core Retail Pro will pass the XML
document as a parameter to the function. The plug-in code can then add the custom fields to the XML.

Consult the Plug-In Programmer’s Guide for more information on the TOnPrint class.

Viewing Document XML:

An easy way to see the XML that is created for any document is to create a script file that saves the XML document. You can then
open the XML document to see the node and attribute structure. Here’s an example for the MyDesign.vbs file:

xmlDoc.save("C:\Test\MyDesign.xml")
Page 3 of 3