The Defaults System
In this section you will get an introduction of the defaults system I implemented in my themes to be able to modify and expanding the themes.
What is a Default
RapidWeaver seems a little bit limitated from a designers view. There are ways to customize a theme, but they all are not as flexible as they can be:
1. Adjusting the css by adding code in the custom css field
This is what I always recommended, as you won't loose any changes you made when you update a theme. But the drawbacks are that you have to add custom code to each page you create and when you switch to another theme, you have to correct this code.
2. Working on the theme files directly
You can build your own theme by changing the theme files directly. But this also means that you will distroy the original one (if you haven't duplicated it first) and especially with purchased themes it can be a problem when an updated version is available. You will loose all your code
The defaults system adds the ability to add your own design ideas, based on preexisting themes. You can add them also to updated themes, which means that you won't loose anything of your work. Think of the default system as a kind of Open-PlugIn-Architecture. It's the bridge between your ideas and the core theme files you want to customize. You don't have to work on the theme files directly, you just add the necessary code and images. That's all. And: you can even distribute your customizations to other users.
Another gread advantage of the default system is, that you don't have to start your work from zero. Your work is based on a working and tested theme, so if you don't add crazy code, you can be sure that the theme with your design will work well with all major modern browsers.
In general the defaults are small theme parts that are added to the theme. A default consists of additional image files, a css document with the added style definitions and a snippet of the theme.plist document called "Defaults.xml".
How to choose a Default
You can choose an installed default in the style variations under an option called "Defaults". Just choose the default you like, and the theme will change the whole design with just one single click. In this image you see the defaults of the Framed pack for the camilo theme, which can be purchased from my website.
As you already should know: the style variations are part of the Page Inspector window since RapidWeaver 3.6
How to install a Default
1. With an installer script (or application)
If you downloaded a default you will receive a default installer in most cases. Simply double click it and it will install the default for you. Also a backup copy of the acutal theme will be made on your desktop.
2. Manually
If you receive your default (or you have built one of your own) without an installer, you can also install the default contents manually. Here is what you have to do:
(THEME.rwtheme is the actual theme you want a default to add)
1. Copy the CSS File to the following directory: ~/Library/Application Support/RapidWeaver/THEME.rwtheme/Contents/css/defaults/
2. Copy the images directory to: ~/Library/Application Support/RapidWeaver/THEME.rwtheme/Contents/images/defaults/
3. Open the Defaults.xml file in any simple text editor (e.g. TextEdit, skEdit, TextWrangler, ...). Select all text and copy it to the clipboard.
4. Open the theme.plist file in a simple text editor. The file is found here: ~/Library/Application Support/RapidWeaver/THEME.rwtheme/Contents/. Search for the string "<!--user defaults-->" and paste the text just below that line. Save the theme.plist document.
When you did everything right, you will find now your new default in the Page Inspector in RapidWeaver (in the Defaults section in the style variations section).
How to deinstall a Default
The easiest way to deinstall the defaults is to just replace your actual theme in the folder ~/Library/ApplicationSupport/RapidWeaver/ with the original theme. So keep a copy of it before customizing it with additional defaults ;-)
The Structure of a Default
If you want to build your own default for a theme it is vital you know how a default is structured.
Contents of a Defaults
Every default consists of the following components:
1. A CSS file with the style definitions
2. A snippet of the additional theme.plist code in a file called Defaults.xml
3. Additional images (optional)
They are placed into the following structure (where NAME means the name of the default)
Defaults Folder:
Defaults.xml
css (folder):
NAME.css
images (folder):
NAME (folder):
(additional images)
The CSS File
The CSS file is where you code your style definitions. If you don't know any CSS yet and like to create your own custom design, well, you have to learn it.
In the css file you can place whatever you want. But you have to know the CSS rules for the theme. Where you can find out more about the style selectors:
1. There are some standard style selectors for RapidWeaver Themes. You can find them on Realmac Software's Site
http://www.realmacsoftware.com/rapidweaver/manual/index.php?n=AdvancedTechniques.ThemeDevelopment
2. Many things are explained in my free creaturion guide, which can be downloaded from my site:
http://www.rapid-ideas.com/downloads/free.html
3. Have a look at the core theme css files
Mention that:
1. You don't have to include all style rules, just the one you want to add/replace
2. You can also import existing stylesheet files by the @import rule as in the following example:
@import url("../sidebar/backgroundcolor/white.css");
So, create your stylesheet document and save it under "NAME.css" in the css folder of your Defaults Folder. (NAME means the name of your default).
The Defaults.xml File
The Defaults.xml file is a simple snippet of code which will be inserted in the theme.plist document. It is really simple and has the following structure:
<dict>
<key>Enabled</key>
<false/>
<key>Files</key>
<array>
<string>css/defaults/mydefault.css</string>
</array>
<key>Name</key>
<string>My Default</string>
<key>Type</key>
<string>Stylesheet</string>
</dict>
The only thing you need to adjust in this code is the name of the css file (mydefault.css) and the Name String (My Default) to match your default name.
Additional Images
Adding your own images is another way to modify the existing theme. All images which are linked to in the css file need to be placed in the images folder of your default. As there is no way to include new forground images only background images are supported. Let's say you want a background image for the body of your default. First you have to add a style rule in the css document as follows:
body { background: #fff url("../../images/defaults/MYDEFAULT/body_bg.jpg") fixed repeat;}
Now you have to add the image "body_bg.jpg" in the folder "images/MYDEFAULT/" where MYDEFAULT is the name of your default.
The above combination will result in a background with tiled (repeated) images which also won't scroll if the document scrolls.o
Creating your own Default
There are several ways to get started creating your own default. The easiest one is by duplicating an existing default (e.g. one that comes with the Framed pack for the camilo theme).
Duplicating an existing Default
It is best to start with an existing default, as this makes the process of creating your own default a lot simpler. Defaults that are built-in in the themes are not easy to duplicate, so I am not going to describe it here. This manual should be a quick start guide. Once you make your first experiments with the defaults system you will find your own way.
To duplicate a default (which you probably downloaded from my site) you have to copy the "Installer_Source" directory. Most defaults will come with the defaults sources - if not, it means that the defaults should not be modified in any way. You will now have a full copy of all the sources you need.
Adjusting the structure
The first thing you should do after the duplicating process, is to adjust the structure - the names - of the corresponding files. First choose a name for your default. It is recommended to choose a descriptive name for it. Also the name should only have alphanumeric characters - so no space, dot, ampersand, ...
Now you have to rename the following folders/files:
• stylesheet file in "css"-folder (e.g. mydefault.css)
• image folder name in folder "images" (e.g. mydefault)
• optional but highly recommended: Installer_Source folder (the topmost folder of your default - e.g. MyDefault_Installer_Source
Modifying the Defaults.xml File
Start your prefered text editor (e.g. TextEdit, TextMate, skEdit). Create a new text file and add the content below:
<dict>
<key>Enabled</key>
<false/>
<key>Files</key>
<array>
<string>css/defaults/tv.css</string>
</array>
<key>Name</key>
<string>TV</string>
<key>Type</key>
<string>Stylesheet</string>
</dict>
You need to change only 2 lines here:
1. <string>css/defaults/mydefault.css</string>
Change the name of the stylesheet
2. <key>Name</key>
<string>My Default</string>
Change the text string to give your default a name (which will show up in RapidWeaver).
Save the file as Defaults.xml in the Installer_Source folder of your Default.
Adding your own Images
Now, it's time to add your own custom images to the defaults. If you don't need images, the images directory can be empty.
Just replace the existing images in the folder with your own ones. I also recommend to use easy and descriptive names for the images. If you own the camilo theme (and maybe also some defaults for it) you can see that I have chosen file names that tells me for what kind of display they will be used (body_bg.jpg, photo_bg.jpg).
Creating or Modifying the Stylesheet file (in the css folder)
The last step will consume most of the time: modifying or creating the stylesheet file. To start, you should open the stylesheet document (e.g. mydefault.css) in a text editor or any css-enhanced editor. I really like CSSEdit as it makes it really easy to modify/create a stylesheet document. But you may also use another tool here (e.g. skEdit, TextWrangler, ...)
I won't tell you exactly what you have to change in the file as it may differ a lot of what you want to do. Only the most important parts should be explained:
First, you can import preexisting stylesheets in your document, as in the following example:
@import url("../colors/content/black.css");
To know which stylesheets already are available in a theme, you can inspect the theme contents folder.
Just note here that the @import rules have to come at the very beginning in the document - before any other content is coded.
Second, you can overwrite existing style definitions. Say, you want your h1 headers be white and have a font size of 24px, you can add the following code in the document:
h1 {
color: #000;
font-size: 24px;
}
To see what definitions are available for a theme you have to open the existing stylesheet files and have a look there. Many definitions are standard in RapidWeaver and you can also find furhter information about it on Realmac Softwares site:
http://www.realmacsoftware.com/rapidweaver/manual/index.php?n=AdvancedTechniques.ThemeDevelopment
If you have added your images, you should look for the line which includes them in the stylesheet and replace the url with your own one.
When you are finished with the stylesheet file, save the document and close it.
Now, you have all parts ready for your default and you can install it manually as described in the overview of this manual. If you want to go further you can also build an installer for your default which makes it a lot easier to handle the installation process and to share your defaults with other users.
Building an Installer
Building an installer is quiet easy and completed in just a few steps.
Adjusting the Installer Script
If you have purchased the defaults installer script, it is really easy to build a self-working installer for your default. You receive the script which is made for my camilo theme, but you can use it for any other theme which supports the defaults system by just changing the following line in the script:
$themeName = "CACamilo.rwtheme";
Here you have to just replace the theme name with the theme you want to build the installer for (the filename of the theme).
That's all!
You will find two different installer scripts. If you know how to work with the command line you can take the script "install_commandline.pl" to install your default. Place the installer script in the Defaults folder (where also the Defaults.xml file is located). Now, start up the command line and type the command "./install_commandline.pl" and the script will install your default to the theme.
Building a self-working installer
To create a selfworking installer, you need the tool "Platypus" which can downloaded here:
http://www.sveinbjorn.org/platypus
1. Start "Platypus"
You will be presented the following window:
Now, do the following:
1. App Name: Enter a name for your installer
2. Drag n' Drop the script "install_platypus.pl" which you will find in the folder "Installer_Scripts" in the field "Script Path:"
3. Click on "Output: Text Window"
4. Click on "Show advanced options" and activate "Secure bundled script" and "Remain running after completion"
5. At the bottom you can add your default files to the application by clicking on the "+" button. You should add the following files and folders of your default: "css" (folder), "images" (folder) and "Defaults.xml" (file)
6. You can also add a custom icon to your installer by drag n' drop any image file on the custom icon field at the top left.
7. Click on the "Create" button and save your installer in the following "save"
Now, you have a full working installer for your default which can be shared with the public.
The installer also makes a backup of the actual theme during the install process on the user‘s desktop