How To Use Third-Party Build Components in DocProject

Introduction

The XML configuration files that are used by Sandcastle's Build Assembler program are available as project items in your DocProjects and DocSites. They are located in the Help\Presentation\Style\Configuration directory. You can edit these files using Visual Studio's XML editor or, as this article will show you how, in the DocProject Properties window or the DocProject External UI.

Build Components

Sandcastle's high level of flexibility can be attributed to its plug-in type architecture, which consists of Build Components and a single program named, BuildAssembler.exe that processes them. As such, Build Components make up a significant portion of Sandcastle's functionality. Adding or configuring Build Components, in what the Sandcastle team refers to as the Build Component Stack, allows end-users to completely customize the HTML topic build process. When used in conjunction with DocProject's extensibility features, developers have full control over the entire build process.

Build Components are registered in Build Assembler's configuration file, which ships with Sandcastle as a file named, sandcastle.config. A different version of this file can be found in each particular presentation style's Configuration directory, although they are mostly the same. Each presentation style has its own implementation of a Build Component Stack to generate HTML topics that have the look and feel of that style; e.g., VS2005, Hana or Prototype.

For more information, see BuildAssembler (EXE) on the Sandcastle blog.

Build Component Stacks

A Build Component Stack is a Sandcastle configuration file that lists Build Components, which build the individual HTML topics. Sandcastle's BuildAssembler.exe program processes each component in the stack once, top-down, for each HTML topic in the build manifest.

When you create a new DocProject or DocSite it will import the selected Sandcastle presentation style into the new project. The sandcastle.config file, containing the presentation's Build Component Stack, will also be imported. However, since DocProject can build both Help 1.x and Help 2.x output, and since the build process for these two types of compiled help usually require different configurations, DocProject will import the sandcastle.config file as two distinct files named, sandcastle.help1x.config and sandcastle.help2x.config, respectively.

Note: You can control the changes that DocProject makes when it imports a sandcastle.config file by configuring the XML elements under the <sandcastleConfigChanges> element in DocProject's configuration file, commonly found at C:\Program Files\Dave Sexton\DocProject\bin\DaveSexton.DocProject.dll.config. (Do not confuse this file with the DocProject.exe.config file.)

Editing a Build Component Stack

The two Sandcastle configuration files, sandcastle.help1x.config and sandcastle.help2x.config, contain the Build Component Stacks that are used by Sandcastle's Build Assembler program to build Help 1.x and Help 2.x output, respectively. You can find them in your DocProject or DocSite by viewing the project in Solution Explorer and browsing to the Help\Presentation\Style\Configuration folder.

The files can be edited in Visual Studio's XML editor. They can also be edited using properties that are exposed in the DocProject Properties window (right-mouse click your project in Solution Explorer and select, DocProject Proprties) or by using DocProject's Build Component Stack editor, which is explained below.

Choosing a Build Component Stack

The first thing to consider before you can edit a stack is which stack you will be editing. Currently, there are four types of build stacks that you can choose from when using any of the built-in Sandcastle presentation styles. The four stacks appear in the DocProject Properties window under the Configuration category:
  • Help 1.x build component stack: Provides the stack that builds reference (API) topics for compiled Help 1.x.
  • Help 2.x build component stack: Provides the stack that builds reference (API) topics for compiled Help 2.x.
  • Help 1.x conceptual build component stack: Provides the stack that builds conceptual topics for compiled Help 1.x.
  • Help 2.x conceptual build component stack: Provides the stack that builds conceptual topics for compiled Help 2.x.

Configuring Build Components

The components in the four Bulid Component Stacks that appear in the DocProject Properties window can be edited in a few different ways:
  • Clicking the ellipses (...) button on any of the stacks will open the Build Component Stack editor for that particular stack.
  • Expanding stacks, by double-clicking the row or using the preceding plus (+) signs, will load the configuration file and display each individual component as a dynamic sub property.
    • The list is filtered, by default, to only show components that have an associated editor. To show all components set the Show entire build component stack option to True (this option precedes the stacks in the DocProject Properties window).
  • To edit individual components simply click the ellipses (...) button. If a DocProject-compatible editor is associated with the component then it will be displayed; otherwise, the XML configuration file will be opened in Visual Studio and the component's definition will be selected automatically.
  • If a component provides sub properties then it will be preceded by a plus (+) sign, allowing you to expand it. Sub properties can either be simple types that can be edited in-line or they can provide their own modal dialog editors, drop-down editors and more sub properties if needed.
