Building Blocks

Building Blocks

This guide shows how to read and modify the reusable content building blocks stored in a document’s glossary document with Aspose.Words FOSS for .NET. The library exposes AutoText entries, cover pages, headers, footers, and similar predefined content through Document.GlossaryDocument and the BuildingBlock/BuildingBlockCollection object model.

The Glossary Document

Every Document carries a GlossaryDocument — accessible via Document.GlossaryDocument — which is itself a DocumentBase subclass holding the building blocks. Its BuildingBlocks property returns a BuildingBlockCollection, with FirstBuildingBlock/LastBuildingBlock giving quick access to the ends of the list. Look up a specific building block with GetBuildingBlock(gallery, category, name), matching its BuildingBlockGallery, category string, and name together.

Building Block Structure

BuildingBlock is a CompositeNode, so it holds its own content tree — Sections (a SectionCollection), FirstSection, and LastSection — the same way a Document holds sections. Its metadata properties identify and classify it: Name, Guid, Description, Category, Gallery (a BuildingBlockGallery — AutoText, CoverPage, Headers, Footers, Tables, Watermarks, and dozens more predefined galleries), Type (a BuildingBlockType), and Behavior (a BuildingBlockBehavior of Content, Paragraph, or Page) controlling how its contents merge into a document when inserted.

Managing the Building Block Collection

BuildingBlockCollection supports full collection editing: Add(node), Insert(index, node), Remove(node), RemoveAt(index), Clear(), Contains(node), and IndexOf(node), alongside ToArray() and GetEnumerator() for reading. Because it’s a NodeCollection, building blocks can be constructed, cloned, and moved using the same node APIs as any other part of the document tree.

Placeholder Text Building Blocks

Structured document tags can reference a building block as their placeholder content: StructuredDocumentTag.Placeholder and StructuredDocumentTagRangeStart.Placeholder both return the BuildingBlock shown when the tag is empty, via the shared IStructuredDocumentTag.Placeholder property.

Tips and Best Practices

• Match GetBuildingBlock(gallery, category, name)’s three arguments carefully — the same name can exist in different galleries or categories.
• Use BuildingBlockGallery to filter which kind of reusable content you’re looking for (AutoText, CoverPage, Tables, Watermarks, etc.) rather than scanning every building block by name alone.
• BuildingBlockBehavior determines how inserted content merges with the surrounding document (Content, Paragraph, or Page) — check it before assuming a building block will insert the way you expect.
• Since BuildingBlock is a CompositeNode, treat it like any other node subtree when building or editing its contents — AppendChild, InsertAfter, and similar node methods all apply.

Common Issues

FAQ

Where are building blocks stored in a document?

In the document’s GlossaryDocument, accessible via Document.GlossaryDocument, whose BuildingBlocks property is a BuildingBlockCollection.

How do I find a specific building block, like an AutoText entry?

Call GlossaryDocument.GetBuildingBlock(gallery, category, name) with the matching BuildingBlockGallery, category, and name.

Can I add new building blocks programmatically?

Yes — BuildingBlockCollection supports Add(node) and Insert(index, node) since it’s a NodeCollection.

What does BuildingBlockBehavior control?

How the building block’s content merges into the document when it’s inserted — as Content, a whole Paragraph, or a whole Page.

How is a building block related to a structured document tag’s placeholder text?

StructuredDocumentTag.Placeholder (and StructuredDocumentTagRangeStart.Placeholder) return the BuildingBlock that supplies an SDT’s placeholder content when it’s empty.

API Reference Summary

See Also

• Aspose.Words for .NET — Enterprise Documentation