Click or drag to resize
Sandcastle Help File BuilderCreating a Presentation Style Component

Sandcastle comes with some standard presentation styles used to apply formatting and layout to each generated topic. Rather than make changes directly to the Sandcastle presentation styles, you can clone them to create modified versions for yourself. In addition, you can create entirely new presentation styles. The help file builder supports custom presentation styles and will make them available via the Presentation Style property. This topic will walk you through the creation of a presentation style project.

Creating the Project

This section describes how to create and configure the presentation style project. It will describe the process for a C# project but the steps should be fairly similar for a VB.NET project with a few differences in the configuration option titles.

Create the Presentation Style Project

  1. In Visual Studio, select the New Project option. In the New Project dialog box, select the C# or VB.NET language, and then select the Documentation subcategory. Select the Sandcastle Presentation Style Component template, give it a name and click OK to create it. Once it has been created, right click on the project and select Properties.

  2. In the Application tab, set the assembly name and default namespace as you see fit.

  3. On the Debug tab, set the Start Action to "Start external program" and enter the path to the SandcastleBuilderGUI.exe program. If you installed the help file builder in the default location, this will be %ProgramFiles(x86)%\EWSoftware\Sandcastle Help File Builder\. If not, substitute your path as appropriate.

    Tip Tip

    Using the standalone GUI as the host is easier than using Visual Studio as the package locks the assemblies once the help file builder project has loaded them for use and you will not be able to rebuild them. Shutting down the standalone GUI frees the assemblies so that you can rebuild them and start a new debugging session.

    In the help file builder project that you use to test your presentation style, set the project's Component Path property to the folder containing your presentation style's assembly. If you have opened the project's Help File property page before setting the component path, you may need to close and reopen the project in order for it to discover your presentation style assembly.

  4. Optionally, select the Signing tab and check the "Sign the assembly" checkbox. Select "<New...>" from the "Choose a strong name key file" dropdown, enter a filename, and click OK to create the key file. You can protect the key file with a password if you like or uncheck the option to create one without a password.

The Presentation Style Template Class

You are now ready to edit the presentation style class itself. See the comments in the template class for information on how to get started. Some general information is given below. Note that multiple presentation styles can reside within the same assembly. Add new class files to the project and implement the necessary methods as described below and as shown in the template class. You should separate each presentation style out into its own subfolder and use the BasePath property to tell the presentation style where it can find its files.

The presentation style is derived from the Sandcastle.Core.PresentationStyle.PresentationStyleSettings class and consists of several properties that you must set to define the content used by it. These are described below. Review the code for "TODO:" comments to find sections that need attention such as setting the presentation style's ID, defining the content, etc. If you followed the steps in the Creating the Project section, you can run the project and debug it by setting breakpoints in the presentation style's code. As noted above, set the test project's Component Path property to the folder containing the presentation style assembly first. If necessary, close and reopen the test project so that it can discover the presentation style.

The Export Attribute Metadata

The presentation style is a Managed Extensibility Framework (MEF) component. The Sandcastle.Core.PresentationStyle.PresentationStyleExportAttribute is used to define the necessary metadata that enables the help file builder to load and use the component.

Id

The Id parameter is required and is used to uniquely identify the presentation style.

Title

The Title parameter is required and is used to provide a friendly name that can be used in development tools rather than the ID.

Version

The Version property is optional and allows you to define the presentation style version displayed in the help file builder property page when the presentation style is selected.

Copyright

The Copyright property is optional and allows you to define the presentation style copyright displayed in the help file builder property page when the presentation style is selected.

Description

The Description property is optional and allows you to define the presentation style description displayed in the help file builder property page when the presentation style is selected.

IsDeprecated

The IsDeprecated property is optional and allows you to specify whether or not the presentation style has been deprecated. If true, the property page will sort the deprecated style to the end of the list of available presentation styles. Deprecated presentation styles are include for backward compatibility but may not receive any future updates or fixes.

The Presentation Style Class

The derived class consists of one property and a constructor that you must implement. The properties in the base class are used to define the content and its locations.

Location

The Location property is used to provide the location of the presentation style component. This is used as the root path to which all other base and content path values are relative. The default implementation in the template project returns the path of the executing assembly which is typically sufficient.

Constructor

Use the constructor to initialize all of the other properties. The template class contains examples for all of the properties and mimics the settings for the existing VS2010 and VS2013 presentation styles.

BasePath

This property defines the base path of the presentation style files relative to the assembly's location. If your assembly will reside in the same folder as the presentation style content, you can remove this property setting. If adding multiple presentation styles to the assembly, set this to the name of the subfolder that contains the presentation style content folders. All file and folder path values support environment variables which will be expanded at runtime. Other relative paths within a presentation style are considered to be relative to the presentation style's base path.

