Feature Preview: HTML Export: Custom XSL
In a previous post, I discussed how you can customize the web pages built when using the new HTML export utility by altering the CSS files. Now I'll take a big step forward and demonstrate how you can make even bigger changes using your own customized XSL file.
First, an example. Below is the slide when exported using the built in style Dark:
Now here is an example using an alternate XSL file that I built for this demonstration.
As you can see, we now have different background colors, thumbnail previous of both the previous and next slides, and a different set of forward and back buttons. Now to explain how this was done.
First, its important to remember that the current HTML export utility for SongShow Plus slide shows exports each slide as its own HTML document. A future edition of SongShow Plus will provide a single document option, but for now, this is how it works.
When using the HTML export utility in the slide show builder, what is actually happening is that the slide image is saved to a folder, then an XML document is generated that contains information about the slide as well as information about its neighboring slide. The exporter then opens the XSL file that was selected by the user, and applies it to the XML document. XSL files are used to transform XML documents into other forms of files, usually to XHTML documents or other another form of an XML document.
In order to build an XSL file that will transform an XML document from one thing to another, you must first know what to expect from the original XML document. XML Schema is often used to describe the structure of an XML document, but I've found that, while that is useful for things like XML editing tools, its easier to describe an XML document by simply showing examples.
Here is an example of an XML document generated for one of the slides:
- h:DocumentExtension
- Identifies the extension to use for the document being created. This is used in conjunction with the slide file names below to provide links to neighboring slides.
- h:CSSFile
- Identifies a user selected CSS file to use. In this case, none was selected.
- SlideShowTitle
- Title of the slide.
- SlideFileName
- File name (without extension) used for both the HTML document and the slide's image file.
- Width
- Width of the image as specified by the user.
- Height
- Height of the image as specified by the user.
- PreviousSlideFileName
- File name (without extension) of the previous slide. If empty, there is no previous slide.
- NextSlideFileName
- File name (without extension) of the next slide. If empty, there is no next slide.
- ImageFileExtension
- File extension used for the image files of the slides.
So with this information, we can now build an XSL file that transforms this XML document to the HTML document we want.
Here is the XSL file used to create the example slide show:
I won't go into detail explaining what the various XSL elements do. Those of you who do web site programming will already be familiar with XSL and XPath. If not, the w3schools.com tutorial on XSL and its tutorial on XPath are a good places to start. There are a few things to note, however. You'll notice that the CSS information is embedded into the HTML document. This is in contrast to the previous examples that used an external style sheet. I did this for demonstration purposes. You could certainly change the style section in the header to reference an external CSS file.
It's also important to note that the HTML export utility uses the MSXML engine. Unfortunately, this engine only supports XPath 1.0, which is too bad since XPath 2.0 provides so many more functions. In particular, rather than hard-coding the size of the thumbnail images in the XSL above, an XPath 2.0 function could have been used to calculate these sizes based on the width and height elements in the export XML document. (I've already have a solution for this for a future edition of SongShow Plus.)
To use an XML file that you've built yourself, during the export process, on the Style page, select the Use an alternate XSL file option. Clicking this option will let you then select your .xsl file where ever it may reside.
If there are other files that you need, such as accompanying image files for buttons, etc., be sure that their filenames start with the same name as your .xsl file. In this example, our XSL file was named "ThumbnailPreview.xsl", and image files used for the buttons were "ThumbnailPreview-LeftArrow-Disabled.png", "ThumbnailPreview-LeftArrow-Enabled.png", "ThumbnailPreview-RightArrow-Disabled.png", and "ThumbnailPreview-RightArrow-Enabled.png". The image files need to be located in the same folder as the .xsl file. Here's the list of all files used by the XSL for the export process:
ThumbnailPreview-LeftArrow-Disabled.png
ThumbnailPreview-LeftArrow-Enabled.png
ThumbnailPreview-RightArrow-Disabled.png
ThumbnailPreview-RightArrow-Enabled.png
ThumbnailPreview.xsl
And here is the list of files used in the target folder containing the new HTML documents:
Announcements-001-Introduction.html
Announcements-001-Introduction.jpg
Announcements-002-Worship Band Rehearsal.html
Announcements-002-Worship Band Rehearsal.jpg
Announcements-003-Annual Ski Trip.html
Announcements-003-Annual Ski Trip.jpg
Announcements-004-Women's Retreat.html
Announcements-004-Women's Retreat.jpg
Announcements-005-Baby Dedication.html
Announcements-005-Baby Dedication.jpg
Announcements-006-Men's Prayer Breakfast.html
Announcements-006-Men's Prayer Breakfast.jpg
Announcements-007-Water Baptism.html
Announcements-007-Water Baptism.jpg
Announcements-008-Marriage Conference.html
Announcements-008-Marriage Conference.jpg
Announcements-009-Volunteers Needed.html
Announcements-009-Volunteers Needed.jpg
Announcements-010-End of Show.html
Announcements-010-End of Show.jpg
ThumbnailPreview-LeftArrow-Disabled.png
ThumbnailPreview-LeftArrow-Enabled.png
ThumbnailPreview-RightArrow-Disabled.png
ThumbnailPreview-RightArrow-Enabled.png
This was a brief review of how to customize the documents generated using the HTML export utility.
(BE199)