Customize iWeb 2.0 Themes and Edit XML

December 13, 2007

Okay, here we go folks. So many people have been asking for updated information about this. I can’t provide all the information at once so I will be updating this entry with each new step, over a period of days. This is what I’ve compiled for the last few weeks.

This document will explain how to effectively duplicate and edit iWeb themes for your own personal use. Please take your time and read this information slowly. I understand the urge to just jump in and edit stuff, but I’m taking a lot of time to elaborate on aspects of the process that will not only save you time, but prevent you from making obvious and costly errors. The document should turn you into a very skilled theme editor so take your time and digest each piece before moving on to the next.

Preface

iWeb themes are a collection of files bundled together into two major pieces: a .webtheme file and a folder of thumbnail images. If you have a complete .webtheme file and you place it within iWeb’s Themes folder and you have a folder of thumbnail images placed within iWeb’s thumbnails folder, then your theme will appear in iWeb’s theme selection dialog and theme swapping dialog boxes when you create new pages.

The path to iWeb’s Theme folder is:
/Applications/iWeb/Contents/Resources/Themes/

The path to iWeb’s thumbnails folder is:
/Applications/iWeb/Contents/Resources/thumbnails/

There is a file named ThemeSortOrder.plist located here:
/Applications/iWeb/Contents/Resources/Themes/ThemeSortOrder.plist

There has been some debate about the use and necessity of this file. At the time of writing, I have not found any proof that this file needs to be edited if you create or install new themes. At one time we believed it was necessary for Leopard, but that is not true. I have not edited that file at all and all my custom themes work just fine in Leopard.

The purpose of ThemeSortOrder.plist, so far as we can tell, is simply to manage the display order of your themes. iWeb will display your themes alphabetically by default, but you can use this file to arrange them in any other order you wish. If you want the Kids Pink theme to be first in your list, you can use this file to make that happen. However, I do not advise doing that. The slightest mistake in this file will produce various bizarre problems within iWeb, including the inability to create new pages. If you decide to edit this file to rearrange your theme order, make a back-up of the original in case you really screw things up.

The instructions from here on out assume you will duplicate an Apple theme and then edit the duplicate, but it is not necessary to create a duplicate if you only want to make minor changes to an existing theme. You can skip to the steps where editing begins if you wish.

Suggested Applications

There are a number of applications I use to edit and create iWeb themes. Some are required, others are optional and some are just suggestions.

Code Editing

Most of the iWeb files that you will edit need to be edited with a text editor or dedicated code editor. TextEdit will work just fine but I suggest that you use a real code editor. There are free code editors available on the Internet. TacoHTML is one that many people use, but I personally use TextMate. TextMate is a powerful code editor with a deceptively simple interface. I like it because the interface is not cluttered with buttons or other nonsense you don’t need. It colors your code significantly better than Taco, to make it easier to view and it will also fold code, although I likely won’t discuss that feature in this article. It’s a luxury however so if you intend to do a lot of iWeb theme editing, invest in a code editor like TextMate.

Mass Replace Text Editing

You likely won’t understand the value of this yet, but an application named MassReplaceIt is one invaluable tool you must have. It’s free, but consider tipping the developer. Download and install this application.

Image Editing

It’s not necessary to have an image editor or know anything about image editing if all you want to do is change some text styles in a favorite theme, but most people want to alter the images in the iWeb themes as well. I’m in no way going to get into how to edit images as that’s a gigantic topic in and of itself, but if you have the basic skills and you want to edit theme images, get yourself an image editor. I use Photoshop period. But you can use anything you like. In some sections of this document, I will give you tips for editing images, but you’re pretty much on your own in that area.

PNG Image Compression

Download and install an application called Ping. Once you copy this application into your Applications folder, then drag it from there, to your dock. This application will attempt to compress PNG images for you. Often, graphics applications do a very poor job of compressing PNG images and if you create PNGs for your iWeb site, you’ll want to try to compress them first so they aren’t HUGE. Create your PNG image first and then when you’re ready to compress it, drag it from Finder and drop it on the Ping icon in your dock. If Ping can compress it, it will and it will save it right back to the location from which you dragged it. Then you can drag it onto your iWeb page without all the extra file size. Ping can’t always compress PNG files. I have found that complex shadows and gradients in your image will likely hamper compression.

