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 specified repeat block's

...

data

...

source

...

to

...

a

...

jagged

...

array

...

(array

...

-of

...

-arrays

...

)

...

of

...

objects.

...

Signature
C#
C#
 public void SetRepeatBlock(System.Object[][] jaggedArray, System.String[] columnNames, System.String bookmark, int maxRows, boolean transpose)
{signature}
{signature:
}
Signature
vb.net
vb.net
Public Sub SetRepeatBlock(ByVal jaggedArray As Object()(), ByVal columnNames As String(), ByVal bookmark As String, ByVal maxRows As Integer, ByVal transpose As Boolean)
{signature}
{parameters}
{param:jaggedArray}An jagged array of objects to use as a data source.  the first dimension corresponds to row and the second to column \(that is, Object\[row\]\[column\]\). WordWriter will insert these values in the repeat block's merge fields.
{param}
{param:columnNames}A string array of data source field names. These must be the same as the corresponding merge field names in the template.
{param}
{param:bookmark}The bookmark name of the template repeat block. The bookmark passed to {{SetRepeatBlock}} must exist in the template Word file. To see a list of template bookmark names: 
# Open the template in Microsoft Word.
# Open the *Edit* menu.
# Select *Go To...*
# Select *Bookmark*.
# Under *Enter bookmark name*, open the drop\-down list of bookmark names.
{param}
{param:maxRows}Specifies the maximum number of repetitions to write to the file. If Next fields are enabled (see [EnableNEXTFields|WordTemplate.EnableNEXTFields]), then the number of rows imported from the data source is {{maxRows\*(numberOfNextFields\+1)}}. If Next fields are not enabled the number of rows imported is equal to the number of repetitions written out. To write the maximum rows available, use the constant [WordTemplate.ALL\_ROWS|WordTemplate.ALL_ROWS].
{param}
{param:transpose}If transpose is set to {{true}}, the array is treated as Object\[column\]\[row\]. If transpose is set to {{false}}, the array is treated as Object\[row\]\[column\].
{param}
{exceptions}
{exception:ArgumentNullException}{{SetRepeatBlock}} will throw this exception if {{null}} \(C\#\) or {{Nothing}} \(VB.NET\) is passed to the method.
{exception}
{exception:ArgumentException}
{exception}
{introducedin:8.4}
{exception:SAException}{{SetRepeatBlock}} will throw this exception if the {{bookmark}} has been set to be  [removed|WordTemplate.BookmarksToRemove].{exception}
{remarks}
A repeat block is a fragment in the template document that will be repeated for each row in a data source. In the template document, repeat blocks are defined by Word bookmarks that contain merge fields.

You can call [SetRepeatBlock|WordTemplate.SetRepeatBlock] several times for a single instance of [WordTemplate]. The repeat block specified by the parameter {{bookmark}} must exist in the template.

If you pass an empty data source to {{SetRepeatBlock}} WordWriter will not include the specified repeat block in the generated Word file.

Not all Word features can be included in a repeat block:
{web-only:To see a full chart of limitations, go to our online documentation:}
|| Supported in Repeat Blocks || Not Supported in Repeat Blocks ||
| * Character Formatting  (everywhere)
* Paragraph Formatting (Alignment, Outlines, Indent, Spacing, Page Break before, Keep Together)
* Multiple Columns (2, 3, Column Breaks)
* Borders and Shading
* Tabs
* Bullets
* Numbering (numbering not reset, it is continued from one repeat block to another)
* Page Breaks
* Section Breaks
* Auto Text Field
* Hyperlink
* Pictures
* Table Row Repeat (entire row only)
* Fields (with some restrictions) | * Nested repeat blocks (Only one data source may be assigned to a single repeat block.)
* Overlapping bookmarks
* Comments
* Drawing Objects
* Text Boxes
* Footnote and endnote references
* Table and picture indexes
* Single cell in a table
* Smart tags (smart tags will be removed from the document)
* Repeat blocks in headers, footers, footnotes, comments,  text boxes, etc. |
{web-only}
{remarks}
{example}{code:csharp|title=C#}
Parameters
Param
jaggedArray
jaggedArray

An jagged array of objects to use as a data source. the first dimension corresponds to row and the second to column (that is, Object[row][column]). WordWriter will insert these values in the repeat block's merge fields.

Param
columnNames
columnNames

A string array of data source field names. These must be the same as the corresponding merge field names in the template.

Param
bookmark
bookmark

The bookmark name of the template repeat block. The bookmark passed to SetRepeatBlock must exist in the template Word file. To see a list of template bookmark names:

  1. Open the template in Microsoft Word.
  2. Open the Edit menu.
  3. Select Go To...
  4. Select Bookmark.
  5. Under Enter bookmark name, open the drop-down list of bookmark names.
Param
maxRows
maxRows

Specifies the maximum number of repetitions to write to the file. If Next fields are enabled (see EnableNEXTFields), then the number of rows imported from the data source is maxRows*(numberOfNextFields+1). If Next fields are not enabled the number of rows imported is equal to the number of repetitions written out. To write the maximum rows available, use the constant WordTemplate.ALL_ROWS.

Param
transpose
transpose

If transpose is set to true, the array is treated as Object[column][row]. If transpose is set to false, the array is treated as Object[row][column].

Exceptions
Exception
ArgumentNullException
ArgumentNullException

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

Exception
ArgumentException
ArgumentException

Introducedin
8.4
8.4
Exception
SAException
SAException

SetRepeatBlock will throw this exception if the bookmark has been set to be removed.

Remarks

A repeat block is a fragment in the template document that will be repeated for each row in a data source. In the template document, repeat blocks are defined by Word bookmarks that contain merge fields.

You can call SetRepeatBlock several times for a single instance of WordTemplate. The repeat block specified by the parameter bookmark must exist in the template.

If you pass an empty data source to SetRepeatBlock WordWriter will not include the specified repeat block in the generated Word file.

Not all Word features can be included in a repeat block:

Web only
To see a full chart of limitations, go to our online documentation:
To see a full chart of limitations, go to our online documentation:

Supported in Repeat Blocks

Not Supported in Repeat Blocks

  • Character Formatting (everywhere)
  • Paragraph Formatting (Alignment, Outlines, Indent, Spacing, Page Break before, Keep Together)
  • Multiple Columns (2, 3, Column Breaks)
  • Borders and Shading
  • Tabs
  • Bullets
  • Numbering (numbering not reset, it is continued from one repeat block to another)
  • Page Breaks
  • Section Breaks
  • Auto Text Field
  • Hyperlink
  • Pictures
  • Table Row Repeat (entire row only)
  • Fields (with some restrictions)
  • Nested repeat blocks (Only one data source may be assigned to a single repeat block.)
  • Overlapping bookmarks
  • Comments
  • Drawing Objects
  • Text Boxes
  • Footnote and endnote references
  • Table and picture indexes
  • Single cell in a table
  • Smart tags (smart tags will be removed from the document)
  • Repeat blocks in headers, footers, footnotes, comments, text boxes, etc.
Web only

Example
Code Block
csharp
csharp
titleC#


          //--- A 2-D jagged array of values
          //--- This is a "transposed" array with columns in the first
          //--- dimension and rows in the second
          string[][] ValuesArr = new string[][] {
               new string[] {"Boston", "Miami", "Merchantville"},
               new string[] {"MA", "FL", "NJ"}
               };

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

          //--- Set the repeat block defined by the bookmark "Block"
          //--- The data source is the 2-D rectangular ValuesArr array
          //--- MaxRows is set to ALL_ROWS, which allows all rows to be imported
          //--- Transpose is true to handle the transposed array
          wt.SetRepeatBlock(ValuesArr, NamesArr, "Block",
               WordTemplate.ALL_ROWS, true);
          wt.Process();
          wt.Save("out.doc");
        
{code} {code:
Code Block
vb.net
|title=
vb.net
titlevb.net
}


          '--- A 2-D jagged array of values
          '--- This is a "transposed" array with columns in the first
          '--- dimension and rows in the second
          Dim ValuesArr()() As String = { _
               New String() {"Boston", "Miami", "Merchantville"}, _
               New String(){"MA", "FL", "NJ"} _
               }

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

          '--- Set the repeat block defined by the bookmark "Block"
          '--- The data source is the 2-D rectangular ValuesArr array
          '--- MaxRows is set to ALL_ROWS, which allows all rows to be imported
          '--- Transpose is true to handle the transposed array
          wt.SetRepeatBlock(ValuesArr, NamesArr, "Block", _
               WordTemplate.ALL_ROWS, True)
          wt.Process()
          wt.Save("out.doc")
        
{code} {example}