Syntax Tags found in html template files will be replaced with actual content when the page is published or exported by RapidWeaver. The tags can be placed anywhere within the template html file. A RapidWeaver Syntax Tag looks like this:
For example, the %content% tag for the main content of the page anything in the main window in RapidWeaver will be inserted here.
The %sidebar% refers to the Sidebar area in the Page Inspector, again any text or images entered into the Sidebar in RapidWeaver will be converted to HTML and will replace this tag in the template html file.
The following is a list of supported template tags for RapidWeaver Classic. Most of these tags can be used anywhere inside of RapidWeaver.
%header%
This outputs the meta information for each page. It should be placed between the <head>tags in your template file.
%title%
Outputs the title of the current page.
%user_header%
Allows the user to place any custom code into the header of the page.
%style_variations%
Outputs a series of style sheets into the head of the page, as selected by the user via theme styles tab of the Page Inspector.
%user_styles%
Outputs the users custom CSS into the head of the users page.
%user_javascript%
Outputs the users custom javascript code into the head of the users page.
%plugin_header%
Outputs code generated by the selected page type into the header area. Typically it will be javascript and/or css.
%navigation%
Outputs the site navigation as an unordered list. Replaced %toolbar% , which was deprecated in RapidWeaver 6.0.
%top_navigation%
Outputs an unordered list of just the top-level of the page hierarchy.
%sub_navigation%
Outputs an unordered list of the remaining sub-navigation of the hierarchy, and respects the RWAlwaysDisplayFullNavigation key.
%site_title%
Outputs the site title
%site_slogan%
Outputs the site slogan entered in the Site Setup area.
%logo%
Outputs a user definable site wide image. This is set via the Site Setup area, and RapidWeaver does not pre-flight the images the customer may select for their size. Depending on how you’re using this tag, you may want to apply some sensible maximum size for the image via CSS.
%content%
Outputs the content of the current page.
%sidebar_title%
Outputs the sidebar title as entered in the Page Inspector.
%sidebar%
Outputs the sidebar content as entered in the Page Inspector.
%plugin_sidebar%
Outputs content specific to the current page style. For example, the blog archives.
%breadcrumb%
Generates an unordered list of links from the home page to the current page following the menu hierarchy in the Page List.
%footer%
Outputs the site’s footer as entered in the Site Setup area.
%pathto(file.extension)%
The %pathto()% syntax should be used to refer to any global assets in the theme. This will generate the appropriate relative, absolute or relative to DOCROOT link to the relevant file. Its primary use is to refer to stylesheets and javascript files that are used across the site.
%pathto()% can be used for any file (styles.css for example), however the file must be added to the RWCopyFiles array in the theme.plist file.
%base_url%
Outputs the web address of the website, as entered in the Site Setup area.
%last_published%
Outputs the last published date - this is not currently customisable in its appearance.
%email%
Outputs the user’s e-mail address.
Colourtags
Colourtags allow customers to customise a particular colour value in your theme using the OS X colour picker. The colour values from a colourtag must currently be set via a separate stylesheet (normally called colours.css or colourtags.css) This style sheet must be included in the RWColourTagCSSFiles array in the theme.plist, to indicate to RapidWeaver that the colours should be substituted.
%colour…%
Each tag (i.e. %colour_header_background%) used be replaced by a colour specified in the theme.plist There are no restrictions placed on the number of colour tags you can use, and you may also use the same tag multiple times. As noted above, all colourtags need to be placed in a specific stylesheet, and explicitly referenced in your theme’s PLIST.
Colour tags will be replaced by a colour specified in the theme.plist. This should be placed in an external style sheet. The style sheet should be included in the RWColourT- agCSSFiles array in the theme.plist. There is no restriction on how many colour tags you can use. You may also use the same tag multiple times. This tag also supports the Americanized spelling of colour, color.
Colour tags support the following mathematical operators: +, – and *.
Example 1: %COLOUR1 + #112233%
Example 2: %COLOUR1 * 0.3%
Example 3: %COLOUR1 + #112233 * 0.3 + #445566%
Example 4: %COLOUR1 + R(0.9) G(0.1) B(0.5)%
All RapidWeaver Syntax Tags, with one exception, look exactly the same. The exception is the %pathto(file.extension)% tag. This tag is used for site consolidation, essentially meaning that RapidWeaver will automatically generate links to files located in the theme folder. When exporting a site RapidWeaver places all of the theme files in a folder called rw_common and gener- ates the links to the files in this folder. This should be used when linking to any file in your theme file including stylesheets, javascript files and images. Examples: Linking to the styles.css file in your theme directory.
%pathto(styles.css)%
the published code will look something like this:
../rw_common/themes/theme_name/styles.css
Folders can be included before the image name eg.
%pathto(images/image_name.jpg)%
The published code will look something like this:
../rw_common/themes/theme_name/images/image_name.jpg
RapidWeaver 7 and newer supports the use of the new %banner_image% and %banner_path% keys. To enable the use of a banner image in your theme, you must set the RWThemeSupportsBannerImages boolean to YES in your theme’s Info.plist.
The Theme.PLIST file will not be used when determining whether to enable the Banner Image feature. With the PLIST key in your theme, and the %banner_path% key in either your index.html or stylesheets, you’ll get a path to the image that can be used as you wish. If you add %banner_path% either to your theme HTML or CSS, the following will be inserted:
In an HTML file
<img src="%banner_path%" />
becomes
<img src="rw_common/images/banner.png" />
and in a CSS file
becomes
If the user does not provide a banner image, you should provide a path to your own using the key RWThemeBannerFallbackImage in Info.plist. This is relative to your other theme files. You can suggest a height and width for the banner which will be displayed in the RW settings screen using the following keys:
RWThemeBannerImageRecommendedWidth
RWThemeBannerImageRecommendedHeight
All banner configuration keys must be within a RWBannerOptions dictionary plist
You can also use the %banner_image% macro to request an image element:
<img src="%banner_path%" id="rw-banner-image" height="" width=""/>
It’s important to note that height and width attributes will be those of the asset added by the user - not the recommended height-width integers you enter into the Theme‘s Info.plist. The alt attribute can also be placed with the %banner_alternate_text% token.
RapidWeaver uses a theme.plist file to gather all the information it needs about the theme.
The Theme.plist file is a standard xml file, meaning, if you have the developer tools installed, you can use Apple’s Property List Editor to create and edit your themes plist.
These tags are displayed in alpabetical order. Large dictionaries such as RWStyleVariationsand RWTextToolBar can be found in their own categories.
RapidWeaver 6 added a new RWAddonSupportURL key in the theme PLIST. This key is required for all themes and should be a website address that customers can visit for support with the theme.
If colour style groups are added RapidWeaver needs to know which file(s) are to be processed for colour tag conversion. Add the following array to the root dictionary.
The RWCopyFiles array is a list of files and folders that are to be copied when the website is published. It should be placed in the root directory.
The RWExportFiles array is a list of items to copy over and process when the site is built. These files can contain any of the theme syntax tags, which will be replaced with the site values on export. It should be placed in the root directory.
This dictionary contains all the style variations to eb included with the theme. For more info see the chapter RWStyleVariations on page 96.
The RWTemplateHTML key sets the file to use as a template. This is the file that RapidWeaver will use a base for all pages in the site. It should be placed in the root directory.
The RWTextToolbar dictionary contains all the relevant keys to build a toolbar. It should be placed in the root directory.
The RWThemeAuthor key sets an author name for the theme. It should be placed in the root directory.
The RWThemeCapabilities key sets which new features are supported by your theme. It is a dictionary that is placed in the root directory.
Th RWThemeDisplayName should be placed in the root directory and localized for each language you want to support.
The RWThemeImage key sets the file to use for the preview in theme drawer. This file should be 115 pixels wide and 125 pixels high. The key should be placed in the root directory.
The RWThemeImage key sets the file to use for the preview in theme drawer. This file should be 800 pixels wide and 950 pixels high. The key should be placed in the root directory.
The RWThemeKeywords adds keywords specific to your theme. It should be added to the root directory. Authors can add as many keywords as they wish, however they should be kept relevant to the theme. Note: It is not necessary to add the author name, theme name, theme display name or theme short name as these are searched for automatically from the existing keys in the theme.plist. Adding such keywords will devalue the theme search feature.
The RWThemeName key names your theme. Make sure the name doesn’t clash with any other theme names. It should be placed in the root directory.
The RWThemeShippedInVersion key specifies which version of the RapidWeaver the theme was originally shipped with. This key is private and only used for official RapidWeaver themes.
The RWThemeShortName sets a name used when publishing a site. It should not contain any special charac- ters of spaces. It should be placed in the root directory.
The RWVersion keys sets a version number for your theme. If two or more themes named the same are in- stalled RapidWeaver will use the most up-to-date version. It should be placed in the root directory.
RWStyleGroups
The RWStyleGroups holds an array of all the style groups associated with the theme. It should be placed inside the RWThemeVariations dictionary.
The GroupDisplayName dictionary is located in the RWStyleGroups array and localizes the variation group display names in to each language. A key should be created for each language you wish to support.
The GroupMembers key holds all the members of each style variation group. It is a key value for each item in the RWStyleGroups array.
The GroupName sets a group display name. It is a key value for each item in the RWStyleGroups array.
The GroupSelectionLimit key sets a selection limit for each variation group. It is a key value for each item in the RWStyleGroups array.
The DisplayName key is located in each item of the GroupMembers array and localizes the display name for each variation option. Again, a key should be created for each language you wish to support.
The Enabled key sets whether or not the variation should be selected by default. It is a key value for each member of a style variation group.
The Files array gives a list of files to be added when the variation is selected. It is a key value for each member of a style variation group.
The Name key sets a name for the variation. It is a key value for each member of a style variation group.
The Type key sets the type of variation. It is a key value for each member of a style variation group. RapidWeaver 3.6 introduced a color type, previously Stylesheet was the only type of variation available.
This is the default colour to be applied to the specified tag.
The DisplayName key is located in each item of the GroupMembers array and localizes the display name for each variation option. Again, a key should be created for each language you wish to support.
The Name key sets a name for the variation. It is a key value for each member of a style variation group.
This is the tag to be used in the colourtag.css file to link the colour picker in RapidWeaver to the stylesheet.
Type
The Type key sets the type of variation. In this case Colour defines the variation.
To add colour styles to your theme it needs to be added to the RWStyleGroups array in the same way as an original variation group with the exception that GroupSelectionLimit is not required.
To add a colour style you should add the following to the GroupMembers array of the colour style group dictionary. Adding support for localisation is an (recommended) option, more information is available under the 3.5 & above keys section of this document.
The RWAlwaysDisplayFullNavigation key set whether the entire menu should be output on every page or if only the current page’s child items should be displayed. It is a key value of the RWTextToolbar dictionary.
The RWBreadCrumbItem key sets the output for each item in the unordered list for bread-crumb navigation. It is a key value of the RWTextToolbar dictionary.
The RWBreadCrumbItemSeparator key defines the characters used to seperate the list of breadcrumb items. If you are using special characters here it is best to escape them to XHTML entities.
The RWSupportedLevels key sets how many levels of navigation the theme officially supports. It is a key value of the RWTextToolbar dictionary.
The RWToolbarItemCurrent sets the output for the current page in the unordered list for main navigation. It is a key value of the RWTextToolbar dictionary.
The RWToolbarItemCurrentAncestor key styles each parent level of the menu with a currentAncestor CSS class tag. It is a key value of RWTextToolbar.
The RWToolbarList key sets the opening and closing tags of an unordered list for main navigation. It is a key value of the RWTextToolbar dictionary.
The RWToolbarItemNormal sets the output for out each item in the unordered list for main navigation. It is a key value of the RWTextToolbar dictionary.
RWSupportsContentOnlySubPages
The RWSupportsContentOnlySubPages key is located in the RWThemeCapabilities dictionary and allows RapidWeaver to create content only sub pages. Used for coherent site design. It is part of the RWThemeCapa- bilities dictionary.
Theme variations was a major feature added to RapidWeaver 3.2. It allows the users to mix and match pre-set variations in your theme.
RWSupportsDisplayName
The RWSupportsDisplayName key is located in the RWThemeCapabilities dictionary and tells RapidWeaver that the theme supports localized display names. It is part of the RWThemeCapabilities dictionary.
RWSupportsPathTo
The RWSupportsPathTo key adds support for site consolidation. It is part of the RWThemeCapabilities dictionary.
The RWSupportsToolbarRelTag key adds support for the “rel” tag being added to toolbar link items. It is part of the RWThemeCapabilities dictionary.
So you’re interested in designing your own theme for RapidWeaver Classic? You’ve arrived at the right place!
Before you start developing or modifying a classic themes, you need to make sure you have RapidWeaver Classic installed. You can .
You’ll also need a text editor. from Panic is great and provides syntax highlighting which makes reading large amounts of code infinitely easier.
Anyone can build or modify a theme for RapidWeaver. You’ll just need a basic understanding of HTML and CSS to get going.
RapidWeaver Classic
A code editor
A JSON/Plist editor (optional)
To get started . Once downloaded you can double-click to install it. If RapidWeaver is running, you’ll need to restart it for the theme to become active.
Once you have the theme installed, open RapidWeaver and create a new project. Find the Example theme in the Theme Browser, right-click on the theme preview and select “Show Contents”.
Tip: You can right-click any theme in the Finder and choose “Show Package Contents”.
This will reveal a Contents folder in the finder, inside are all the files required to construct a RapidWeaver theme. You should have the following files:
Theme.plist - an XML file containing the name and details of the theme
index.html - layout template file (HTML)
styles.css - base stylesheet (CSS)
colourtag.css - colour style variations stylesheet (CSS)
js Folder - contains the required javascript for the theme
images Folder - where all images for the theme are placed
css Folder - theme variations CSS files are located here
preview_large.jpg - 800x950px image/logo of your theme displayed in the theme drawer.
The index.html file contained in the theme folder is the framework for all your other pages to be generated from.
A themes index.html file follows a familiar structure that is common in nearly all modern web pages. This section aims to familiarise you with the template document.
The basic layout of the theme index.html should look familiar to you:
RapidWeaver will automatically set the language of the template index.html file based on the user’s preference. Your Template file should not include the lang attribute.
<html lang="en">
Instead, it should just include the opening HTML tag, like this:
<html>
The Syntax Tags found in the template file will be replaced with actual content when the page is published of exported by RapidWeaver.
The main content areas are distinguished by elements, each open and close tag contains a Syntax Tag. For example.
<div id=”content”>%content%</div>
The majority of the relate directly back to a text area in RapidWeaver, it should be obvious which tag corresponds to which area.
The tags can be placed anywhere within the template. To recap a RapidWeaver looks like this:
%content%
This is the tag for the main content of the page anything in the main window in RapidWeaver will be inserted here.
%sidebar%
This tag refers to the Sidebar Window in the Page Inspector, again any text or images entered into the Sidebar in RapidWeaver will be converted to HTML and will replace this tag in the .html file. A full list of tags can be found in the file.
All RapidWeaver Syntax Tags, with one exception, look exactly the same. The exception is the %pathto(file.extension)% tag. This tag is used for site consolidation, essentially meaning that RapidWeaver will automatically generate links to files located in the theme folder.
When exporting a site RapidWeaver places all of the theme files in a folder called rw_common and generates the links to the files in this folder. This should be used when linking to any file in your theme file including stylesheets, javascript files and images.
Examples:
Linking to the styles.css file in your theme directory.
%pathto(styles.css)%
the published code will look something like this:
../rw_common/themes/theme_name/styles.css
Folders can be included before the image name:
%pathto(images/image_name.jpg)%
The published code will look something like this:
../rw_common/themes/theme_name/images/image_name.jpg
Tip: All tags can also be used inside styled text areas in RapidWeaver. The %pathto(…)% tag is particularly useful should you want to include images or links to files inside your theme.
The Info.plist stores basic information about the Theme, such as its name, author, and version number.
It supports the following keys:
Here is an example of an info.plist from a standard theme:
RapidWeaver Classic offers a way for developers to offer theme updates via sparkle. Theme updates work exactly the same way as plugin updates have always done.
To take advantage of this feature you’ll need to add a SUFeedURL key to the Info.plist of your theme. The SUFeedURL key should reference the Sparkle RSS feed on your server.
When comparing releases, we’ll look at the CFBundleVersion field in your addon’s Info.plist file. If this isn’t increased, we’ll assume it’s not an updated addon. Apple has this to say about CFBundleVersion:
CFBundleVersion (String - iOS, OS X) specifies the build version number of the bundle, which identifies an iteration (released or unreleased) of the bundle. The build version number should be a string comprised of three non-negative, period-separated integers with the first integer being greater than zero. The string should only contain numeric (0-9) and period (.) characters. Leading zeros are truncated from each integer and will be ignored (that is, 1.02.3 is equivalent to 1.2.3). This key is not localizable.
When displaying the version string to users, we’ll use CFBundleShortVersionString . This isn’t used for calculating updates - it’s only used in UI. Apple has this to say:
CFBundleShortVersionString (String - iOS, OS X) specifies the release version number of the bundle, which identifies a released iteration of the app. The release version number is a string comprised of three period-separated integers. The first integer represents major revisions to the app, such as revisions that implement new features or major changes. The second integer denotes revisions that implement less prominent features. The third integer represents maintenance releases.
The value for this key differs from the value for
CFBundleVersion, which identifies an iteration (released or unreleased) of the app. This key can be localized by including it in yourInfoPlist.stringsfiles.
In most cases, you’ll want these to be the same value.
When comparing version numbers, no other fields are used. To be totally clear, do not use RWVersion in your Theme.plist file.
Plugins should also set the RWPluginAPIVersion field in their Info.plist and we’ll change certain behaviour based on their selection. This does not increment in line with the RapidWeaver release version.
If you’re unfamiliar with the XML AppCast format there’s some documentation on the Sparkle website, here: