BuildingBlock

BuildingBlock class

Represents a glossary document entry such as a Building Block, AutoText or an AutoCorrect entry.

To learn more, visit the Aspose.Words Document Object Model (DOM) documentation article.

public class BuildingBlock : CompositeNode

Constructors

Name	Description
BuildingBlock(GlossaryDocument)	Initializes a new instance of this class.

Properties

Name	Description
Behavior { get; set; }	Specifies the behavior that shall be applied when the contents of the building block is inserted into the main document.
Category { get; set; }	Specifies the second-level categorization for the building block.
Count { get; }	Gets the number of immediate children of this node.
CustomNodeId { get; set; }	Specifies custom node identifier.
Description { get; set; }	Gets or sets the description associated with this building block.
virtual Document { get; }	Gets the document to which this node belongs.
FirstChild { get; }	Gets the first child of the node.
FirstSection { get; }	Gets the first section in the building block.
Gallery { get; set; }	Specifies the first-level categorization for the building block for the purposes of classification or user interface sorting.
Guid { get; set; }	Gets or sets an identifier (a 128-bit GUID) that uniquely identifies this building block.
HasChildNodes { get; }	Returns `true` if this node has any child nodes.
override IsComposite { get; }	Returns `true` as this node can have child nodes.
LastChild { get; }	Gets the last child of the node.
LastSection { get; }	Gets the last section in the building block.
Name { get; set; }	Gets or sets the name of this building block.
NextSibling { get; }	Gets the node immediately following this node.
override NodeType { get; }	Returns the BuildingBlock value.
ParentNode { get; }	Gets the immediate parent of this node.
PreviousSibling { get; }	Gets the node immediately preceding this node.
Range { get; }	Returns a `Range` object that represents the portion of a document that is contained in this node.
Sections { get; }	Returns a collection that represents all sections in the building block.
Type { get; set; }	Specifies the building block type.

Methods

Name	Description
override Accept(DocumentVisitor)	Accepts a visitor.
override AcceptEnd(DocumentVisitor)	Accepts a visitor for visiting the end of the BuildingBlock.
override AcceptStart(DocumentVisitor)	Accepts a visitor for visiting the start of the BuildingBlock.
AppendChild<T>(T)	Adds the specified node to the end of the list of child nodes for this node.
Clone(bool)	Creates a duplicate of the node.
CreateNavigator()	Creates navigator which can be used to traverse and read nodes.
GetAncestor(NodeType)	Gets the first ancestor of the specified `NodeType`.
GetAncestor(Type)	Gets the first ancestor of the specified object type.
GetChild(NodeType, int, bool)	Returns an Nth child node that matches the specified type.
GetChildNodes(NodeType, bool)	Returns a live collection of child nodes that match the specified type.
GetEnumerator()	Provides support for the for each style iteration over the child nodes of this node.
override GetText()	Gets the text of this node and of all its children.
IndexOf(Node)	Returns the index of the specified child node in the child node array.
InsertAfter<T>(T, Node)	Inserts the specified node immediately after the specified reference node.
InsertBefore<T>(T, Node)	Inserts the specified node immediately before the specified reference node.
NextPreOrder(Node)	Gets next node according to the pre-order tree traversal algorithm.
PrependChild<T>(T)	Adds the specified node to the beginning of the list of child nodes for this node.
PreviousPreOrder(Node)	Gets the previous node according to the pre-order tree traversal algorithm.
Remove()	Removes itself from the parent.
RemoveAllChildren()	Removes all the child nodes of the current node.
RemoveChild<T>(T)	Removes the specified child node.
RemoveSmartTags()	Removes all `SmartTag` descendant nodes of the current node.
SelectNodes(string)	Selects a list of nodes matching the XPath expression.
SelectSingleNode(string)	Selects the first `Node` that matches the XPath expression.
ToString(SaveFormat)	Exports the content of the node into a string in the specified format.
ToString(SaveOptions)	Exports the content of the node into a string using the specified save options.

Remarks

BuildingBlock can contain only Section nodes.

BuildingBlock can only be a child of GlossaryDocument.

