Page History

{info}
We recommend that you read about [Word file representation in WordApplication] before reading this article.
{info}

h3. How WordApplication insert elements

{excerpt} Each of the elements listed in the document tree structure inherit from the [Element] class, which provides most of the methods for inserting new elements into a document. [WordApplication] will allow you to call any Insert method on almost any type of element, but the behavior of that method will change depending on what type of element the method is called on and what type of element the method is inserting. {excerpt}

For example:
* Inserting a new [Section] automatically inserts a new [Paragraph] and [CharacterRun] within that [Section].
* Inserting a new [Paragraph] automatically inserts a new [CharacterRun] within that [Paragraph].

To further illustrate this point, we will examine calling [InsertTextAfter|Element.InsertTextAfter(String, boolean)] on a [Section]

h3. Example: Calling InsertCharacterRunAfter on a Section

_This example shows the behavior of WordWriter when inserting an element two levels deeper than the current element._

A [CharacterRun] must be the child of a [Paragraph], but [InsertTextAfter|Element.InsertTextAfter(String, boolean)] can be called on a [Section]. In this case, a new [CharacterRun] will be inserted at the end of the last [Paragraph] in the [Section].

{csharp:1}
//--- doc is a Document object
Section sec = doc.Sections[0];
sec.InsertTextAfter("  New text.", true);
{csharp}

{vbnet:1}
'--- doc is a Document object
Dim sec As Section = doc.Sections(0)
sec.InsertTextAfter("  New text.", True)
{vbnet}

To achieve the most predictable behavior, it is recommended practice to call a Create or Insert method on an object appropriate to what is being inserted.

So, for example, instead of calling [InsertTextAfter|Element.InsertTextAfter(String, boolean)] on a [Section] object as described above, it should be called on a [Paragraph], [ListEntry], or [field] contents.

{csharp:2}
//--- doc is a Document object
Section sec = doc.Sections[0];
Element[] paragraphs = sec.get_Elements(Element.Type.Paragraph);
Paragraph lastParagraph = (Paragraph)paragraphs[paragraphs.Length - 1];
lastParagraph.InsertTextAfter("  New text.", true);
{csharp}

{vbnet:2}
'--- doc is a Document object
Dim sec As Section = doc.Sections(0)
Dim paragraphs As Element[] = sec.Elements(Element.Type.Paragraph)
Dim lastParagraph = CType(paragraphs(paragraphs.Length - 1), Paragraph)
lastParagraph.InsertTextAfter("  New text.", True)
{vbnet}

Here is an example Word document before running either of the code samples above:

!StartingDoc.png|border=1,width=700!

Here is the output from the example after running either of the code samples:

!OutputDoc.png|border=1,width=700!


h3. List of Insert Behaviors

The following table lists some common examples of how WordWriter behaves when a Create or Insert method is called on different elements.

Each column represents the following:

* *Parent element:* *Element* on which {{{*}InsertXBefore{*}}} or {{{*}InsertXAfter{*}}} is called.
* *Element to be inserted:* Type of element which is being inserted. Use the appropriate {{{*}InsertXBefore{*}}} or {{{*}InsertXAfter{*}}} for this type.
* *InsertXBefore Behavior:* What the {{{*}InsertXBefore{*}}} method does in this case.
* *InsertXAfter Behavior:* What the {{{*}InsertXAfter{*}}} method does in this case.

Notes:

* To insert a [Section], use [CreateSectionBefore|Element.CreateSectionBefore()] or [CreateSectionAfter|Element.CreateSectionAfter()].
* To insert a [CharacterRun], use [InsertTextBefore|Element.InsertTextBefore(String, Boolean)] or [InsertTextAfter|Element.InsertTextAfter(String, boolean)].

|| Parent element || Element to be inserted || InsertXBefore Behavior || InsertXAfter Behavior ||
| [Document] | [Section] | New [Section] is inserted before existing [Section]s. | New [Section] is inserted after existing [Section]s. |
| [Document] | [Paragraph], [List], or [Table] | Element is inserted in the first [Section] of the [Document] before any existing elements in that [Section]. | Element is inserted in the last [Section] of the [Document] after any existing elements in that [Section]. |
| [Document] | [CharacterRun], [InlineImage], [Hyperlink], or [MergeField] | Element is inserted in the first element ([Paragraph], [List], or [Table]) of the first [Section] of the [Document] before any existing elements in that first element. | Element is inserted in the last element ([Paragraph], [List], or [Table]) of the last [Section] of the [Document] after any existing elements in that last element. |
| [Section] | [Section] | New [Section] is inserted before the current [Section]. | New [Section] is inserted after the current [Section]. |
| [Section] | [CharacterRun], [InlineImage], [Hyperlink], or [MergeField] | Element is inserted in the first element ([Paragraph], [List], or [Table]) of this [Section] before any existing elements in that first element. | Element is inserted in the last element ([Paragraph], [List], or [Table]) of this [Section] after any existing elements in that last element. |
| [List] | [List] | New [List] is inserted before the current [List]. | New [List] is inserted after the current [List]. |
| [List] | [CharacterRun], [InlineImage], [Hyperlink], or [MergeField] | Element is inserted in the first [ListEntry] of the [List] before any existing elements in that [ListEntry]. | Element is inserted in the last [ListEntry] of the [List] after any existing elements in that [ListEntry]. |
| [Table] | [Table] | [Table] is inserted in the first [TableCell] of the current [Table] before any existing elements in that [TableCell]. | There is currently an issue with this behavior. New rows are appended to the current [Table] instead of being added to a new [Table]. |
| [Table] | [Paragraph] | [Paragraph] is inserted in the first [TableCell] of the current [Table] before any existing elements in that [TableCell]. | [Paragraph] is inserted after the [Table]. |
| [Table] | [List] | [List] is inserted before the [Table]. There is currently an issue with this behavior. | The [List] is inserted after the [Table] and appears as a [TableCell]. |
| [Table] | [CharacterRun], [InlineImage], [Hyperlink], or [MergeField] | Element is inserted in the first element ([Paragraph], [List], or [Table]) of the first [TableCell] of the [Table] before any existing elements in that first element. | Element is inserted in the next element ([Paragraph], [List], or [Table]) after the [Table], after any existing elements in that next element. |