XSLT Processor Upgrade to Saxon 11.3
This page applies exclusively to upgrades from versions before 2022.1.3 of the CMS.
PurposeLink to this section
We are upgrading the XSLT processor, Saxon, on May 19, 2022. Omni CMS uses Saxon to process all Publish Control Files (PCFs). With this upgrade, you will notice the following:
- More functionality when developing XSL.
- Better performance when viewing PCFs inside Omni CMS.
How will this affect your site?Link to this section
Common Example Issues and Fixes
We reviewed every customer account on SaaS to mitigate potential issues prior to upgrade. We know that you may have developed custom XSL, so we have created a list of changes, using examples, you may need to implement in order to be compatible with the release. Review your XSL and make these changes, as applicable, prior to May 19, 2022.
document function change
The document() function will no longer silently fail when the given XML document is unable to be retrieved. To find out if this affects your implementation use Find and Replace and search for document( in only XSL files. If found, review the full scope of all the logic around where this function is called to see if a change is required.
<!-- Look for (potential find) -->
<xsl:variable name="file-contents" select="document($path)"/>
<!-- Correction Required -->
<xsl:variable name="file-contents">
<xsl:if test="doc-available($path)">
<xsl:copy-of select="doc($path)"/>
</xsl:if>
</xsl:variable>
<!-- $file-contents is an example variable name. Any usages of $file-contents after it's declared will need to make sure that the contents were found before doing xpath operations on it. -->
xsl:mode change
xsl:mode element does not allow a mode name of #default. You can either remove #default when a mode has no name or define the explicit name on the mode. To find out if this affects your implementation use Find and Replace and search for #default in only XSL files. If found, follow the one of the corrections based on the situation.
<!-- Look for (potential find) -->
<xsl:mode name="#default" on-no-match="shallow-skip" />
<!-- Correction Required: Two Options -->
<!-- Option 1 -->
<!-- if mode is supposed to be default -->
<xsl:mode on-no-match="shallow-skip"/>
<!-- Option 2 -->
<!-- if mode is defined on the xsl:stylesheet -->
<xsl:mode name="snippet-body" on-no-match="shallow-skip"/>
Backticks are not allowed in xsl:template match statements
Some xsl:template matches may have backticks in the match statement. These backticks do not affect how the statement is processed and they are now disallowed. To find out if this affects your implementation use Find and Replace and search for a backtick ` in only XSL files. If found, remove the backticks as these have no affect on how the XSL is processed.
<!-- Look for (potential find) -->
<xsl:template match="`[MATCHSTATEMENT]`"> (notice the backticks)
<!-- Correction Required -->
<xsl:template match="[MATCHSTATEMENT]">
Include files on the staging server can not be <ouc:div>
You must write staging includes in your XSL with comment tags, especially when creating includes that appear before the <html> tag. We recommend all your staging includes use comments for the best experience when editing pages.To find out if this affects your implementation use Find and Replace and search for <ouc:div in only XSL files. If found, switch to the comment style approach and verify that everything is still functioning.
This is not related to editable regions on PCFs.
<!-- Look for (potential find) -->
<ouc:div label="{$staging_path}" path="{$staging_path}"/>
<!-- Correction Required -->
<xsl:comment> ouc:div label="<xsl:value-of select="$staging_path"/>" path="<xsl:value-of select="$staging_path"/>"</xsl:comment> <xsl:comment> /ouc:div </xsl:comment>
No whitespace in XSL import href attributes
There can be no whitespace in the href value of an xsl:import. If you have a space, you will encounter an error similar to Illegal character in path at index 10: example.xsl. To find out if this affects your implementation use Find and Replace and search for .xsl " in only XSL files. If found, follow the correction of removing the extra whitespace.
<!-- Look for (potential find) -->
<xsl:import href="example.xsl " /> (notice the space)
<!-- Correction Required -->
<xsl:import href="example.xsl" />
<ouc:ob /> needs to be a comment
You must change all <ouc:ob /> to a comment style, this will make the direct edit link output.
<!-- Look for (potential find) -->
<ouc:ob />
<!-- Correction Required -->
<xsl:comment> com.omniupdate.ob </xsl:comment><xsl:comment> /com.omniupdate.ob </xsl:comment>
<ouc:date /> needs to be a comment
You must change all <ouc:date /> to a comment style, this will make the proper time output.
<!-- Look for (potential find) -->
<ouc:date />
<!-- Correction Required -->
<xsl:comment> com.omniupdate.date </xsl:comment><xsl:comment> /com.omniupdate.date </xsl:comment>
Frequently Asked QuestionsLink to this section
When is this upgrade occurring?
We are targeting 5/19/22 for this upgrade.
Will there be downtime during this upgrade?
We are targeting no downtime for this release and it will be completed during off-peak hours.
What can be done or has been to prepare for this upgrade?
We have proactively reviewed all customer accounts on Omni CMS SaaS and have implemented the appropriate XSL fixes where applicable. We have reviewed what we can, but we realize that you may have customizations to your XSL that we are not aware of. To help with this, review the common issues and fixes to see if any apply to your XSL. If have questions about a potential change required, contact our help desk.
I am having an issue after the upgrade, what do I do?
Before submitting a help desk ticket, and if you are comfortable with XSL, review the common issues and fixes to determine if it is one of those. If you are unable to apply a fix, contact our help desk. Be sure to include a link to the affected PCFs.
After the update, I am receiving an error about a missing file, what does this mean and how do I correct it?
This error message will be along the lines of: XML parser processing file ... [filepath] .. (No such file or directory).
What does it mean?
At the end of the filepath, it may contain a file name of _props.pcfs, _breadcrumb.xml, or _properties.pcf. This is most commonly used for creating breadcrumbs, Section Title, inside of your pages for each folder. In the new Saxon version, it is important to make sure this file exists in any folder, as well as the folders above the given folder, that contains PCFs to make sure that the breadcrumb functionality works correctly. We noticed this file was missing from the most top level folder of some customer sites. When we came across this error, we added the missing file back to prevent errors in the new Saxon version.
How do I correct it?
The filepath in the error message will state the location where the file is missing. To correct this issue, you will need to copy an existing _props.pcf, _breadcrumb.xml, or _properties.pcf from a different folder into the specified filepath in the error message. After this file is copied to the folder that is missing it, you will need complete the following:
- Navigate to the copied file and change the Section Title to have the correct wording for the given folder
- Verify The affected PCFs should now be able to be edited again
If you are unable to apply this fix, contact our help desk.
When will this upgrade affect self-host customers?
The updated Saxon version is scheduled to be released to SaaS customers on 5/19/22 as Omni CMS 2022.1.3. The specific version number of Omni CMS is subject to change. This means any version of Omni CMS after this upgrade will affect self-host customers.
