FieldToa Class
Implements the TOA field.
Inheritance Hierarchy
SystemObject
  Aspose.Words.FieldsField
    Aspose.Words.FieldsFieldToa

Namespace: Aspose.Words.Fields
Assembly: Aspose.Words (in Aspose.Words.dll) Version: 19.11
Syntax
public class FieldToa : Field

The FieldToa type exposes the following members.

Constructors
  NameDescription
Public methodFieldToa
Initializes a new instance of the FieldToa class
Properties
  NameDescription
Public propertyCode exampleBookmarkName
Gets or sets the name of the bookmark that marks the portion of the document used to build the table.
Public propertyCode exampleDisplayResult
Gets the text that represents the displayed field result.
(Inherited from Field.)
Public propertyCode exampleEnd
Gets the node that represents the field end.
(Inherited from Field.)
Public propertyCode exampleEntryCategory
Gets or sets the integral category for entries included in the table.
Public propertyCode exampleEntrySeparator
Gets or sets the character sequence that is used to separate a table of authorities entry and its page number.
Public propertyCode exampleFormat
Gets a FieldFormat object that provides typed access to field's formatting.
(Inherited from Field.)
Public propertyCode exampleIsDirty
Gets or sets whether the current result of the field is no longer correct (stale) due to other modifications made to the document.
(Inherited from Field.)
Public propertyCode exampleIsLocked
Gets or sets whether the field is locked (should not recalculate its result).
(Inherited from Field.)
Public propertyCode exampleLocaleId
Gets or sets the LCID of the field.
(Inherited from Field.)
Public propertyCode examplePageNumberListSeparator
Gets or sets the character sequence that is used to separate two page numbers in a page number list.
Public propertyCode examplePageRangeSeparator
Gets or sets the character sequence that is used to separate the start and end of a page range.
Public propertyCode exampleRemoveEntryFormatting
Gets or sets whether to remove the formatting of the entry text in the document from the entry in the table of authorities.
Public propertyCode exampleResult
Gets or sets text that is between the field separator and field end.
(Inherited from Field.)
Public propertyCode exampleSeparator
Gets the node that represents the field separator. Can be null.
(Inherited from Field.)
Public propertyCode exampleSequenceName
Gets or sets the name of a sequence whose number is included with the page number.
Public propertyCode exampleSequenceSeparator
Gets or sets the character sequence that is used to separate sequence numbers and page numbers.
Public propertyCode exampleStart
Gets the node that represents the start of the field.
(Inherited from Field.)
Public propertyCode exampleType
Gets the Microsoft Word field type.
(Inherited from Field.)
Public propertyCode exampleUseHeading
Gets or sets whether to include the category heading for the entries in a table of authorities.
Public propertyCode exampleUsePassim
Gets or sets whether to replace five or more different page references to the same authority with "passim", which is used to indicate that a word or passage occurs frequently in the work cited.
Methods
  NameDescription
