Leopard Wiki Server: Creating Custom Themes

Wikis are a great tool for sharing information between individuals and teams. By providing a flexible way to update and provide information within a web environment, they make it easy for both basic and advanced users to create and share content that can easily be saved and organized according to individual needs.

Wiki Server, a part of Mac OS X Leopard Server, provides this wiki functionality to all users with access to the server. Individual groups can tap into Wiki Server to create their own wikis and customize the look and feel of the wiki to suit both their content and audience. By creating their own personal wiki theme, Wiki users can apply their own style and identity to the wiki, in addition to supplying their own content.

Follow along in this article to create a customized wiki theme using Wiki Server, and also learn how to extend and improve wiki themes to give your users a greater selection of themes to work with.

Wiki Theme Layout and Structure

Before you begin customizing your Wiki Server themes, you first need to understand the different elements of the wiki page and how they relate to the underlying theme files and definitions. You should also understand how the theme can be changed and modified within the web interface. Figure 1 shows the default theme for a new group.

Figure 1: Default Theme Layout

To change the theme for a group wiki, you must login as a user with rights to manage the wiki. When a user with suitable rights accesses the group wiki page, the Admin Function section in the toolbar is made accessible. These functions in the toolbar provide access to change the settings for the wiki, such as the currently applied theme.

If you click on Settings and then the pencil to edit the settings, you can click on the Choose button next to the Theme selection to choose your theme. An example of this selection is shown in Figure 2.

Figure 2: Choosing a theme

The selection display in Figure 2 provides the first indication of the different elements that you can control and edit. Themes are organized into two types: those with a banner image and those without. The themes with a banner image support any type of image to be used as the banner. You can see in Figure 2 that Block Green Books includes a size specification; this is the width of the window used to display a banner image. Users can change this image using the Banner Image popup at the bottom of the window.

By comparison, the Block Green theme has no banner image, and the user cannot change the banner image because the theme does not support it.

Theme File Locations

The overall theme definition is stored within /Library/Application Support/Apple/WikiServer/Themes. The main theme definition consists of the following four files:

• theme.plist— contains the theme definition, such as the name and the banner specification.
• preview.png— contains a graphic snapshot of the theme for use in the theme browser.
• screen.css— imports the Cascading Style Sheets (CSS) files for use when displaying the wiki server contents to the screen (i.e. within a browser).
• print.css— imports the CSS files for use when the Wiki Server content is printed.

Both screen.css and print.css import their CSS files from the files located within the /usr/share/collaboration/themes directory. Within this directory is a single directory for each theme. The contents of the theme directory include all of the Cascading Style Sheets (CSS), pages and images used to define the theme look and feel.

Note: Importing numerous style sheet files in a web browser can cause performance problems. For this reason, the Apple-provided themes compress all of the style sheets into a single file, before being sent to a web browser. The uncompressed files mentioned in this section are provided for your learning benefit. Keep in mind that the final step in creating a custom-styled theme is to compress the CSS files in order to provide the best performance to your wiki's users.

The theme definitions in the WikiServer/Themes directory specify the main parameters of the theme, while the files in the collaboration/themes directory specify the actual look and feel. By dividing the configuration between these two directories, it is possible to mix and match themes and Cascading Style Sheets from different locations to suit your needs.

Customizable Elements

Before you look at the specifics of the customizations that you can apply to your wiki pages in Wiki Server, you need to think about the layout of the page and how this can be customized. Figure 3 shows the default Wiki Server page layout again, but this time the different areas and elements of the page are highlighted and have been given an identifier.

Figure 3: Highlighted sections of configurable Wiki elements

The highlights given in Figure 3 are just examples of the main areas that you can customize. There are hundreds of individual elements that make up the page, all defined using CSS, that can be controlled and defined through the theme definitions. Additional elements not shown here include the ability to customize the look and feel of comments, blog posts, blog entries, tables, and the overall layout of the individual pages.

