Transforming Sitecore Docker Containers with XSLT: A Developer’s Guide

Do you still remember Sitecore XSLT rendering? Are you this old? No, don’t expect me in this blog to explain that legacy stuff. But in a nutshell, XSLT renderings were used for transforming XML data into HTML for rendering web pages. Using the same concept, In this blog post, we will explore how XSL Transformations (XSLT) can be used to transform XML documents and modify configuration files such as Solrconfig.xml or any other XMLs in Sitecore Docker containers. Similar to how XDT is used for .config transformations in Docker, XSLT can be used for XML transformation in this context.

What is XSLT?

XSLT is a language used to transform XML documents into other formats such as HTML, text, or another XML format. XSLT is widely used in web development to transform XML data into HTML for rendering web pages. It can also be used to transform XML data into other formats such as text or another XML format. XSLT uses XSL templates to define how to transform an input XML document into an output document. An XSL template consists of a set of rules that define how to match parts of the input document and what to do with them.

Why Use XSLT in Sitecore Docker Containers?

Sitecore Docker containers provide a consistent and isolated environment for developing and testing Sitecore applications. Using Docker containers, you can easily create and manage Sitecore instances and apply custom configurations. XSLT can be used in Sitecore Docker containers for modifying configuration files such as Solrconfig.xml to apply custom settings or configurations.

How to Use XSLT in Sitecore Docker Containers?

Sitecore has built-in support for XSLT transformations, and developers can use XSLT to transform XML data. To use XSLT in Sitecore Docker containers, you need to follow these steps:

1. Create an XSLT stylesheet that contains the required transformations
2. Apply the XSLT stylesheet to the XML document using an XSLT processor

Example: Modifying Solrconfig.xml using XSLT

The Solrconfig.xml file contains various configurations related to the Solr instance such as indexing, searching, and caching. In Sitecore Docker containers, you can modify the Solrconfig.xml file using XSLT to apply custom settings or configurations. Let’s take the example of adding a new custom updateRequestProcessorChain.

1. Create an XSLT stylesheet that contains the required transformations:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output omit-xml-declaration="yes" indent="yes" />
  <xsl:strip-space elements="*" />

  <xsl:template match="node() | @*">
    <xsl:copy>
      <xsl:apply-templates select="node() | @*" />
    </xsl:copy>
  </xsl:template>

  <xsl:template match="//config">
    <xsl:copy>
      <xsl:apply-templates select="@* | *" />
      <updateRequestProcessorChain name="ignore-commit-from-client" default="true">
        <processor class="solr.IgnoreCommitOptimizeUpdateProcessorFactory">
          <int name="statusCode">200</int>
        </processor>
        <processor class="solr.LogUpdateProcessorFactory" />
        <processor class="solr.DistributedUpdateProcessorFactory" />
        <processor class="solr.RunUpdateProcessorFactory" />
      </updateRequestProcessorChain>
    </xsl:copy>
  </xsl:template>

</xsl:stylesheet>

Explanation of the above transformation file:

• The xsl:stylesheet element is used to declare the XSLT version, the namespace for the XSLT elements, and the attributes to be used in the stylesheet.
• The xsl:output element is used to define the output format of the transformation. In this case, the omit-xml-declaration attribute is set to yes to omit the XML declaration from the output, and the indent attribute is set to yes to indent the output.
• The xsl:strip-space element is used to strip whitespace characters from the input document.
• The xsl:template element is used to define templates for matching nodes and attributes in the input document. The first template matches any node or attribute in the input document and creates a copy of it in the output document.
• The second xsl:template element matches the config element in the input document and creates a copy of it in the output document. It then applies templates to any attributes or child nodes of the config element. The match attribute is used to associate a template with an XML element. The match attribute can also be used to define a template for the entire XML document. The value of the match attribute is an XPath expression.
• Within the config template, a new updateRequestProcessorChain element is created and populated with child processor elements that define the processors for the update request chain.

You can test the XSLT transformation with the various tools available online eg. https://linangdata.com/xslt-tester/

2. Copy the XSLT stylesheet to the Sitecore Docker container: Since we are creating a transformation file for solrconfig.xml file under the Solr role, save the above file as solrconfig.xml.xslt under docker\build\solr-init\data\xslt folder. If you don’t have a build folder for solr-init dockerfile, create a folder name solr-init, and under that create dockerfile to build your customized version of a Sitecore runtime image as explained here. Under the solr-init folder, create a data folder and then create xslt folder to hold xslt transformation files. The folder structure will look like this:

3. Create a Dockerfile to build the Solr image and apply the transformation: Here is an example of a Dockerfile that applies the Solrconfig.xslt transformation to Solrconfig.xml:

# escape=`

ARG BASE_IMAGE

FROM ${BASE_IMAGE}

SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]

COPY ./data/xslt/solrconfig.xml.xslt /data/xslt/solrconfig.xml.xslt