Public methodEquals (Inherited from Object.)
Protected methodFinalize (Inherited from Object.)
Public methodCode exampleGetFieldCode
Returns text between field start and field separator (or field end if there is no separator). Both field code and field result of child fields are included.
(Inherited from Field.)
Public methodCode exampleGetFieldCode(Boolean)
Returns text between field start and field separator (or field end if there is no separator).
(Inherited from Field.)
Public methodGetHashCode (Inherited from Object.)
Public methodGetType (Inherited from Object.)
Protected methodMemberwiseClone (Inherited from Object.)
Protected methodNeedStoreOldResultNodes (Inherited from Field.)
Public methodCode exampleRemove
Removes the field from the document. Returns a node right after the field. If the field's end is the last child of its parent node, returns its parent paragraph. If the field is already removed, returns null.
(Inherited from Field.)
Public methodToString (Inherited from Object.)
Public methodCode exampleUnlink
Performs the field unlink.
(Inherited from Field.)
Public methodCode exampleUpdate
Performs the field update. Throws if the field is being updated already.
(Inherited from Field.)
Public methodCode exampleUpdate(Boolean)
Performs a field update. Throws if the field is being updated already.
(Inherited from Field.)
Remarks
Builds a table of authorities (that is, a list of the references in a legal document, such as references to cases, statutes, and rules, along with the numbers of the pages on which the references appear) using the entries specified by TA fields.
Examples
Shows how to build and customize a table of authorities using TOA and TA fields.
public void FieldTOA()
{
    Document doc = new Document();
    DocumentBuilder builder = new DocumentBuilder(doc);

    // Insert a TOA field, which will list all the TA entries in the document,
    // displaying long citations and page numbers for each
    FieldToa fieldToa = (FieldToa)builder.InsertField(FieldType.FieldTOA, false);

    // Set the entry category for our table
    // For a TA field to be included in this table, it will have to have a matching entry category
    fieldToa.EntryCategory = "1";

    // Moreover, the Table of Authorities category at index 1 is "Cases",
    // which will show up as the title of our table if we set this variable to true
    fieldToa.UseHeading = true;

    // We can further filter TA fields by designating a named bookmark that they have to be inside of
    fieldToa.BookmarkName = "MyBookmark";

    // By default, a dotted line page-wide tab appears between the TA field's citation and its page number
    // We can replace it with any text we put in this attribute, even preserving the tab if we use tab character
    fieldToa.EntrySeparator = " \t p.";

    // If we have multiple TA entries that share the same long citation,
    // all their respective page numbers will show up on one row,
    // and the page numbers separated by a string specified here
    fieldToa.PageNumberListSeparator = " & p. ";

    // To reduce clutter, we can set this to true to get our table to display the word "passim"
    // if there would be 5 or more page numbers in one row
    fieldToa.UsePassim = true;

    // One TA field can refer to a range of pages, and the sequence specified here will be between the start and end page numbers
    fieldToa.PageRangeSeparator = " to ";

    // The format from the TA fields will carry over into our table, and we can stop it from doing so by setting this variable
    fieldToa.RemoveEntryFormatting = true;
    builder.Font.Color = Color.Green;
    builder.Font.Name = "Arial Black";

    Assert.AreEqual(" TOA  \\c 1 \\h \\b MyBookmark \\e \" \t p.\" \\l \" & p. \" \\p \\g \" to \" \\f", fieldToa.GetFieldCode());

    builder.InsertBreak(BreakType.PageBreak);

    // We will insert a TA entry using a document builder
    // This entry is outside the bookmark specified by our table, so it won't be displayed
    FieldTA fieldTA = InsertToaEntry(builder, "1", "Source 1");

    Assert.AreEqual(" TA  \\c 1 \\l \"Source 1\"", fieldTA.GetFieldCode());

    // This entry is inside the bookmark,
    // but the entry category doesn't match that of the table, so it will also be omitted
    builder.StartBookmark("MyBookmark");
    fieldTA = InsertToaEntry(builder, "2", "Source 2");

    // This entry will appear in the table
    fieldTA = InsertToaEntry(builder, "1", "Source 3");

    // Short citations aren't displayed by a TOA table,
    // but they can be used as a shorthand to refer to bulky source names that multiple TA fields reference
    fieldTA.ShortCitation = "S.3";

    Assert.AreEqual(" TA  \\c 1 \\l \"Source 3\" \\s S.3", fieldTA.GetFieldCode());

    // The page number can be made to appear bold and/or italic
    // This will still be displayed if our table is set to ignore formatting
    fieldTA = InsertToaEntry(builder, "1", "Source 2");
    fieldTA.IsBold = true;
    fieldTA.IsItalic = true;

    Assert.AreEqual(" TA  \\c 1 \\l \"Source 2\" \\b \\i", fieldTA.GetFieldCode());

    // We can get TA fields to refer to a range of pages that a bookmark spans across instead of the page that they are on
    // Note that this entry refers to the same source as the one above, so they will share one row in our table,
    // displaying the page number of the entry above as well as the page range of this entry,
    // with the table's page list and page number range separators between page numbers
    fieldTA = InsertToaEntry(builder, "1", "Source 3");
    fieldTA.PageRangeBookmarkName = "MyMultiPageBookmark";

    builder.StartBookmark("MyMultiPageBookmark");
    builder.InsertBreak(BreakType.PageBreak);
    builder.InsertBreak(BreakType.PageBreak);
    builder.InsertBreak(BreakType.PageBreak);
    builder.EndBookmark("MyMultiPageBookmark");

    Assert.AreEqual(" TA  \\c 1 \\l \"Source 3\" \\r MyMultiPageBookmark", fieldTA.GetFieldCode());

    // Having 5 or more TA entries with the same source invokes the "passim" feature of our table, if we enabled it
    for (int i = 0; i < 5; i++)
    {
        InsertToaEntry(builder, "1", "Source 4");
    }

    builder.EndBookmark("MyBookmark");

    doc.UpdateFields();
    doc.Save(ArtifactsDir + "Field.TOA.TA.docx");
}

/// <summary>
/// Get a builder to insert a TA field, specifying its long citation and category,
/// then insert a page break and return the field we created
/// </summary>
private FieldTA InsertToaEntry(DocumentBuilder builder, string entryCategory, string longCitation)
{
    FieldTA field = (FieldTA)builder.InsertField(FieldType.FieldTOAEntry, false);
    field.EntryCategory = entryCategory;
    field.LongCitation = longCitation;

    builder.InsertBreak(BreakType.PageBreak);

    return field;
}
See Also