Wiki Server makes heavy use of importing CSS stylesheets together to form a complete theme. For example, the default block.green.banner theme shown in Figure 3 imports the CSS files of the block theme from the main CSS directory. The block theme defines the different styles used with a series of different files.

You can see this more clearly later in Figure 4. The main theme definition includes the file, screen.css, which will be specified as the CSS file in the pages served up to the user's browser.

That CSS file, defined within the /Library/Application Support/Apple/WikiServer/Themes/theme.wikitheme directory is what defines the styles for the remainder of the Wiki Server pages. This CSS file imports the screen.css file within the block.green.banner directory in the /usr/share/collaboration/themes/ directory.

That CSS file, in turn, imports the screen.css file within the block theme directory, which, finally, imports the actual CSS definitions for each element on the page.

Although this is a complex structure, and an extreme example of the relationships between the different files, it demonstrates how easy it is to create a suite of CSS files that define common elements, and combine them with smaller CSS files that define specific elements for individual themes. In the process, you can create a range of themes and different colors and styles, while maintaining a consistent look and feel among all of the themes.

Copying an Existing Theme

The easiest way to customize or create a new theme is to start by copying an existing theme. First, copy the main theme definition directory from /Library/Application Support/Apple/WikiServer:

$ sudo ditto /Library/Application Support/Apple/WikiServer/Themes/block.green.wikitheme
/Library/Application Support/Apple/WikiServer/Themes/example.wikitheme

You should delete the compressed directory within the wikitheme directory, as this contains a canned version of the CSS for the theme and will be used in preference to the CSS that you will manually modify.

Now, copy the layout directory with the real CSS files. Use the block directory as the structure, which is easy to understand: $ sudo ditto /usr/share/collaboration/themes/block /usr/share/collaboration/themes/example.

Now you are ready to start customizing the different elements.

Customizing the Theme

The appearance of wiki content is controlled by CSS files, while the information about the theme is stored in the main theme directory.

The theme's property list defines the core settings of the theme, including the theme name and the height and width of the banner image. Additional settings in the theme's property list include the ability to define the sidebar that appears next to the main content of a wiki page. The easiest way to edit the property list is with the Property List Editor.

The following table shows the properties that can be set within the property list for a theme.

Key	Value type	Description
bannerImageHeight	A number > 0	Height of the banner image in pixels. This setting affects only the height of the image, not the banner itself.
bannerImageWidth	A number > 0	Width of the banner image in pixels. This setting affects only the width of the image, not the banner itself.
displayName	Any string	The name of the theme as shown in the theme chooser.
name	Any string, no spaces	A unique identifier for the theme.
selectable	<false/>	Determines if a theme is available in the theme chooser.
version	number	Do not change this value.

The bannerImageHeight and bannerImageWidth properties, in addition to controlling the image size, also control whether a banner image is supported for the theme. If these properties are not present, then the theme does not support a user-defined banner image.

The property list is an XML file, and you can edit the file with any text editor. If you use the Property List Editor application, you must first copy the theme.plist file into your Documents folder. When you are finished, copy the file back to the theme's .wikitheme folder.

After editing a theme's property list, you must restart the web service using the Server Admin administration tool. This will stop the web service for the entire server.

When modifying or creating a new theme you need to change the name property to a unique ID for the theme, and the displayName property to the name you want to use for your theme. You can use the version number to help track differences in your theme definition.

Figure 4 shows a completed property list for the example theme.

Figure 4: The Example property list

Working with Sidebars

A sidebar is a special area that runs along the side of the page's content area. There are several different types of sidebars available, but the content of a sidebar is either static (such as a list of URLs), or dynamic (such as search results). The theme's sidebars are defined with an array of dictionaries in the theme.plist file. All sidebars share keys that define their type, the name of the sidebar displayed to the user and a unique identifier.

Static sidebars have additional keys that determine the list of URLs to display, a URL linked from the sidebar's header, and the URL of an RSS or Atom feed.

The following code shows an example definition of a static sidebar from the wireframe theme.plist file. The sidebar's display name is Useful Links, and its urls key consists of an array of dictionaries that fully specify each URL in the list.

