Advanced XML Transformations

Programmatic and XSLT transformations can be added to outputs to manipulate content. Programmatic transformations can be written in any .NET language, such as C# or VB.NET. This advanced feature gives you great flexibility, because it allows for post-build modification in virtually any imaginable custom way.

You can use the Transformation Wizard to insert boilerplate content or code into every topic in your targets. See About Transformations.

Example  

Examples of advanced transformations include:

  •  Replacing some text (tag) with variable text depending on a parameter specified in that tag.

  • The Expanding/Collapsing Sections feature in Doc-To-Help. See Creating Expanding/Collapsing Sections.

  1. Select the Home ribbon.
  2. At the bottom of the Target group, click . The Help Targets dialog opens.
  3. In the Advanced section, next to the XML transformation field, click .
  4. Navigate to the file, select it, and click Open.
  5. In the Help Targets dialog, click OK and build your target.

Refer to the notes below, and the two examples provided with Doc-To-Help:

  • The expanding sections functionality (see Creating Expanding/Collapsing Sections) is implemented as an XML transformation (a programmatic one). Its full source code can be found in \\Program Files [or Program Files (x86)]\MadCap Software\DocToHelp\Transforms\BuiltIn\Source\XMLInternal. (Don’t modify these files; they are used in target compilation.)

  • There is an example transformation named timestamp.config that will add timestamp text to each topic of a target. It is located at C:\Program Files (x86)\MadCap Software\MadCap DocToHelp 6\Tranforms\Examples\Timestamp.

Transformations registered in the configuration file are applied to every topic in the order of their appearance in the configuration file.

A configuration file is XML where every transformation is registered with a <transform> element with the following elements inside:

  • <description> Arbitrary string describing the transformation, for explanatory purpose only.

  • <assembly> File name of the transformation assembly (including the .dll extension). For an XSLT transformation that assembly should always be C1D2HXMLInternal.dll. For programmatic transformations, it is a path to the file, not the file name. The path is relative to the configuration file (where transform assembly is specified).

  • <type> Full class name in the assembly that implements the IXMLTransform interface. That is the class whose methods are called to perform the transformation. For an XSLT transformation that element should always be as follows: <type>C1.D2H.XMLTransform.XSLTTransform</type>

  • <params> This element contains whatever elements the transformation may need as its parameters. All specific parameters will be passed to the transformation assembly when it is executed. For programmatic transformations, their interpretation is entirely dependent on the code implementing the transformation methods. XSLT transformations should be contained in one XSLT file that receives parameter values. The path to an XSL file is relative to the configuration file, so only the file name needs to be specified, for example: <xsl-file>C1D2HXMLInternal.xsl</xsl-file>.

A programmatic transformation assembly contains a class implementing the interface C1.D2H.XMLTransform.IXMLTransform. That interface is defined in the C1XHTML.dll assembly residing in the DocToHelp directory. It contains three methods (note that you do not need to implement this interface if you are creating an XSLT transformation; creating XSLT transformations requires programming only in XSLT; no .NET programming is required):

  • void IXMLTransform.ReadParams(XmlNode node)

    This method is called before executing the transformation, to initialize the transformation class with parameter values specified in the <params> tag in the configuration file. This method is called once in Doc-To-Help build, before this transformation is applied to any topics. The 'node' parameter passed to this method contains the XmlDocument whose root element is the <params> element of the configuration file.

  • void IXMLTransform.Execute(XmlDocument doc)

    This method executes the transformation, applies it to a topic. The 'doc' parameter is the topic XML before applying the transformation (all transformations preceding this transformation in the configuration file have already been applied to it. This method implementation modifies the XmlDocument passed to it.

  • void IXMLTransform.CopyRequiredFiles(string targetPath)

    This method is used to copy any files that may be needed in the help target to support this transformation's functionality (these are usually resource files, such as graphics, scripts, style sheets, etc). If you don't need any files, leave this method empty. The 'targetPath' parameter contains the path to the TransformFiles subdirectory of the Help target directory (for example, \MyProject\MyHTMLHelpTarget\TransformFiles). This method implementation copies required files (if any) to that subdirectory (possibly creating subdirectories inside it, if needed).