TX Text Control provides a powerful API to access elements such as merge fields of a MS Word Office Open XML DOCX document. The ApplicationField class represents a merge field in a document. This article shows how to get the section, paragraph, and SubTextPart number of a merge field in a document.

Unlike HeadersFooters or TextFrames, which have their own collection for ApplicationFields, elements such as SubTextParts, Paragraphs, and Sections do not. There are scenarios where it is necessary to get all the fields within a particular element, such as a section.

Character Index

The above mentioned elements are constructs around the text and the common element is the character index. They all have a Start property and a Length property, which indicates the position of the element within the document.

Now, to get the section of, say, a particular ApplicationField, we have to loop through the sections and compare the character index to see if the field is within the given range.

private static bool IsFieldInContainer(int fieldStart, int fieldLength, int containerStart, int containerLength)
{
    int fieldEnd = fieldStart + fieldLength;
    int containerEnd = containerStart + containerLength;

    return fieldStart >= containerStart && fieldEnd <= containerEnd;
}

public static int Section(this ApplicationField field, TextControl textControl)
{
    foreach (Section section in textControl.Sections)
    {
        if (IsFieldInContainer(field.Start, field.Length, section.Start, section.Length))
        {
            return section.Number;
        }
    }

    // Return -1 or throw an exception if the ApplicationField does not belong to any Section
    return -1;
}

The IsFieldInContainer function compares the start and end index of the container and the given field and returns true if the field is within the container.

Extension Method

The Section extension method will then loop through the sections and call the IsFieldInContainer method to return the number of the section when it is found.

With this extension method, it is possible to get the section of a field within a document:

int sectionNumber = field.Section(textControl1);

ApplicationFieldExtender Class

The complete ApplicationFieldExtender class, which implements the extension methods for ApplicationFields that handle Sections, Paragraphs, and SubTextParts, can be found here:

using TXTextControl;

public static class ApplicationFieldExtender
{
    private static bool IsFieldInContainer(int fieldStart, int fieldLength, int containerStart, int containerLength)
    {
        int fieldEnd = fieldStart + fieldLength;
        int containerEnd = containerStart + containerLength;

        return fieldStart >= containerStart && fieldEnd <= containerEnd;
    }

    public static int Section(this ApplicationField field, TextControl textControl)
    {
        foreach (Section section in textControl.Sections)
        {
            if (IsFieldInContainer(field.Start, field.Length, section.Start, section.Length))
            {
                return section.Number;
            }
        }

        // Return -1 or throw an exception if the ApplicationField does not belong to any Section
        return -1;
    }

    public static int Paragraph(this ApplicationField field, TextControl textControl)
    {
        foreach (TXTextControl.Paragraph paragraph in textControl.Paragraphs)
        {
            if (IsFieldInContainer(field.Start, field.Length, paragraph.Start, paragraph.Length))
            {
                return paragraph.Number;
            }
        }

        // Return -1 or throw an exception if the ApplicationField does not belong to any Paragraph
        return -1;
    }

    public static int SubTextPart(this ApplicationField field, TextControl textControl)
    {
        foreach (TXTextControl.SubTextPart subTextPart in textControl.SubTextParts)
        {
            if (IsFieldInContainer(field.Start, field.Length, subTextPart.Start, subTextPart.Length))
            {
                return subTextPart.Number;
            }
        }

        // Return -1 or throw an exception if the ApplicationField does not belong to any SubTextPart
        return -1;
    }

}

The following code shows how to call these three extension methods to get the section number, paragraph number, and SubTextPart number for all ApplicationFields:

foreach (ApplicationField field in textControl1.ApplicationFields)
{
    int sectionNumber = field.Section(textControl1);
    int paragraphNumber = field.Paragraph(textControl1);
    int subTextPartNumber = field.SubTextPart(textControl1);
    Debug.WriteLine("Field in Section: " + sectionNumber.ToString());
    Debug.WriteLine("Field in Paragraph: " + paragraphNumber.ToString());
    Debug.WriteLine("Field in SubTextPart: " + subTextPartNumber.ToString());
}

Conclusion

These extension methods make it easier to work with ApplicationFields and their surrounding elements. The Section method can be used to get the section number of a field, the Paragraph method can be used to get the paragraph number of a field, and the SubTextPart method can be used to get the SubTextPart number of a field.