The Post-Transform Component is used to provide the following additional features to modify the transformed HTML for a help topic:

  • It can insert a logo image at the top of each help topic to the left, right, or above the topic title.
  • It acts as a companion component to the Code Block Component to add the supporting links for the colorizer script and stylesheet only when required.
  • For the Prototype style, it hides the language combo box if only one language appears in the Syntax section.
  • It acts as a companion component to the Version Information Component to add version information to the help topics if used with the help file builder. If used outside the help file builder, a shared content file containing the necessary overrides is needed or a modification is required to the Sandcastle reference content files (see below).

Example Configuration

The following is the default configuration for the post-transform component. All attribute names and values are case-sensitive. It should be inserted into the configuration file right after the TransformComponent. This component can be used by itself if you do not want to use the code block and/or version information components. However, this component is required and must be used if you do use the code block and/or version information components.

If the version information component is used, this component will insert the version information found into the help topic. For the code block component, it adds the script and stylesheet links to the document's <head> section. While they could both be inserted into the first code element by the code block component and would work, the link for the stylesheet is only considered valid HTML if it appears in the <head> section. By using this component to insert it, it keeps the HTML well formed and valid. Since it is inserting the stylesheet link, I placed the code to insert the script element in here as well.

CopyExample Configuration
<!-- Post-transform component configuration.  This must appear after the
     TransformComponent.  See also: CodeBlockComponent. -->
<component type="SandcastleBuilder.Components.PostTransformComponent"
  assembly="{@SHFBFolder}SandcastleBuilder.Components.dll"
  id="Post-transform Component">
    <!-- Code colorizer files (required).
         Attributes:
            Stylesheet file (required)
            Script file (required)
            "Copy" image file (required) -->
    <colorizer stylesheet="{@SHFBFolder}Colorizer\highlight.css"
        scriptFile="{@SHFBFolder}Colorizer\highlight.js"
        copyImage="{@SHFBFolder}Colorizer\CopyCode.gif" />

    <!-- Base output paths for the files (required).  These should
         match the parent folder of the output path of the HTML files
         (see each of the SaveComponent instances below). -->
    <outputPaths>
      <path value="Output\HtmlHelp1\" />
      <path value="Output\MSHelp2\" />
      <path value="Output\MSHelpViewer\" />
      <path value="Output\Website\" />
    </outputPaths>

    <!-- Logo image file (optional).  Filename is required. The height,
         width, altText, placement, and alignment attributes are
         optional. -->
    <logoFile filename="" height="0" width="0" altText=""
        placement="left" alignment="left" />
</component>

The example given above is taken from the Sandcastle Help File Builder's configuration file. When used with it, you may specify the replacement tag {@SHFBFolder} to insert the help file builder's folder in the file path. This is replaced at build time with the appropriate value. This replacement tag can also be specified in the configuration dialog when configuring project-specific configurations for the component from within the help file builder. The same applies to the {@ProjectFolder} replacement tag which can be used in the logo image's filename attribute to insert a reference to the project folder. If using the component in your own build scripts, replace the tags with an actual absolute or relative path. If a relative file path is specified, it will be relative to the current working folder at build time.

The colorizer element defines the files used by the code colorizer script. The stylesheet attribute defines the stylesheet to use for the colorized code. The scriptFile attribute defines the script file containing the JavaScript code used to show and hide the collapsible sections and copy the code to the clipboard (Internet Explorer only). The copyImage attribute defines the image file to use for the "Copy Code" link. The supplied highlight.css, highlight.js, and CopyCode.gif files are used by default. A copy of the image file with an "_h" suffix should also exist if you would like to see a different image when the mouse hovers over the link (i.e. CopyCode_h.gif). If it does not exist, the same image is used for both. You can edit the stylesheet to use different colors for the highlighted code elements. If using the help file builder, you can also add a new stylesheet using the same name to an html\ folder in the project. The project's copy will overwrite the default stylesheet. The same applies to the image files. However, their location is determined by the copyImageUrl attribute in the code block component's configuration.

The outputPaths element is used to specify where the stylesheet and script files are to be copied. One or more child path elements must be specified that match the parent folder of the paths used in the SaveComponent instances that save the help topic HTML files. The help file builder supports output of multiple formats in a single build. As such, there is one child element for each of the different help file formats. The image files are copied to the location specified in the CodeBlockComponent configuration which is relative to these paths. See its description for details. The script is copied to the scripts\ folder and the stylesheet is copied to the styles\ folder under these paths.

The logoFile element is optional. Using it, you can add a logo image to the header of each help topic page that will appear to the left, right, or above the topic title. If no image file is specified or the element is omitted, no image will appear in the header. The height and width attributes can be used to specify the height and width of the image. If omitted or set to zero, the image will be displayed using its actual size. By using these attributes, you can scale a larger image down or scale a smaller image up to get a better fit. The configuration dialog for the component allows you to select an image and adjust its size with a preview area. The altText attribute lets you specify some alternate text that can appear for the image. The placement attribute allows you to specify where the image is placed (to the left, to the right, or above the topic title). When set to above, the alignment attribute specifies how the image is aligned (left, right, or centered).

Version Information

As noted, the component can insert version information into the topic when used with the VersionInformationComponent. If not used, no version information will be listed. The help file builder contains the necessary modifications to its shared content files to add version information. If you use this component in your own scripts or build tools, you will need to include a copy of this shared content file or modify the Sandcastle reference content files in order to add the version parameter. To do so, add the text "Version: {2}" to the locationInformation entry in the reference_content.xml file for the Prototype, VS2005, and Hana styles and the requirementsAssemblyLayout entry in the reference_content.xml file for the VS2005 and Hana styles.

See Also