Color Management

The iWeb XML uses RGB100 values to specify color. Most of us are familiar with hex values for color, for example #FF33CC or #000000, and we’re all familiar with RGB255 specifications as well ( 255,0,0 or 204,130,65 ). But RGB100 is different. It’s similar to RGB255 in that each color, red, green and blue have a value on a spectrum, but the spectrum is from 0 to 100, not 0 255. You will need an application that helps you determine RGB100 values. I use Art Director’s Took Kit for this. The application has so many nice features beyond this, but RGB100 color values is what you need in this case. Any application that will allow you to pick colors and then give you the RGB100 value for it will work.

iWeb

Of course you need iWeb 2.0, part of iLife ‘08 for this tutorial. These instructions will not work for iWeb 1.0. The old, out-dated 1.0 instructions can be found here. Use at your own risk.

Step 1: Duplicate An Existing iWeb Theme

Here are the steps to duplicate an iWeb 2.0 theme. Close iWeb before you begin.

1. Right click or control click on the iWeb application icon in your Applications folder.
2. Select Show Package Contents from menu.
3. Navigate to the Themes folder. The location was mentioned in the section above. In this folder you will find all of Apple’s themes and any third-party themes you have installed.
4. Decide which theme you want to duplicate and then right click or control click on its filename. Select Duplicate from the pop-up menu.
5. Rename the duplicate using a unique name. Spaces in the name are okay, for example: Baby Orange.webtheme, but do not choose a name that’s longer than 13 characters or it will not display properly in the theme selection window when you create new pages.
6. Now, navigate to the thumbnails folder. The location was listed in the previous section above. In this folder, you will find sub-folders, all with names that reflect every theme you have installed. For example, if you have a theme named Kids Pink.webtheme, then you will have a thumbnail folder named Kids Pink as well.
7. It is not required that you create thumbnails for your theme. If you choose not to create thumbnail images, all thumbnails will appear blank when you create a new page with your theme. While that’s fine, it’s kind of weird so another option would be to duplicate an existing folder of images from an Apple theme. For example, if your new theme is named Baby Orange, then it might make sense to duplicate the Baby theme thumbnails and then replace the images with new ones when you have time. If you choose this option, simply duplicate the folder named Baby and then rename the duplicated folder to Baby Orange. I have found that it is not necessary to rename the actual thumbnail images within the folder, but some of you might prefer to do that.

   The last option would be to create a new, empty folder with the name of your theme, Baby Orange, or whatever you chose and then to create your images one by one as you have time. Be sure to use the same naming convention that Apple uses for their thumbnail images. Note that they are TIFF images. The name is important. If you don’t name them correctly, your thumbnails will not display in the theme selection window.

8. The last step requires that you update the display name of the theme. The display name is the name that actually appears in the theme selection window. To edit this name, please return to the Themes folder within iWeb and continue with the next step.
9. Find your new theme and right click or control click on its icon. Select Show Package Contents from the pop-up menu. This will display a new Finder window revealing the contents of your theme. There will be numerous folders and files in your theme.
10. The display name of your theme can be localized in any or all of the languages Apple supports. That’s why when you open your theme, you see folders for many languages. If you’re creating this theme for yourself, you only need to select the language folder for the language in which your Mac operates. If your Mac is using Spanish as the system language and all your applications are in Spanish, then open the Spanish folder and find the file named DisplayNames.plist. This file exists in every language folder so select your language and open that folder to find that file.
11. Open the file named DisplayNames.plist using a code editor or TextEdit. Do not use Pages or Word or any other word processing application.
12. In this file, there are two lines that control the display name. They look like this:

    <key>DisplayName</key>
    <string>Baby</string>

    Update the display name from the original theme name to your new theme name. For example, if the original theme name was Baby and your new theme name is Baby Orange, then your change would look like this:

    <key>DisplayName</key>
    <string>Baby Orange</string>

