Generating business
documents using XML and MS-Word 2003.
Wh=
y use XML
and not go straight into Word?
Us=
ing Word
as an Automation server to insert data in a document is good enough for sm=
all
documents that need a few data-elements. As soon as the amount of data gro=
ws or
multiple documents have to be generated, the speed is generally not good
enough.
Fu=
rther
more, while such a process is in progress the application is usually block=
ed
and the user can only wait, or abort because they do not understand what is
happening.
Us=
ing XML
as the file format for generating Business Documents will deliver flexibil=
ity,
scalability, and simplicity for the developer and End users alike.
Th=
is
article presents a way to write the data part of documents without even st=
arting
Word, yet it will use Word for display and/or print and allow the users to
alter the appearance of the documents without the need for developers. As =
long
as the data and schema contains the information that is required, users ha=
ve
more or less complete freedom to apply formatting and layout as they need =
to.
Documents like this can have several different appearances for different
purposes. A user could decide to view the details of an order, or an overv=
iew
of sales in that day all using the same generated XML data. Different kind=
s of
views can be defined by developers or users or existing ones can be modifi=
ed on
the fly. The documents can be generated on a server without installing Wor=
d which
is a big bonus. This is also a very convenient option for websites that let
users download data or Word documents.
Fr=
om a developers
perspective it is not very difficult to build solutions using Word and XML=
. The
only drawback is that there are different steps involved, each requiring t=
heir
own tools. Keeping it all in sync and doing it in the right order takes a =
bit
of getting used to.
In
this article we will build a letter to be send out of the organization
regarding a client’s assets stating some details to identify the cli=
ent
and listing the relevant assets in a Word-table. This is a scenario that w=
ill
show how to handle form as well as a list of repeating data.=
It uses MS Word 2003 profess=
ional but
the same scenario can be used in Office 2007. The good news for 2007 is th=
at it
will work in all SKU’s, the XML support is no longer limited to the
professional version.
Step 1, create a sc=
hema
Wo=
rking
with XML requires a schema (the XSD-file), and this is a good thing. Proba=
bly the
easiest way to build and manage our schemas is using Visual Studio 2005 or
XMLSPY but it could just as well be done using Notepad. This article will =
not
go into any detail on how to create schemas, there are lots of resources
available (see Appendix A). For most documents a fairly simple schema is
sufficient, for the example here the schema describes some data at the root
level and some repeating data in a one to many relationship. In this case =
the
root level has elements like ClientName and Ad=
dress,
repeating elements are the asset description and an associated value. The
schema used in this example looks like this:
F=
igure 1, schema for Statement of Ass=
ets in
Notepad
Ma=
ke sure
to save this file in a convenient location. More and more schema’s w=
ill
be used in a production environment. It is important to be well organized =
in
particular during development when there is the risk of having to create
multiple versions implementing small changes over time. Only with a well
organized folder structure will prevent making mistakes along the way. Word
does lend a helping hand here as it caches the schema’s that are use=
d and
knows where to find then, but it is necessary to tell Word where they are
coming from initially. This is described in Step 2.
Step 2, apply the s=
chema
to a word document
Th=
e way to
inform MS-Word about a schema, is by loading it into the Schema Library. F=
or
this purpose Word has a dialog to manage XML related data. It actually cac=
hes
the files in a specific storage area which can be maintained either on a u=
ser
specific basis, or for all users using the workstation. Open MS-Word and o=
pen a
new blank document.
Op=
en the
XML dialog by choosing Tools, Templates and Add-ins and selecting the XML-=
tab.
Click on Add Schema, browse to the saved file and give it a user-friendly =
to
easily identify it later on when this list grows. Naming schema’s;
Schema1, Schema2 etc. will quickly create an unmanageable list.
Un=
-check
Apply to Current user only when the schema needs to be made available to a=
ll
users of the system.
Cl=
ick Ok,
next click XML Options and check the Ignore
mixed content checkbox. This allows Word to ignore any additional text=
you
want to use in your document that does not go into the actual XML-file it =
will
be using. When this option isn’t set, Word will not save a document =
as
XML-data. The document won’t adhere to the schema (which only allows=
the
data elements) because there is additional text in between the XML element=
s.
m
F=
igure 2, Adding a schema to the libr=
ary and
setting the details
No=
w the
schema can be applied to the document and additional text can be mixed with
data elements.
Wo=
rd has a
special task pane that can be displayed next to the document, the XML Stru=
cture
Task Pane. --à>>>>>> Chec=
k if
this happens automatically and explain how to open it. Add a picture.
It=
is important
to always have the XML Structure task pane displayed; it now shows the
‘Statement’ element in the lower right corner as the only thin=
g in
the list. Adding additional Schema’s would show up beneath each othe=
r.
Th=
e root
element of the schema needs to be applied to the entire area of the docume=
nt
where elements will occur, typically this is the entire document. Selectin=
g the
Statement element in the XML Structure Pane, and apply it to the entire
document. This will make the XML-tags appear in the document. Now the docu=
ment
can be further build by adding text and XML-elements between the Statement=
tag.
The other nested xml-tags are now available when the cursor is inside the =
root
element. To build the example Statement of Assets add some layout and the =
RecipientAddress, ClientName,
Balance and SubTotalAssets elements as shown i=
n the
next figure.
F=
igure 3, Document after adding some =
basic
elements
An=
y kind of
styles or formatting can be applied to these elements and they will not sh=
ow up
when the document is printed by default. The tags can be hidden from view =
using
Ctrl-Shift-X. Optionally a document can be printed including the XML-tags =
which
might be a useful feature while developing or to use when generating end u=
ser
documentation for solutions build this way.
Th=
e goal
was to also show a table for repeating data, for this a table can be added
using the normal Insert Table menu commands.
- Insert a 1 row, 2 column table in between bal=
ance
and subtotal.
- Now select the row by clicking just in front =
of
the table, the row should be completely highlighted.
- With the row selected click on the Assets Ele=
ment,
this should insert the opening tag in the first column and the close =
tag
in the second.
- Position the cursor just right of the opening
Assets tag and click the Description element. Position in the second
column and click the Value element.
Th=
e document
should now look like the figure below.
F=
igure 4, Document with all schema el=
ements
applied
To=
test if
the elements are really applied to the row in the right way position the c=
ursor
to the right of the table, and press enter, Word will add a new row which
should have schema tags applied to them automatically.
No=
w save
the document, this is a document that can be used as a seed document to
generate the XSLT file needed in later steps.
In=
dications
are visible in the XML Structure pane (yellow signs) that point to
inconsistency in the data. This is XML-schema validation in action. Becaus=
e the
schema implies a numeric value for the Value element and there is nothing =
for
the value in the actual document, empty is not considered a valid numeric =
value.
As soon as a value is entered in the value element the indicators will
disappear. Hovering the mouse over the yellow indicators will make a toolt=
ip
appear with a better explanation of what may be the problem, usually for o=
ur
purposes they can safely be ignored.
Step 3, adding data=
and
saving as XML (this will be an example for step 4)
If=
any of
the previous steps were not successful Example.doc as included in the down=
loads
for this article is in the state it should be in after finishing step 2.
Op=
en the
document and manually enter some sample data, to save it as plain XML data
using MS-Word. Enter some data in between all of the elements and choose S=
ave
As, change the type to XML, check=
Save
data only. (the result is also available in the downloads: ‘Stat=
ement
Raw.XML’). Saving as xml wi=
thout
checking Save data only will save the file as a WORDML file in the new XML
format for Word that was introduced in Office 2003. Do that save as well to create a WordML
file for input in Step 4 (‘Statement with data.xml’ in the
downloads). Have a look at b=
oth
files using notepad or display it in Internet Explorer, to get an idea of =
how
these files look.
Th=
e new XML
format, WordML is very interesting, it is now =
the
native file format for Word. Word can handle that as good as it handles .d=
oc
files, and it gives developers the opportunity to write Word compatible fi=
les
just by using XML documents. This means developers can easily create Word =
files
without the need to start or install Word. Ideal for server based scenario=
s like
websites and to quickly generate large amounts of files when needed (Invoi=
ces,
yearly statements etc.).
Step 4, generate an=
XSLT-file
Wo=
rd also
has the ability to read a raw xml data file (just like Statement Raw.xml) =
but
display it using the formatting and styles just created in the above seed =
document.
This is done by applying an XML transform based on an XSLT file.
Cr=
eating an
XSLT file by hand is no easy task, which is why the Office team has provid=
ed a
tool for that uses the WordML file as input an=
d writes
an XSLT file. Word can use such an XSLT file to always apply the translati=
on
when opening an XML file that references a particular schema
(StamentOfAssets.XSD in this case). Now first download and install the
WML2XSLT tool.
He=
re’s
the url where this tool is available:
Co=
py the WordML file from step 3 (Statement with data.xml) in=
to the
same folder as where the WML2XSLT-tool is installed to prevent having to t=
ype
paths as this is a command line tool. Open a command prompt. Navigate to t=
he
same folder and run the following command: WML2XSLT “Statement with
data.xml” –o Statement.xslt .
Th= is will create the translation file, Statement.xslt. <= o:p>
Wo=
rd needs
to be configured to associate that specific XSLT file with XML files that =
use
the StatementOfAssets schema. This is also don=
e in
the Template and Add-ins dialog. On the XML tab click on Schema Library an=
d on
the next dialog make sure the schema you want to associate with the XSLT is
highlighted (this would be Statement of Assets for this example). Now clic=
k Add
Solution and browse to the just created .XSLT file to open it. Give it a
friendly name and close the dialogs.
Step 5, open the ge=
nerated
XML in Word for viewing or printing
Th=
is is
actually the easiest part, as it now all happens automatically. Right clic=
k the
“Example Raw.xml” file and choose Open with Microsoft Office W=
ord.
Word will see the reference to the schema and automatically apply the
transform. So, as long as the generated XML-files from a Line Of Business =
application
use this schema Word will make it look nice and/or print it using the XSLT=
.
Op=
tionally different
XSLT-files can be attached to the schema and the user can pick how to disp=
lay
or print the document by selecting the appropriate XSLT. One XSLT could ge=
nerate
a view that displays all details, and another one can print a summary, or consider a sce=
nario
that requires an internal view and a public view for printing.
Wh=
en an XML
file is opened that has no XSLT attached to its schema (using the Add Solu=
tion
dialog), a translate can sti=
ll be
applied. Word opens a task pane next to the XML that shows the available X=
SLT
options or allows a user to browse and manually open an XSLT to apply.
Th=
e Example
RAW.xml can be used as a sample of how the XML should look like that needs=
to
be generates from an application. In the case of Windows 32-bit application
development environments such as Visual Object of Visual Foxpro
one would use the MS-XML automation objects to generate such a file. Below=
is a
listing of Visual Objects code that writes an XML file like that and calls=
into
Word to actually open it.
// Create a simple XML file using all
fields in oTmp (a dataser=
ver)
// Use a wrapper class for the MS-XML =
Dom
Document automation server
oXMLFile=
:=3D MS_IXMLDOMDocument{}
// Make sure we write an XML file and =
apply
an encoding attribute
oP :=3D oXMLFile:createProcessingInstruc=
tion("xml",;
[version=
=3D'1.0'
encoding=3D'utf-8'])
oXMLFile:Append=
child(oP)
// Create the root-element
onewElement :=3D oXMLFile:createElement(&q=
uot;_x0039_3100")
// Apply schema attribute, this allows=
Word
to lookup
// which XSLT can be used.
onewElement:set=
Attribute("xmlns",;
"http://te=
mpuri.org/93100-CertificateOfReceipt.xsd")
oRoot :=3D oXMLFile:appendChild(onewElement)
// Now loop through all fields
FOR nI :=
=3D 1 TO SELF:oTmp:FCount
=
&n=
bsp; //
Create an XML element for everu field
=
onewElement
:=3D oXMLFile:createElement(SELF:oTmp:FieldName(nI))
IF
Upper(SELF:oTmp:FieldName(nI))
=3D=3D "AMOUNTRCVD"
=
&n=
bsp; &nbs=
p; oNewElement:T=
ext_
:=3D ;
"$ "+Transform(SELF:oTmp:FIE=
LDGET(nI),"999,999,999.9")
ELS=
E
=
&n=
bsp; oNewEl=
ement:Text_
:=3D AsString(SELF:oTmp:F=
IELDGET(nI))
=
&n=
bsp; ENDIF
=
&n=
bsp; //
Append the element to the root
=
&n=
bsp; oRoot:appendChild(onewElement)
NEXT&n=
bsp;
// Write the file to disk
oXMLFile:Save("C:\FIC\REPORTS\93100.XML")
// Tell the garbage collector we are d=
one
oXMLFile=
:=3D NULL_OBJECT
……
// Open word and XML-file
oWord :=3D OLEAutoObject{"Word.Application", NIL, NIL, TRUE}
oWord:visible :=3D TRUE
oWord:Documents=
:Open("C:\FIC\REPORTS\93100.XML")
oWord :=3D NULL_OBJECT
// Typically code would not close word=
as
the user
// is now in control of Word
Fr=
om a
developers’ perspective it is obviously very easy to create Word fil=
es
this way. By supplying an appropriate XSLT it will quickly look profession=
al in
Word. The schema and XSLT tool provide a quick and flexible way to create
additional views based on the data in the XML file. End user themselves te=
nd to
quickly get used to the way the XML options in Word work which creates a v=
ery
flexible platform for professional output solutions and easy to modify let=
ters
or statements.
The
Software Objectives web site, www.VOConversion.com.au has a more complex c=
ode
examples for Visual Objects, VBScript and code samples in C#.
Th=
e above
concept applies equally well to Microsoft Excel, although that works sligh=
tly
different because of the nature of a spreadsheet in contrast to a Word
document. A similar article describing the Excel approach is coming on
VOConversion.com.au.
&c=
opy; Ed
Richard, Software Objectives
su=
mmer 2006
Me=
lbourne,
Australia