How to use RapidWeaver 5 Resources

RapidWeaver 5 introduces a new and improved way of working with files used in your site - Resources. As this feature replaces the previous page Assets folder, users may notice a few changes in their site. This guide is designed to help you update your site using the new Resources feature.

Where are Resources stored in relation to my site?

Unlike in RapidWeaver 4.x, Resources in RW5 are stored in a global resources folder, called 'resources', found at the root of your site.

This means that if your site were http://www.realmacsoftware.com, your resources are uploaded to http://www.realmacsoftware.com/resources/. As you add files and folders to the Resources area these are all contained within the resources folder.

If you're wanting to link to a resource, you can do it in a number of ways.

Existing Sites That Previously Linked to Assets Using the RW Add Link Sheet

As links via the Add Link sheet are tracked to a particular asset, when you upgrade your project file in RapidWeaver 5 the links to the resources are tracked. This means that, when you re-publish your site, the links to the new Resources are updated and you're all set to go. If you don't use any custom code to link to assets, or hand-code links to assets, your site should continue to display just fine after uploading it with RapidWeaver 5.

Existing Sites That Manually Linked to Assets

To ensure that users are able to use resources in RapidWeaver 5, we added a new way of pointing to files. There's three ways you can point to files in your code. Two of them are similar to RW4 - the third is all-new for RW5.

1. Use an absolute URL: e.g. http://www.realmacsoftware.com/resources/my-image.jpg
   
2. Use a 'Relative to DOCROOT' URL: e.g. /resources/my-image.jpg - this may not work on all servers
   
3. Use the new %resource()% macro - this is new in RW5

How to Use the new Resource Macro

The resource Macro is designed to allow users with custom code to use a quick, consistent way to link to resources - regardless of how nested their pages are in the site.

To start using it, simply use the following code. You should replace 'my-image.jpg' with the name of the file you're wanting to link to.

%resource(my-image.jpg)%

If a resource is in a resource folder within the Resources sidebar area, add that to the path also:

%resource(folder/my-image.jpg)%

So, in your custom CSS you would use it as such:

#header {
    background-image: url(%resource(my-image.jpg)%);    
}

This %resource()% macro is particularly important if you wish your custom code to work in RapidWeaver's Preview mode. When RapidWeaver finds a %resource()% tag in the page, it'll not only expand the link correctly depending on whether you're previewing or publishing the page, it'll also ensure that RapidWeaver exports the resource to the relevant location such that the resource is then available in RapidWeaver's Preview area. If you wish to use Custom CSS that works in Preview mode, you must use the new Resource macro.

Why Does RW5 Not Automatically Update My Code?

There's no way for us to know whether custom code (which the user themselves wrote) actually refers to an item added as an asset, and there's no reliable tracking of the file in 4.x. Whilst developing 5.0 we considered the possibility of doing a global find / replace on your document to try and avoid this: however that doesn't have any guarantee that an asset is part of the project file (and thus migrated to be a Resource in 5.0). Building the link between a bit of custom CSS and the document structure is actually pretty hard to do reliably and on a large scale. We're deliberately not offering any potential migration because users are happier to migrate things themselves than have a machine try to do it for them...

We fully appreciate it's a pain to have to make these changes, however if a site is already live with the custom CSS and assets, because RW doesn't move things on the server the existing files will remain online and thus the code will work - albeit only when you visit it live - not in RapidWeaver's Preview area.

The new %resource()% macro was brought in because it's used by RapidWeaver to ensure three things:

1. When you preview a page in RW, RW builds the link to the resource
   
2. it also ensures that the resource is copied to the preview location so that the user can actually use it when previewing the site
   
3. It also ensure that when exporting and publishing the link to the resource (which is different from Preview in-app) is correct.

It means that no matter how nested the user's page is, the code for putting a resource is exactly the same - RW figures it out.