Journal

28 October 2006

Building a Symphony Theme: Part 1

This is part one in a series of articles on Creating a Theme for Symphony. Building a site in Symphony will require some knowledge about XML, XPath and XSLT, as well as HTML and CSS. All of these technologies are standards developed by the World Wide Web Consortium as the basic building blocks that make the web work. Many of us have come around to the idea of developing standards compliant sites using XHTML and CSS. XML is a standard means of storing and retrieving data and media. However, XPath and XSLT are neglected siblings that could use some attention, and Symphony can help us out in this area. They are, in fact, the heart and soul of Symphony.

Note: I changed horses in mid-stream. The theme being ported to Symphony will be Qwilm instead of Pink for October because of the differences in usage rights.

For a good introduction to XML, XPath and XSLT templating in Symphony, refer to Mark Lewis’s article in the Overture library: A Symphony Walkabout. Also, the Wiki contains some helpful screencasts that demonstrate how to navigate the Symphony admin and build specific functionality into your site.

The Symphony Admin

The first thing you will notice when you login to Symphony is the clean, uncluttered design of the interface.

Symphony Admin : Publish : Comments

Beside the Symphony logo, at the top of the page is the site name, which links to the front page of your website. By default, the name of the site is “Website Name.” This will be one of the first things that you should change.

Settings

First, though, let’s take a look at the Settings menu. It contains two submenus: Authors and System Preferences. Choose Authors, and you’ll see a list of the Authors and Administrators of the site. When you first install Symphony, there is one user.

Symphony Admin : Settings : Authors

Author Settings

Click on the name and you will see the details of the primary administrative user, containing the information provided when you first registered your Symphony account. One thing to notice is the Miscellaneous section, which contains a setting for Formatting Preference. This preference is set for each Author or Administrator. By default, there is only one option: “None.” In actuality, Symphony ships with a default text formatter called SimpleHTML. This formatter does one thing: it wraps lines of text separated by two returns with paragraph tags <p>. If you would like to add text formatters, such as Textile or Markdown, install the corresponding Campfire Service.

Symphony Admin : Settings : Authors : Author Details

System Preferences

Now, select Settings System Preferences and you will find settings for Website Name, Online Status, and Regional Timezone and Date and Time formatting options. The Date and Time settings will be reflected in the Symphony admin for listings of entries where the publish date column is available. Make the appropriate changes to the Website Status and Regional Settings and click on the Save Changes button. A blue bar will appear at the top of the page to indicate that your settings have been saved and the Website Name will change to the name saved. Note that at this time, since I have started with an empty workspace, changes to website status will not affect the front end of the website until the Home and Maintenance pages have been created. Once these page templates are available, the site can be switched to a maintenance mode that gives full access to the front end for administrative users when logged in, but authors and the public will be able to view only the Maintenance page and all links to the site will be redirected to this page.

Symphony Admin : Settings : System Preferences Saved

Campfire Services

If you plan to use text formatters other than the default, SimpleHTML, it would be best to install the Campfire Services you need to make these text formatters available before creating any entries. It is currently not possible to change text formatter preferences on a per entry basis, unless you make the change to the Author Settings each time you need to create an entry that uses a different text formatter. An alternative possibility is to make changes directly to the MySQL database through a database administration tool such as phpMyAdmin. It is assumed that a site administrator will choose one text formatter and use it consistently throughout the site. However, provision has been made to notify a user when the text formatter in use for a particular entry differs from the Author’s formatting preference.

Symphony Admin : Campfire : Your Services

Click on the Get More button and you will find a list of available Campfire Services that can be filtered by Category and Recent Additions to the library. Use the arrows at the bottom of the list to navigate between pages.

Symphony Admin : Campfire : Get Campfire Services : Get More

Markdown and Textile are popular text formatters that are available as Campfire Services for Symphony. Install the Campfire Service for the text formatter, choose the installed Campfire Service from the list of installed services and enable it by selecting Enable from the pull-down menu at the bottom of the page.

Symphony Admin : Campfire : Your Campfire Services : Enable

Navigate to Settings : Authors to edit the Author Settings, select your Text Formatting preference, and save the text formatting preference that will apply to all entries created by this Author after setting this preference.