<key>sidebars</key>
 <array>
    .
    .
    .
  <dict>
   <key>displayName</key>
   <string>Useful Links</string>
   <key>type</key>
   <string>static</string>
   <key>uid</key>
   <string>UsefulLinks</string>
   <key>urls</key>
   <array>
      <dict>
         <key>kind</key>
         <string>url</string>
         <key>subtitle</key>
         <string>Your server's homepage.</string>
         <key>title</key>
         <string>Server Home</string>
         <key>uid</key>
         <string>serverhome</string>
         <key>url</key>
         <string>/</string>
      </dict>
      <dict>
         <key>kind</key>
         <string>url</string>
         <key>subtitle</key>
         <string>List of groups with wikis on this server.</string>
         <key>title</key>
         <string>Groups</string>
         <key>uid</key>
         <string>groups</string>
         <key>url</key>
         <string>/groups/</string>
      </dict>
      <dict>
          <key>kind</key>
         <string>url</string>
         <key>subtitle</key>
         <string>All things related to Mac OS X Server
engineering and planning</string>
         <key>title</key>
         <string>Mac OS X Server wiki</string>
         <key>uid</key>
         <string>server wiki</string>
         <key>url</key>
         <string>http://serverstoragesoftware.apple.com/groups
/macosxservergroup/</string>
      </dict>
   </array>
   </dict>
    .

 </array>

Search sidebars have additional keys that determine such attributes as: the number of results to display, the fields used to sort the results, the order in which to display the results and the query used to search for entries. The following code shows the definition of a What's Hot sidebar from the wireframe theme. The tag key specifies how the query will look for pages tagged with the word "hot".

<key>sidebars</key>
   <array>
    .
    .
    .
       <dict>
     <key>displayName</key>
     <string>What's Hot</string>
     <key>howMany</key>
     <string>5</string>
     <key>sortDirection</key>
     <array>
        <string>reverse</string>
     </array>
     <key>tag</key>
     <array>
        <string>hot</string>
     </array>
     <key>type</key>
     <string>search</string>
     <key>uid</key>
     <string>HotList</string>
      </dict>
      .
      .
      .

After you make changes to the theme's property list file, remember you must copy it back to the example.wikitheme/ folder and restart the web service in order for your changes to take effect.

Customizing the CSS

Once you have configured the core information about the theme using the theme's property list, the remainder of the customizations must take place in the CSS for the theme.

First, you need to update the CSS definition within the main theme directory: example.wikitheme. The remainder of the CSS specification should now take place in CSS files within the corresponding wikitheme directory. If you need to copy an existing theme, copy the CSS files from the /collaboration/themes directory. The CSS for the header portion of the Wiki Server pages can be found within the screen/header.css file, while changes to the main content of the Wiki Server page can be set within metadata.css.

You can control all of the different elements of the display of the page through the CSS definition.

Creating a Preview Image

To help the user when selecting the theme they want to use, you should create a preview image that will be displayed as the image when the list of available wiki themes is shown.

To create a preview image:

1. Edit your theme and ensure that all the settings are finalized.
2. Take a screenshot of your theme. You can do this within Mac OS X by pressing Shift-Command-4 and selecting the area of the screen you want to modify.
3. Open the screenshot, which will be located on your desktop, using Preview.
4. Choose Adjust Size from the Tools menu.
5. Deselect Scale Proportionally, and change the measure system to use pixels.
6. Change the size of the image to be 128x128 pixels.
7. Save the image as preview.png.
8. Copy the preview.png file into the wikitheme directory for your theme.

The preview image for the theme will now appear in the theme selection screen.

Conclusion

The look and feel of a Wiki Server page within Leopard Server is highly configurable. Different themes can be edited and new themes can be added to allow you to support a range of different themes to your users. Editing the themes involves changing a combination of the main theme definition and the CSS that makes up the display differences. The relationship between these different components can be quite complex, but the flexibility enables you to create common styles across your different themes, while still retaining the individuality of each theme.

Posted: 2009-02-04