Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

...

Description

Excerpt

Sets the MailMerge's

...

data

...

source

...

to

...

a

...

two-dimensional

...

(rectangular)

...

array

...

of

...

objects.

...

A

...

MailMerge

...

by

...

default

...

treats

...

the

...

page

...

content

...

as

...

a

...

repeat

...

block,

...

repeating

...

the

...

page

...

content

...

for

...

each

...

row

...

unless

...

NEXT

...

fields

...

are

...

used.

...

If

...

the

...

WordTemplate.EnableNEXTFields

...

property

...

is

...

set

...

to

...

true,

...

the

...

NEXT

...

field

...

can

...

also

...

be

...

used

...

to

...

indicate

...

that

...

the

...

next

...

row

...

of

...

data

...

should

...

be

...

inserted

...

instead

...

of

...

the

...

current

...

row

...

at

...

the

...

next

...

occurence

...

of

...

the

...

merge

...

fields.

...

This

...

should

...

largely

...

imitate

...

the

...

behavior

...

of

...

a

...

Microsoft

...

Word

...

Mail

...

merge.

...

Signature
C#
C#
 public void SetMailMerge(System.Object[][] jaggedArray, System.String[] columnNames)
{signature}
{signature:
}
Signature
vb.net
vb.net
Public Sub SetMailMerge(ByVal jaggedArray As Object()(), ByVal columnNames As String())
{signature}
{parameters}
{param:jaggedArray}The jagged array \(array\-of\-arrays\) to use as the data source.
{param}
{param:columnNames}The one\-dimensional array of strings that represent the field names to be replaced by the data. These names must match the column names from your data source.
{param}
{exceptions}
{exception:ArgumentNullException}[Save|WordTemplate.Save] will throw this exception if {{null}} \(C\#\) or {{Nothing}} \(VB.NET\) is passed to the method.
{exception}
{exception:ArgumentException}
{exception}
{remarks}You can call [SetMailMerge|WordTemplate.SetMailMerge] once for each instance of [WordTemplate].  If you are using the Word 2003 binary template file type 
Parameters
Param
jaggedArray
jaggedArray

The jagged array (array-of-arrays) to use as the data source.

Param
columnNames
columnNames

The one-dimensional array of strings that represent the field names to be replaced by the data. These names must match the column names from your data source.

Exceptions
Exception
ArgumentNullException
ArgumentNullException

Save will throw this exception if null (C#) or Nothing (VB.NET) is passed to the method.

Exception
ArgumentException
ArgumentException

Remarks

You can call SetMailMerge once for each instance of WordTemplate. If you are using the Word 2003 binary template file type (.doc/.dot),

you

can

call

SetMailMerge

or

SetRepeatBlock,

but

not

both.

Additionally,

only

the

page

content

is

repeated

for

each

row,

not

the

entire

page

itself.

If

you

wish

to

have

the

page

itself

repeat

for

each

row,

you

will

need

to

remember

to

place

a

page

break

at

the

bottom

of

the

page. 

Alternatively,

you

can

create

a

hidden

page

break

at

the

top

of

the

page

as

follows:

*

  • Put
  • the
  • cursor
  • at
  • the
  • top
  • of
  • the
  • document
*
  • Go
  • to
  • Page
  • Layout
  • and
  • open
  • the
  • paragraph
  • formatting
  • dialog
*
  • On
  • the
  • Line
  • and
  • Page
  • Breaks
  • tab,
 
  •   select
  • "Page
  • Break
  • Before"

Merge

Fields

for

using

the

SetMailMerge

method

must

not

specify

a

data

source

--

the

data

source

is

implied,

and

using

a

data

source

name

will

cause

WordTemplate

to

throw

an

error.

Valid

merge

field

formats

for

use

with

SetMailMerge

include

field

names

(*«fieldname»*) and field ordinals (*«#1»*). {introducedin: 8.2} [SetMailMerge|WordTemplate.SetMailMerge] will now work with headers and footers. A section break is required instead of a page break if each header or footer will be different. {remarks} {example}{code:csharp|title=C#}

(«fieldname») and field ordinals («#1»).

Introducedin
8.2
8.2

SetMailMerge will now work with headers and footers. A section break is required instead of a page break if each header or footer will be different.

Example
Code Block
csharp
csharp
titleC#


          ...
          //--- A 2-D jagged array of values
          object[][] data = new object[][]{
               new string[]{"Knoxville","Tennessee"},
               new string[]{"Boston","Massachusetts"},
               new string[]{"Washington","DC"},
               new string[]{"Seattle","Washington"},
               new string[]{"Chicago", "Illinois"},
               new string[]{"New York","New York"},
               new string[]{"Atlanta", "Georgia"},
               new string[]{"Los Angeles", "California"},
               new string[]{"Houston", "Texas"}
               };

          //--- Names array, elements correspond to merge field names
          string[] names = new string[]{"City", "State"};
          WordTemplate wt = new WordTemplate();
          wt.Open(Server.MapPath("template/MergeFieldTest.doc"));

          //--- Set the mail merge
          //--- The data source is the 2-D jagged data array
          wt.SetMailMerge(data, names);
          wt.Process();
          wt.Save(Page.Response, "output.doc", false);
        
{code} {code:
Code Block
vb.net
|title=
vb.net
titlevb.net
}


          ...
          '--- A 2-D jagged array of values
          Dim data()() As Object = { _
               New Object() {"Knoxville", "Tennessee"}, _
               New Object() {"Boston", "Massachusetts"}, _
               New Object() {"Washington", "DC"}, _
               New Object() {"Seattle", "Washington"}, _
               New Object() {"Chicago", "Illinois"}, _
               New Object() {"New York", "New York"}, _
               New Object() {"Atlanta", "Georgia"}, _
               New Object() {"Los Angeles", "California"}, _
               New Object() {"Houston", "Texas"} _
               }

          '--- names array, elements correspond to merge field names
          Dim names() As String = {"City", "State"}
          Dim wt As New WordTemplate()
          wt.Open(Server.MapPath("template/MergeFieldTest.doc"))

          '--- Set the mail merge
          '--- The data source is the 2-D jagged data array
          wt.SetMailMerge(data, names)
          wt.Process()
          wt.Save(Page.Response, "output.doc", False)
          ...
        
{code} {example}