SupportedFormats

This defines the help file formats supported by the presentation style. The HelpFileFormats values are:

  • HtmlHelp1 - HTML Help 1 (.chm)

  • MSHelp2 - MS Help 2 (.HxS)

  • MSHelpViewer - MS Help Viewer (.mshc)

  • OpenXml - Open XML document (.docx)

  • Website - Website output

If a presentation style does not support a particular help format, it can be omitted.

SupportsNamespaceGrouping

Set this property to true if the presentation style supports namespace grouping. When enabled, it indicates that namespaces with a common root will be grouped in the table of contents.

SupportsCodeSnippetGrouping

Set this property to true if the presentation style supports code snippet grouping. When enabled, it indicates that the Syntax Component can group and sort the code snippets based on the selected syntax filters in the project. It is expected that the presentation style will then render these groups as tabbed sections or something similar in the topics in which they appear along with the supporting script to switch between them to see the code snippets.

ResourceItemsPath

This defines the path to the shared content resource items. These files contain the localizable elements such as messages, section titles, language element names, etc. The files in the indicated folder will be passed as parameters to the content resolution components used by the BuildAssembler tool.

ToolResourceItemsPath

This defines the path to the tool-specific shared content resource items. These are used to override the default resource items from the presentation style in order to do such things as insert project properties into the values using tag substitution. Files in the tool-specific resource items folder are expected to be named using the language they represent plus a .xml extension (en-US.xml for example).

DocumentModelTransformation

This defines the document model XSL transformation to use on the reflection data to prepare it for use with BuildAssembler in order to generate topics. The first parameter specifies the path to the XSL transformation.

The document model XSL transformation typically has parameters that can be passed to it to modify how it works. You can define these parameters with appropriate defaults or substitution tags that will be filled in at build time using the optional second constructor parameter. The parameters are in the form of a dictionary containing key/value pairs.

IntermediateTocTransformation

This defines the XSL transformation to use on the reflection data to generate the intermediate table of contents XML file used by help formats that require a table of contents. As above, parameters can be specified if necessary to define any parameters required by the transformation file.

ConceptualBuildConfiguration

This defines the BuildAssembler configuration file to use for conceptual content builds.

ReferenceBuildConfiguration

This defines the BuildAssembler configuration file to use for reference content (API) builds.

ContentFiles

This collection property is used to define the content from the presentation style that should be embedded in the compiled help file such as images, style sheets, and scripts. Add one or more ContentFiles instances that define the content files that should be copied and their destination in the compiled help file. The help file format parameter defines which format types the content applies to. Typically, this is the same as the SupportedFormats property. However, it is possible to have format-specific content such as for websites only as shown in the template class. The source parameter defines the source location relative to the presentation style base path. The optional destination parameter, if specified, defines the relative location of the files in the compiled help file. If omitted, the files are copied to a like-named folder relative to the root of the compiled help file. If the destination parameter is set to an empty string, the files are copied to the root of the compiled help file. Unlike all other path values, the destination value must always be a relative path.

Note Note

UNIX based web servers may be case-sensitive with regard to folder and filenames so match the case of the folder and filenames in the elements to their actual casing on the file system.

TransformComponentArguments

The XSL transformations used by BuildAssembler's TransformComponent typically have a set of parameters that can be used to alter aspects of their processing such as inserting a logo image into the topic headers. This property can be used by third-party build tools such as the Sandcastle Help File Builder to modify them for the build. It is up to the build tool to insert the modified values into the appropriate configuration file at build time.

Add one or more TransformComponentArgument instances to define the parameters. Each one has the following properties, most of which can be set in the constructor.

  • Key - This property defines the argument key name.

  • IsForConceptualBuild - This property specifies whether or not to include the parameter in the conceptual build.

  • IsForReferenceBuild - This property specifies whether or not to include the parameter in the reference (API) build.

  • Description - This property provides a description of the parameter that can be displayed by build tools. It can be used to provide usage notes, information on the set of valid values, and information about what happens if a value is not specified.

  • Value or Content- These properties are optional. The Value property allows you to specify a simple value to use for the default. If present, the Content property value is ignored. If a Value is not set, it is assumed that the Content value will serve as the value. The Content property allows for complex values such as XML to be used (i.e. the syntax filter language definitions). To restrict the argument to a simple value with no specific default value, set the Value property to an empty string or leave both properties set to null.

PlugInDependencies

This collection property is used to define one or more plug-in IDs on which the presentation style depends. It can be omitted if the presentation style has no plug-in dependencies. If the identified plug-ins are not present in the project when built, they will be added automatically to ensure that the build succeeds. If already present in the project (the user has added them to override their default configurations), the project instances will be used instead.

See Also