Blog Be Nimble

RapidWeaver - A Word on Page Assets vs Sitewide Resources

With the recent release of RapidWeaver 5 what used to be known as "page assets" is now known as "sitewide resources", and since the two behave quite differently I thought it would be a good idea to describe how each works, so you can adjust accordingly when upgrading from RW4 to RW5. This explanation will mostly benefit those who use snippets or otherwise hand-type code to access assets/resources.

In RapidWeaver 4, any files you add via the Page Inspector --> Header --> Assets section are kept separate from other pages in your website. In most cases this isn't a problem, as RapidWeaver by default puts each page of your website in its own folder. This means (if you don't change anything) that the files you add to a page can be accessed by referring to the "assets" folder. Easy, right?

The problem with this approach is that it can cause confusion when you restructure your website. For example, let's say you put several related pages into the same folder. Since each page can have its own assets, RapidWeaver has to keep track of which files belong to which page. Therefore, in RapidWeaver 4, the "assets" folder is renamed to pagename_assets for the pages that share the same folder. Let's see this in action to make sure it's completely clear:

Say you have a photos page with pictures from your recent vacation. The URL on your website for that page may look like this:

http://www.example.com/vacation/photos.html

And let's also say you made a diary of your vacation and put it here:

http://www.example.com/vacation/diary.html

In this example, the two pages (photos.html and diary.html) share the same folder (vacation). In RapidWeaver 4, in order to keep each page's assets separate, the assets folder would be renamed to photos_assets (for the photos.html page) and diary_assets (for the diary.html page). Make sense? (If not, don't worry, this has confused a lot of people.)

Fortunately, RapidWeaver 5 does away with "page assets" and instead uses "sitewide resources". This is a tremendous improvement, as it means you can access the files you add to your website from anywhere you want. Adding files to your website is also much easier - you can just drag and drop any files into the Resources section of the RapidWeaver sidebar. You can also use the "Add Resources" button in the upper left of the RapidWeaver window.

To make things even easier, RapidWeaver 5 allows you to access any of the files in sitewide resources by using this macro: %resource()% This special syntax tells RapidWeaver that you want to use a file in the sitewide resources, and RapidWeaver then figures out the path to that file for you.

So, how do you use the %resources()% macro? First, find out the filename for the file you want to use. Then, insert that filename in between the parenthesis of the macro, like so: %resource(image.jpg)%. If you've added an entire folder to sitewide resources, and want to refer to a file inside that folder, just include the folder name as well, like so: %resource(folder_name/image.jpg)%.

In summary, when switching from RW4 to RW5, you may have some code snippets that refer to page assets like this:

assets/image.jpg> --> RapidWeaver 4 syntax

When switching to RW5, just change such sections like so:

%resource(image.jpg)% --> RapidWeaver 5 syntax

Another thing I'd like to note here - when opening a RW4 project in RW5, any files you originally added to page assets (RW4) will automatically be moved to sitewide resources (RW5). When doing so, RapidWeaver will create a folder in sitewide resources named after the page where the assets were initially added. This makes more sense when you see it in action, so just be sure to browse the files and folders in Resources section of the RapidWeaver 5 sidebar if you're not sure where everything is.

Hope this helps - be sure to leave any thoughts or questions in the comments below.