Creating Your First Word File

SoftArtisans WordWriter opens a WordWriter template file, populates it with data from a specified data source, and generates a new Word file. A WordWriter template is a file created in Microsoft Word that contains merge fields. A merge field displays a data source field name (for example, a database column name) where a data source value will be inserted. Merge fields are bound to a data source in the WordWriter ASP.NET script. When you run the code, WordWriter populates the data markers with values from the data source and creates a new Word file.

Step 1: Create a Template To generate a Word file with WordWriter, first create a template: In Microsoft Word, create a new file. From the Insert menu, select Field... to open the Field dialog. From the Field names list, select MergeField. In the Field name text box, enter a name for the merge field. For example, enter ProductName. Click Ok. The merge field will be displayed in the document in the format <<Field Name>>. To insert additional merge fields, repeat steps 2-4.

To add a merge field to a template, select open the Insert menu and select Field. The merge field display format is <<Field Name>>.

Top

Step 2: Write the WordWriter Code

Next, create an ASP.NET script that uses WordWriter to open the template, fill in merge field values, and generate a new Word file. The VB.NET and C# samples above generate a file from the template StringVarTemplate.doc (included in WordWriter\doc-samples\samples\basic\stringvar). This template contains a single merge field - <<Product Name>>. The data source for the merge field is a single-element array.

The WordTemplate object represents the template Word file. The WordTemplate object is in the SoftArtisans.WordWriter namespace. The object can be referenced as SoftArtisans.WordWriter.WordTemplate. To minimize typing and errors, use an Import directive to import the namespace to the aspx page, and reference the object as WordTemplate, without the namespace prefix:

	<%@ Import Namespace="SoftArtisans.WordWriter" %>

To generate a new Word file with WordWriter:

1. Create an instance of the WordTemplate object, for example:

   	'--- Declare the WordTemplate object and 
   	'--- intialize it as Nothing.
   	Dim oWW As WordTemplate = Nothing
   	...	
   	'--- Instantiate the WordTemplate object.
   	oWW = New WordTemplate()
   

2. Call WordTemplate.Open to open a template Word file, for example:

   oWW.Open(Server.MapPath("./StringVarTemplate.doc")) The Open method takes either the template's path (as in the example) or a System.IO.Stream object (for example, System.IO.FileStream).

   WordWriter supports Microsoft Word 97, 2000, and 2002 (XP). Do not use Open to open files created in earlier versions of Microsoft Word.

   
   
3. Call WordTemplate.SetDataSource to bind the template's merge fields to a data source, for example:

   	Dim arrValue As Object() = {"SoftArtisans WordWriter"}
   	Dim arrName As String() = {"ProductName"}
   	...
   	oWW.SetDataSource(arrValue, arrName)

   StringVar-vb.aspx uses a single variable as a data source. To set the data source to a single value, put the value in a single-element object array, and the merge field name in a single-element string array. Pass the two arrays to WordTemplate.SetDataSource.

4. Call WordTemplate.Process to enter values from the data source into the template's merge fields:

   	oWW.Process()

5. Call WordTemplate.Save to save the generated file or stream it to the browser. In the samples above the file is streamed to the browser:

   	oWW.Save(Page.Response, "StringVarOutput.doc", False)

   When you pass Save an HttpResponse object (Page.Response) WordWriter will stream the file to the browser. The method's second parameter specifies a default name for the generated file; this name will be displayed in the browser's File Download dialog. The third parameter specifies whether the file should open in the browser window or in Microsoft Word; if the parameter is set to False, the file will open in Word.

   WordWriter also allows you to save the generated file on the server. For more information, see Output Options.

Top

Copyright © 2003, SoftArtisans, Inc.