13. Save and close the file.
14. OPTIONAL: You already know that within the theme selection window in iWeb, there is a dropdown list that allows you to filter all of your themes. Apple has grouped its themes by release (1.0 Themes, 1.1 Themes and 2.0 Themes). If you purchased a license for any of my themes, you will also see a group named 11 Mystics Themes. You can create a new group for your personal themes if you wish. Follow these remaining steps to do so, otherwise, skip to the next section.
15. Within the language folder where you found the file DisplayNames.plist, you will also find a file named index.xml.gz. Double-click index.xml.gz to decompress and reveal a file named index.xml. See the picture in the next step for more information.
16. Rename the original file index.xml.gz to index.xml.gz.original or something similar. This is very important. If you do not rename the file, the process will not work.
    
17. Open index.xml with a code editor or with TextEdit. Do not open it with Pages or Word or any other word processing application.
18. Within the file, you will find a giant cluster of XML – it will not make much sense so don’t even try to understand it. However, find this much:

    <bl:theme bl:version=”1.0″ sf:name=”theme”>

    This is where you set the name of the filter for your theme. If you study this line of text, you will see bl:version=”1.0″ within it. In this case, the theme was originally assigned to the 1.0 Themes group. In the XML they call it version, but ultimately, that’s the text that becomes your group name. iWeb automatically appends the word Themes to the the value you provide here, so if you want your group name to be My Themes, then simply replace 1.0 with the word My as shown below. Do not use apostrophes in your group name, i.e. Christopher’s or Jane’s.

    <bl:theme bl:version=”My” sf:name=”theme”>

19. Save and close the file. Make sure you renamed the original file from index.xml.gz to index.xml.gz.original or your group name change will not work.

Congratulations! You have successfully duplicated an iWeb 2.0 theme! If you would like, you can now open iWeb to view the results of your efforts. If you chose to create a custom group name for your theme, you can select your new group from the dropdown list in the theme selection window in iWeb, otherwise the theme will appear under the group that was specified by the original theme you duplicated (1.0 Themes, 1.1 Themes or 2.0 Themes). As always, all themes can be viewed using the All group filter.

Step 2: Editing Theme Imagery

To be written… for the really smart, geeky folks, you will find all the theme images in the theme’s Shared folder. You can open those images in your favorite image editor right from the Shared folder. You can change the look of the image all you want, but do not change its dimension or file name. That will break the theme.

When you save your changes, they’ll save right back into the Shared folder, unless you’re using Photoshop or some other image editor that uses layers. Then it’s likely you will be prompted to save your changes into a new file. I always keep a directory of my artwork for each theme. I save the images there and keep them forever. I just drag copies into the theme’s Shared folder when they’re ready.

Be sure if you’re just changing an image, that you save the new version back into the Shared folder with the original name or it won’t appear in your theme. The XML code looks for those file names so the name is very important.

More details about this will be written later.

Step 3: Editing Theme Styles Embedded In XML

To be written… for the smart, geeky people, the original XML editing instructions found in the 1.0 document still apply for the most part. If you want to get a jump start on editing XML, review that entry and ALL the comments. I’m sure I’ve answered everything in that thread. The exceptions for 2.0 themes would be the navigation menus, the comments and the blog and podcast summary areas. All of these sections are now handled by some simple HTML and CSS that’s embedded within the XML. If you know a little of both of those, you should be able to make your way around that stuff.

The page XML files are all located in the Shared folder for your theme. You will have to decompress the .gz files first. Just double click them. I delete the .gz files after that, but you might want to rename them or save them off somewhere else. Just don’t leave them there with their original names or you’ll never see any of your changes.

Format the XML files then with MassReplaceIt so that all instances of >< are replaced with:

>
<

That’s right, you’re inserting a line break. If you don’t, best of luck to you ;-)

Then you can open the XML files and edit anything you want. Changes are immediate so you can have iWeb open at the same time you’re editing to test your changes. Just remember, changing template XML does NOT, NOT, NOT, update pages you’ve already created. It changes the template so create a new page to see your changes.

If you’re not seeing changes, you failed to rename your .gz files or delete them.

Details for this will be written later. Please hold off on questions for this section until I’ve completed it. Thanks.