Troubleshooting Techniques

Overview

The Troubleshooting Techniques topic contains tips and best practices for troubleshooting XML, XSL, and template issues within the OU Campus CMS.

XSLs and Template File Sets

When working within a live site or even within a test environment, making changes to an XSL can have detrimental effects, especially if a page that calls the XSL is published. The XSLs do not need to be published to affect pages that use them. Once changes in an XSL are saved and a page that uses it is previewed, edited, compared, or published, these changes are rendered. It can also be, though, that the XSL excludes specific rendering in specific modes. For example, if a particular include file or xsl:template match might only be included in publish mode. If the template location is set to be on staging, changes to files within a specific template file set are also immediate.

One method to troubleshoot issues and test new development is to make a copy of affected files: especially, XSLs, TCFs, and TMPLs, and then proceed to make changes to the files. This can make it easier to rollback or undo changes that did not work or that borked something. Sometimes an entire directory of XSLs may need to be copied.

Setting up  a Test Environment 

  1. Make a copy of the XSL folder. This automatically names the folder xsl-1. It may be prudent to rename the folder to xsl-yourname (e.g., xsl-ralphie).
  2. Create a test directory, named for example, yy-test, being very careful to ensure that the navigation is not changed with the addition of this new section.
  3. Change the pcf-stylesheet declaration in the test pages to point to the new test XSL directory.

Make the necessary changes or conduct troubleshooting in the test folder and test the changes. 

Tracking Changes with Versions

  1. After verifying that everything is working as expected, save a version of the original XSL in the original XSL folder.
    Make sure to add a Version Description, as this helps identify which edits introduced errors, if any errors are discovered later.
    A version description might include text such as: “Prior to changes to fix the alignment.”
  2. Make the necessary changes in the original file.
  3. Publish content that was not part of the test directory to confirm that the changes render pages as expected. 
  4. Create a version of the changed XSL that includes a summary in the Version Description.

Cleaning Up

To keep the site tidy, delete the files used for testing.

Page Templates

Troubleshooting and testing template file sets follow similar steps to those above, but the copies of the test files for the TMPLs, TCFs, and INCs must be in the existing template directory.

Copying Template Files

  1. From a Content > Pages view, navigate to /_resources/ou/templates/. Location is typical as the template directory may differ.
  2. Hover, and from the File menu, select Copy for each file that will be modified. Alternatively, use the checkboxes to multiselect files and copy.
  3. Rename the test files as necessary.

Changing Access Settings

Changing the access settings for the test copies of the template files is recommended.

  1. From Setup > Templates, Access drop-down for the template, choose (Administrators Only).
  2. Click Save.
  3. Select Template Groups from the local menu.
  4. Click New and give the new group a name; for example, Test Group
  5. Select the checkboxes for copied, test TCFs to be included in the new template test group.
  6. Click Save.

Follow the prior steps regarding testing and versioning for XSLs.