Documentation Center

Customizing the HTML in a topic

The HTML you see when you view a topic in a web browser is generated by transforming the XML in your topic or document with a set of XSL stylesheets specifically prepared to be customized.

About this task

These steps describe how to customize the HTML output of a topic. However, a parallel set of steps could be completed to modify the PDF output of a topic as well. If your HTML style changes are based on existing customized XSL styles for the DITA Open Toolkit, refer to Using XSL from the DITA Open Toolkit for instructions on how to load these custom XSL styles into an Content Delivery skin.

Procedure

  1. Content Delivery provides an XSL file specifically for custom modifications to the HTML transform. Create or modify ContentDelivery_home/db/LiveContent/ui/skins/<your skin>/xsl/<your standard>/html_custom.xsl.
  2. Identify the XSL templates you need to override, or the XML node you need to match. The base XSL processing starts in ContentDelivery_home/db/LiveContent/ui/skins/<your skin>/xsl/<your standard>/html.xsl. For the DITA standard, the XSLs in the ContentDelivery_home/db/LiveContent/ui/skins/<your skin>/xsl/DITA/xslhtml/ folder are also used.
  3. Modify ContentDelivery_home/db/LiveContent/ui/skins/<your skin>/xsl/<your standard>/html_custom.xsl.
  4. The Content Delivery XSL customization is based upon the ability to add priority or mode to override templates in the core XSL with customized templates. Add a new <xsl:template> for each template you need to modify. If you are adding a new template with a match attribute, be sure to add a priority attribute with a value of 11 or higher.
    
    <xsl:template match="*[contains(@class, ' topic/image ')]
    /@href" priority="10">
        <!-- include the result of the template here -->
    </xsl:template>
    
  5. Modify your new template to complete the required transform. The following example shows a high priority template that customizes how the href attribute for an image tag is handled. This customization modifies the value of the style attribute, which is produced by the template and appended to the parent HTML element. In this example, an additional margin and a black border are added to all images.
    
    <xsl:template match="*[contains(@class, ' topic/image ')]/@href" priority="10">
        <xsl:variable name="srcfile">
            <xsl:call-template name="strip_path">
                <xsl:with-param name="link" select="."/>
            </xsl:call-template>
        </xsl:variable>
        <xsl:attribute name="src">
            <xsl:value-of select="$rel_app_url"/>media/<xsl:value-of select="$pub.lang"/>
    /<xsl:value-of select="$pub.id"/>/<xsl:value-of select="$srcfile"/>
        </xsl:attribute>
        <xsl:attribute name="style">
            	padding:0px 4px 0px 4px; margin: 2pt; border: 1pt solid black;
        </xsl:attribute>
    </xsl:template>
    
  6. You can customize the HTML wrapper and toolbar that is built around the topic by modifying the template for the DOCUMENT element. In Content Delivery, each individual topic or document XML object loaded into the system is wrapped in a DOCUMENT for consistency within the system.
  7. Upload the new skin customization into the database.
    • You can upload the resources using the web UI, as described by Adding a Skin and Resources.
    • You can also update the skins via the command line using the loaddb tool. Copy the updated skin resources from the source code repository to ContentDelivery_home/db/LiveContent/ui/skins/<your_skin>/.
      • On Windows, to load the most recent changes into the database run this command:

        loaddb.bat UPGRADE

      • On Linux, run this command:

        loaddb.sh UPGRADE