GlossaryDocumentGetBuildingBlock Method

Finds a building block using the specified gallery, category and name.

Namespace:  Aspose.Words.BuildingBlocks
Assembly:  Aspose.Words (in Aspose.Words.dll) Version: 20.3
Syntax
public BuildingBlock GetBuildingBlock(
	BuildingBlockGallery gallery,
	string category,
	string name
)

Parameters

gallery
Type: Aspose.Words.BuildingBlocksBuildingBlockGallery
The gallery criteria.
category
Type: SystemString
The category criteria. Can be null, in which case it will not be used for comparison.
name
Type: SystemString
The building block name criteria.

Return Value

Type: BuildingBlock
The matching building block or null if a match was not found.
Remarks

This is a convenience method that iterates over all building blocks in this collection and returns the first building block that matches the specified gallery, category and name.

Microsoft Word organizes building blocks into galleries. The galleries are predefined using the BuildingBlockGallery enum. Within each gallery, building blocks can be organized into one or more categories. The category name is a string. Each building block has a name. A building block name is not guaranteed to be unique.

Examples
Shows how to use GlossaryDocument and BuildingBlockCollection.
public void GlossaryDocument()
{
    Document doc = new Document();

    GlossaryDocument glossaryDoc = new GlossaryDocument();
    glossaryDoc.AppendChild(new BuildingBlock(glossaryDoc) { Name = "Block 1" });
    glossaryDoc.AppendChild(new BuildingBlock(glossaryDoc) { Name = "Block 2" });
    glossaryDoc.AppendChild(new BuildingBlock(glossaryDoc) { Name = "Block 3" });
    glossaryDoc.AppendChild(new BuildingBlock(glossaryDoc) { Name = "Block 4" });
    glossaryDoc.AppendChild(new BuildingBlock(glossaryDoc) { Name = "Block 5" });

    Assert.AreEqual(5, glossaryDoc.BuildingBlocks.Count);

    doc.GlossaryDocument = glossaryDoc;

    // There is a different ways how to get created building blocks
    Assert.AreEqual("Block 1", glossaryDoc.FirstBuildingBlock.Name);
    Assert.AreEqual("Block 2", glossaryDoc.BuildingBlocks[1].Name);
    Assert.AreEqual("Block 3", glossaryDoc.BuildingBlocks.ToArray()[2].Name);
    Assert.AreEqual("Block 5", glossaryDoc.LastBuildingBlock.Name);

    // Get a block by gallery, category and name
    BuildingBlock block4 =
        glossaryDoc.GetBuildingBlock(BuildingBlockGallery.All, "(Empty Category)", "Block 4");

    // All GUIDs are the same by default
    Assert.AreEqual("00000000-0000-0000-0000-000000000000", block4.Guid.ToString());

    // To be able to uniquely identify blocks by GUID, each GUID must be unique
    // We will do that using a custom visitor
    GlossaryDocVisitor visitor = new GlossaryDocVisitor();
    glossaryDoc.Accept(visitor);

    Assert.AreEqual(5, visitor.GetDictionary().Count);

    Console.WriteLine(visitor.GetText());

    // We can find our new blocks in Microsoft Word via Insert > Quick Parts > Building Blocks Organizer...
    doc.Save(ArtifactsDir + "BuildingBlocks.GlossaryDocument.dotx"); 
}

/// <summary>
/// Simple implementation of giving each building block in a glossary document a unique GUID. Implemented as a Visitor.
/// </summary>
public class GlossaryDocVisitor : DocumentVisitor
{
    public GlossaryDocVisitor()
    {
        mBlocksByGuid = new Dictionary<Guid, BuildingBlock>();
        mBuilder = new StringBuilder();
    }

    public string GetText()
    {
        return mBuilder.ToString();
    }

    public Dictionary<Guid, BuildingBlock> GetDictionary()
    {
        return mBlocksByGuid;
    }

    public override VisitorAction VisitGlossaryDocumentStart(GlossaryDocument glossary)
    {
        mBuilder.AppendLine("Glossary document found!");
        return VisitorAction.Continue;
    }

    public override VisitorAction VisitGlossaryDocumentEnd(GlossaryDocument glossary)
    {
        mBuilder.AppendLine("Reached end of glossary!");
        mBuilder.AppendLine("BuildingBlocks found: " + mBlocksByGuid.Count);
        return VisitorAction.Continue;
    }

    public override VisitorAction VisitBuildingBlockStart(BuildingBlock block)
    {
        block.Guid = Guid.NewGuid();
        mBlocksByGuid.Add(block.Guid, block);
        return VisitorAction.Continue;
    }

    public override VisitorAction VisitBuildingBlockEnd(BuildingBlock block)
    {
        mBuilder.AppendLine("\tVisited block \"" + block.Name + "\"");
        mBuilder.AppendLine("\t Type: " + block.Type);
        mBuilder.AppendLine("\t Gallery: " + block.Gallery);
        mBuilder.AppendLine("\t Behavior: " + block.Behavior);
        mBuilder.AppendLine("\t Description: " + block.Description);

        return VisitorAction.Continue;
    }

    private readonly Dictionary<Guid, BuildingBlock> mBlocksByGuid;
    private readonly StringBuilder mBuilder;
}
See Also