Modify XML files on your website via XSLT with the file XSL transformation package fragment installer

You can have a CMS Package modify an existing XML file by using XSLT. For example, you can add some configuration entry required for your package to web.config. For this, you should:

1. Create an XSL file that will transform the target XML and add this file to your package.
2. Manually update install.xml in your package to specify the target XML file and the XSL file to use on it.

Normally, you should create two XSL files:

• To add or change something when installing a package
• To remove or roll something back when uninstalling a package

We recommend that you put these files in a dedicated folder (for example, "Config") within the package.

Creating XSL files

1. Create a folder to store XSL files in, for example, "Config".
2. Create one XSL file that will add/update content in the target XML file, for example, "Install.xsl".
3. Create another XSL file that will remove/roll back content in the target XML file, for example, "Uninstall.xsl".
4. Add the folder with these files to your package (pack it into the package ZIP).

Install.xsl:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:msxsl="urn:schemas-microsoft-com:xslt" exclude-result-prefixes="msxsl"> 
  <xsl:output method="xml" indent="yes" /> 
  <xsl:template match="@* | node()"> 
    <xsl:copy> 
      <xsl:apply-templates select="@* | node()" /> 
    </xsl:copy> 
  </xsl:template> 
  <xsl:template match="configuration/system.web"> 
    <xsl:copy> 
      <xsl:if test="count(authentication) = 0"> 
        <authentication mode="Forms" /> 
      </xsl:if> 
      <xsl:apply-templates select="@* | node()" /> 
    </xsl:copy> 
  </xsl:template> 
</xsl:stylesheet>

In the sample Install.xsl above, XSLT:

• looks up the section configuration/system.web (the target file is web.config)
• checks whether the element <authentication mode="Forms"/> exists,
• adds it, if not

Uninstall.xsl:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:msxsl="urn:schemas-microsoft-com:xslt" exclude-result-prefixes="msxsl"> 
  <xsl:output method="xml" indent="yes" /> 
  <xsl:template match="@* | node()"> 
    <xsl:copy> 
      <xsl:apply-templates select="@* | node()" /> 
    </xsl:copy> 
  </xsl:template> 
  <xsl:template match="configuration/system.web/authentication" /> 
</xsl:stylesheet>

In the sample Uninstall.xsl above, XSLT removes the <authentication/> element.

Please note that these samples are provided for illustration only. In real-life scenarios, you may want to avoid removing the <authentication> element in web.config because it may be used by C1 CMS or other installed packages.

Updating install.xml

CMS Packages are ZIP files either uploaded to C1 CMS directly or fetched via a remote web service. In the root of this ZIP file, there is "install.xml", the file which describes the package and how the installation process should run.

The package's ZIP file must at least contain the install.xml. All other files in the ZIP are considered data. There are no restrictions of the folder and file layout of the ZIP.

Among other information (which is out of this article's scope), the install.xml specifies package install actions, that is, steps to execute when installing and uninstalling a package.

The steps themselves are handled by "fragment installers" (plug-ins) and not by the package installer itself. Their respective XML elements are placed in the section mi:PackageInstaller/mi:PackageFragmentInstallers and contain class names for the fragment installers to use as well as XML passed on to these installers when called.

Package Creator automatically creates an install.xml, makes necessary entries in it, and, if needed, adds package data (folders and files).

To use custom XSL files that transform target XML files, you should use a specific fragment installer: FileXslTransformationPackageFragmentInstaller.

To specify the target XML file and XSL files to transform it when installing and uninstalling a package, add this fragment installer element to install.xml:

1. Extract the install.xml from the package and edit it.
2. In the section mi:PackageInstaller/mi:PackageFragmentInstallers, add:
   

   <mi:PackageInstaller xmlns:mi="http://www.composite.net/ns/management/packageinstaller/1.0"> 
     <!-- skipped for readability --> 
     <mi:PackageFragmentInstallers> 
       <!-- skipped for readability --> 
       <mi:Add installerType="Composite.Core.PackageSystem.PackageFragmentInstallers.FileXslTransformationPackageFragmentInstaller, Composite" uninstallerType="Composite.Core.PackageSystem.PackageFragmentInstallers.FileXslTransformationPackageFragmentUninstaller, Composite"> 
         <XslFiles> 
           <XslFile pathXml="~\Web.config" installXsl="~\Config\Install.xsl" uninstallXsl="~\Config\Uninstall.xsl" /> 
         </XslFiles> 
       </mi:Add> 
     </mi:PackageFragmentInstallers> 
   </mi:PackageInstaller>

    
3. Save the install.xml and add it back to the package overwriting the outdated install.xml in it.

As you can see in the sample above:

• You add the required fragment installer with the <mi:Add/> element specifying its type in the installerType and uninstallerType attributes
• Each file you want to modify with XSLT is specified in the pathXml attribute of the <XslFile/> element listed under <XslFiles/> element (web.config, in our case)
• Each <XslFile/> element have two more attributes: installXsl and uninstallXsl, where you specify the corresponding XSL files (Install.xsl and Uninstall.xsl, in our case)

The unistallXsl attribute is optional.

Please note that you should use relative paths:

• The path to the target XML file (preceded with '~') must be relative to the website's root.
• The paths to XSL files (preceded with '~') must be relative to the package ZIP's root.