Component Names and Descriptions
The descriptions for individual components in the DocProject Properties window are taken from the XML comments that immediately precede their declaration in the configuration file. However, if a component has an associated System.ComponentModel.DescriptionAttribute then that will be used instead. The same goes for the component's name, which component vendors can set by attaching the System.ComponentModel.DisplayNameAttribute to their components; otherwise, without that attribute, the simple type name of the component as it appears in the configuration file is used for display purposes.

Adding Build Components

The same procedure can be used to add build components from both Sandcastle's build component library and third-party component libraries:
  1. Open the DocProject Properties window for your DocProject or DocSite.
    1. Right-mouse click your project in Solution Explorer and select, DocProject Properties from the context menu.
    2. If you prefer you can use the Tools > Options > DocProject > Active Projects page or the DocProject External UI (the latter being the only supported option for Express users).
  2. Click the ellipses button (...) at the far-right side of one of the build component stacks to open the editor dialog (see Choosing a Build Component Stack above).
    1. Note: You do not need to expand the stack to see the ellipses button.
  3. Click the New Build Component button to open the Add Build Components dialog.
Add Build Components Dialog
The Available list contains all of the built-in Sandcastle build components. From this list you can choose the components that you want to add one at a time, by double-clicking each individual row. You can also select more than one, right-mouse and click Select in the context menu.

When you select components from the Available list they will appear in the Selected grid below. When you are finished selecting components, press OK and an editor dialog will be shown for the last component that you selected (or the only component if you only selected one).

The Default Component Editor
The default editor allows you to configure the raw XML configuration and a description of the component as they will appear in the configuration file. The description is saved as an XML comment immediately above the component's definition in the configuration file.

Adding Third-Party Build Components

Continuing with the instructions from Adding Build Components above, you should still have the Add Build Components dialog open. To add third-party components:
  1. Click the Browse... button and locate the managed assembly (.exe or .dll) that contains the build component(s) that you want to add. Press Open on the Browse dialog to load the components into the Available grid.
  2. You can find the third-party components that are defined in the assembly that you just added, if there are any, by scrolling to the bottom of the Available grid.
  3. Select the components that you want to include in the stack (see Adding Build Components above for help).
  4. When you are finished choosing components, press OK on the Add Build Components dialog. The components will be appended to the end of the Build Component Stack and an editor dialog will be shown for the last component that you selected (or the only component if you only selected one).
    1. In the component's editor dialog, add a description that will appear as an XML comment immediately above the component's definition in the configuration file.
    2. If the component vendor has provided a default XML configuration, enter it in the second text box.
      1. The root <component> element is required even if it's empty.
      2. The type and assembly attributes on the <component> element are ignored if they are specified.
    3. Press OK on the editor dialog to commit the changes to the component.
    4. Note: If the component's vendor has provided an editor that is compatible with DocProject, then clicking the ellipses button (...) next to the component will show the vendor's dialog.
  5. Use the up and down arrows to move the new components to the proper location.
    1. Note: This step is very important. You must consult the component vendor's documentation to find out where your component should be located in the Build Component Stack. Placement is usually expressed as being relative to one of the built-in Sandcastle components, such as before SaveComponent or before ResolveReferenceLinksComponent2, for example.
  6. Click OK on the Build Component Stack editor dialog to commit the changes.
Third party components will appear as sub properties of stacks when they are expanded in the DocProject Properties window. If a component provides a DocProject-compatible editor then the ellipses (...) button will invoke the editor. Similarly, if the component supports configurable properties then they will appear under the component when it's expanded in the DocProject Properties window.

Component vendors can use the Sandcastle Build Component Template 1.0 to easily create Sandcastle Build Components that take advantage of DocProject configuration features such as modal dialog and drop-down editors and configurable sub properties. Components based on this template will also work out-of-the-box in the Sandcastle Help File Builder. They'll also work without using automation tools, but without a graphical editor as well.

Last edited Feb 18, 2008 at 1:26 PM by davedev, version 3

Comments

davedev Mar 6, 2008 at 8:17 AM 
The icon changed in 1.10.0 to a green plus sign. (Previously, the "blob" was actually a gear with a star - indicating that a new component would be added.)

DDeWitt Mar 5, 2008 at 12:25 AM 
Ah, I find the add button for my DocProject it is cleverly disguised as a blob.
And I have browsed to the downloaded components and added them to the DocProject editor.
I'll see how much further I get.

Details, details, details...
Thanks