4. Build the docker images and up the containers: Build the images (docker-compose build) and up the containers (docker-compose up -d). You may need to clear the Solr data folder (delete all the existing Solr cores/indexes) to apply to new changes.

5. Check the transformations: Once containers are up, Go to the Solr dashboard and check the solrconfig.xml file. It should contain the changes we applied through transformation.

Some more common examples of XSLT transformation:

• Increase the facet.limit in Solrconfig.xml:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output omit-xml-declaration="yes" indent="yes" />
  <xsl:strip-space elements="*" />

  <xsl:template match="node() | @*">
    <xsl:copy>
      <xsl:apply-templates select="node() | @*" />
    </xsl:copy>
  </xsl:template>

  <xsl:template match="//config/requestHandler[@name='/select']/lst">
    <xsl:copy>
      <xsl:copy-of select="@* | node()" />
      <str name="facet.limit">300</str>
    </xsl:copy>
  </xsl:template>

</xsl:stylesheet>

• Insert the new dynamic fields in managed-schema.xml:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output omit-xml-declaration="yes" indent="yes" />
  <xsl:strip-space elements="*" />
  <xsl:param name="uniqueKeyReplacement" select="'_uniqueid'" />

  <xsl:template match="node() | @*">
    <xsl:copy>
      <xsl:apply-templates select="node() | @*" />
    </xsl:copy>
  </xsl:template>

  <xsl:template match="//schema">
    <xsl:copy>
      <xsl:apply-templates select="@* | *" />
      <xsl:element name="field">
        <xsl:attribute name="name">_uniqueid</xsl:attribute>
        <xsl:attribute name="type">string</xsl:attribute>
        <xsl:attribute name="indexed">true</xsl:attribute>
        <xsl:attribute name="required">true</xsl:attribute>
        <xsl:attribute name="stored">true</xsl:attribute>
      </xsl:element>
      <xsl:element name="dynamicField">
        <xsl:attribute name="name">*_t_ko</xsl:attribute>
        <xsl:attribute name="type">text_cjk</xsl:attribute>
        <xsl:attribute name="indexed">true</xsl:attribute>
        <xsl:attribute name="stored">true</xsl:attribute>
      </xsl:element>
    </xsl:copy>
  </xsl:template>

  <xsl:template match="//schema/uniqueKey/text()">
    <xsl:value-of select="$uniqueKeyReplacement" />
  </xsl:template>
</xsl:stylesheet>

General rules of XSLT

1. XSLT is rule-based: XSLT works by applying a set of rules to the input XML document. These rules are defined in an XSLT stylesheet, which contains a set of templates.
2. Templates: Templates are the basic building blocks of an XSLT stylesheet. Each template defines a set of rules that are applied to a specific part of the input XML document. Templates are identified by a match pattern, which specifies the part of the input document to which the template should be applied.
3. XPath: XPath is a language used to navigate through an XML document and select nodes that match a specific pattern. XPath is used extensively in XSLT to locate nodes in the input document that are to be transformed.
4. Output types: XSLT can generate output in various formats, such as HTML, XML, or plain text. The output type is specified using the xsl:output element in the XSLT stylesheet.
5. Elements and attributes: XSLT uses a set of built-in elements and attributes to perform transformations. For example, the xsl:value-of element is used to output the value of a selected node in the input document, while the xsl:if element is used to apply a transformation only if a certain condition is met.
6. Modes: Modes allow you to define different sets of templates for different contexts. You can define a mode for a specific template and then apply that mode to the transformation using the xsl:apply-templates element.
7. Variables and parameters: XSLT allows you to define variables and parameters that can be used in the transformation. Variables are defined using the xsl:variable element, while parameters are defined using the xsl:param element.
8. Built-in functions: XSLT provides a set of built-in functions that can be used to manipulate nodes and values in the input document. For example, the xsl:choose element can be used to select between different output options based on a specified condition.
9. Recursive templates: XSLT allows you to define recursive templates, which can be used to traverse complex data structures such as XML trees. Recursive templates can be defined using the xsl:template element.
10. xsl:apply-templates and xsl:copy-of are two important XSLT (XSL Transformation) elements used for transforming XML documents.
11. xsl:apply-templates: This element is used to process nodes in the input XML document. It applies templates to nodes based on their type and context. When applied to a node, xsl:apply-templates looks for a matching template rule, which specifies how the node should be transformed. If no matching template rule is found, xsl:apply-templates applies a default rule.
12. xsl:copy-of: This element is used to create a copy of the selected nodes in the output XML document. It copies the selected nodes along with their attributes and child nodes. Unlike xsl:apply-templates, xsl:copy-of does not transform the copied nodes. In summary, xsl:apply-templates is used to process and transform nodes in the input XML document, while xsl:copy-of is used to create a copy of nodes in the output XML document without transforming them.
13. In XSLT, select="@* | node()" is a selector used in XSLT templates to select all attributes and child nodes of the current node.

References: https://www.w3schools.com/xml/xsl_templates.asp