Symphony Admin : Authors : Textile Formatter

Campfire Services are not included in Symphony Themes, but I find Textile to be very helpful in quickly entering content into entries without worrying too much about HTML coding.

Blueprints

In the Blueprints section, there are three menu items: Pages, Components and Controllers. You may notice that we are working backwards through the main menu items. The Symphony Team has built the interface with the most used section, Publish, featured first. The rest of the items are Administration menus arranged in order of the frequency of use. The Blueprints section contains the HTML, CSS, Javascript, XSLT Templates, XML Data Sources and PHP Events that control the site structure, presentation and behaviours.

Pages

Pages are the templates that control the content for different areas of your site. In the example of a weblog, the standard pages tend to be Home, About, Blog, Archive, and Contact. Each of these pages has a different function and this difference will generally be reflected in the structure and presentation of the content. The Page templates control the structure of individual pages, allowing the template to respond to specific URL schemas.

A blog page might have a very simple URL schema:

                  /entry/

                

Alternatively, a journal may be arranged with a much more complex URL schema to allow for navigation by categories or tags:

                  /journal/tag/entry/

                

An archive may have an even more complex URL schema:

                  /archive/year/month/day/entry/

                

With an empty workspace, there are no pages.

Symphony Admin : Pages

So, we will need to create each page. Click on the Create New button to create a new page template. Each page requires a Title and a Body containing the XSLT template.

Symphony Admin : New Page

Symphony starts off the template with the opening and closing xsl:template elements. We could try a simple experiment, knowing that it will fail, but let’s give it a try and see what happens. Give the new page a Title of “Home”. In the Body of the new page template, create the following template:

                  <xsl:template match="data">
    <h1>Hello World!</h1>
</xsl:template>

                

Click on the Configure button and you will greeted with several additional options. The URL Handle is automatically generated if you leave this field blank, so we can ignore this field for now. The important thing to note is the Page Type. A home page is a special type of page that must be configured with an “Index” Page Type. Select “Index”, click on the Configure button to close the drawer and click on the Save button to save the New Page. Now try navigating to the Home page by clicking on the URL link. You will discover an error page:

Symphony Admin : XSLT Error Page

At the bottom of the page will be a link that provides a link to “Check the page debug information.” Click on this link and you will be presented with the debug information for this specific page, the Home page. There are three links along the top of the page: XML, XSLT and Output.

The XML data associated with the home page is empty:

Symphony Admin : Home Page - Debug Information - XML

The XSLT template contains our code, but the XSLT stylesheet is empty:

Symphony Admin : Home Page - Debug Information - XSLT

Because the XSLT stylesheet is empty, no output has been parsed:

Symphony Admin : Home Page - Debug Information - Output

This is a problem, but it is easily remedied. We could do a couple things, but let’s try the most basic solution first. We need to define a stylesheet by creating a Master template. Navigate to Blueprints : Components and you will find an area to create Utilities, Masters and Assets.

Symphony Admin : Components

Create a new Master template by clicking on the Create New button beside “Masters”. This brings up a New Master page with a layout similar to the page for creating new Pages. However, the default stylesheet has been automatically generated for you. Click on the Configure button and you’ll find that the options are different. As with the Pages configuration settings, you can associate a Data Source with a master page and you can also attach Events that allow you to combine the power of PHP with XSLT to do many more things with your site.

Symphony Admin : Components : Masters : default

Give this master page the name “default” and click the Save button. Navigate to Blueprints : Pages and click on the name of the Home page to edit the page template. In the Master pull-down menu, choose default.xsl and click on the Save button. Click on the URL link for the Home page template to view the Home page in the front end of the site. You should see the heading “Hello World!” rendering properly now. In the browser address bar, type ?debug at the end of the home page URL to view the debug information for the page:

                  http://sym.qwilm.site/home/?debug

                

You will find that the XML data has not changed, since we still have not added any data or data sources. But you will find that the XSLT contains the stylesheet and template, and Output displays the HTML source that was produced by the XSLT template. Congratulations! You have created a working XSLT template.

This, of course, is just the beginning. There is no data, there is no dynamic content. So that is next: Building a Symphony Theme: Part 2.