You can create new building blocks and insert them into a glossary document. You can modify or delete existing building blocks. You can copy or move building blocks between documents. You can insert content of a building block into a document.

Corresponds to the docPart, docPartPr and docPartBody elements in OOXML.

Examples

Shows how to add a custom building block to a document.

public void CreateAndInsert()
{
    // A document's glossary document stores building blocks.
    Document doc = new Document();
    GlossaryDocument glossaryDoc = new GlossaryDocument();
    doc.GlossaryDocument = glossaryDoc;

    // Create a building block, name it, and then add it to the glossary document.
    BuildingBlock block = new BuildingBlock(glossaryDoc)
    {
        Name = "Custom Block"
    };

    glossaryDoc.AppendChild(block);

    // All new building block GUIDs have the same zero value by default, and we can give them a new unique value.
    Assert.That(block.Guid.ToString(), Is.EqualTo("00000000-0000-0000-0000-000000000000"));

    block.Guid = Guid.NewGuid();

    // The following properties categorize building blocks
    // in the menu we can access in Microsoft Word via "Insert" -> "Quick Parts" -> "Building Blocks Organizer".
    Assert.That(block.Category, Is.EqualTo("(Empty Category)"));
    Assert.That(block.Type, Is.EqualTo(BuildingBlockType.None));
    Assert.That(block.Gallery, Is.EqualTo(BuildingBlockGallery.All));
    Assert.That(block.Behavior, Is.EqualTo(BuildingBlockBehavior.Content));

    // Before we can add this building block to our document, we will need to give it some contents,
    // which we will do using a document visitor. This visitor will also set a category, gallery, and behavior.
    BuildingBlockVisitor visitor = new BuildingBlockVisitor(glossaryDoc);
    // Visit start/end of the BuildingBlock.
    block.Accept(visitor);

    // We can access the block that we just made from the glossary document.
    BuildingBlock customBlock = glossaryDoc.GetBuildingBlock(BuildingBlockGallery.QuickParts,
        "My custom building blocks", "Custom Block");

    // The block itself is a section that contains the text.
    Assert.That(customBlock.FirstSection.Body.FirstParagraph.GetText(), Is.EqualTo($"Text inside {customBlock.Name}\f"));
    Assert.That(customBlock.LastSection, Is.EqualTo(customBlock.FirstSection));
    // Now, we can insert it into the document as a new section.
    doc.AppendChild(doc.ImportNode(customBlock.FirstSection, true));

    // We can also find it in Microsoft Word's Building Blocks Organizer and place it manually.
    doc.Save(ArtifactsDir + "BuildingBlocks.CreateAndInsert.dotx");
}

/// <summary>
/// Sets up a visited building block to be inserted into the document as a quick part and adds text to its contents.
/// </summary>
public class BuildingBlockVisitor : DocumentVisitor
{
    public BuildingBlockVisitor(GlossaryDocument ownerGlossaryDoc)
    {
        mBuilder = new StringBuilder();
        mGlossaryDoc = ownerGlossaryDoc;
    }

    public override VisitorAction VisitBuildingBlockStart(BuildingBlock block)
    {
        // Configure the building block as a quick part, and add properties used by Building Blocks Organizer.
        block.Behavior = BuildingBlockBehavior.Paragraph;
        block.Category = "My custom building blocks";
        block.Description =
            "Using this block in the Quick Parts section of word will place its contents at the cursor.";
        block.Gallery = BuildingBlockGallery.QuickParts;

        // Add a section with text.
        // Inserting the block into the document will append this section with its child nodes at the location.
        Section section = new Section(mGlossaryDoc);
        block.AppendChild(section);
        block.FirstSection.EnsureMinimum();

        Run run = new Run(mGlossaryDoc, "Text inside " + block.Name);
        block.FirstSection.Body.FirstParagraph.AppendChild(run);

        return VisitorAction.Continue;
    }

    public override VisitorAction VisitBuildingBlockEnd(BuildingBlock block)
    {
        mBuilder.Append("Visited " + block.Name + "\r\n");
        return VisitorAction.Continue;
    }

    private readonly StringBuilder mBuilder;
    private readonly GlossaryDocument mGlossaryDoc;
}