Collective.xdv works by compiling the information from your theme.html template, your rules file and your Plone content into a brand new page.  Static files forming part of your theme, such as CSS, JavaScript and images, get pulled into the page after this compilation has taken place. As a result, your web server needs to know where to find these resources - it isn't automatically aware of the theme directory you set up to hold your template and rules.

In a production environment, you'll probably have Apache, Nginx or some other web server sitting in front of Plone and Zope, and, with the correct configuration, this will take care of making the static resources available to your compiled page. However, on a development computer - perhaps your own PC or laptop - you're probably more accustomed to just use Zope itself as the web server. In this case you've got several options for making your static resources available to your compiled page.

1. The Quick and Dirty

Your simplest option is to drop your resources into the Custom folder in portal_skins. Your Plone site will then find these resources through a simple relative link (such as href="test.css"). The disadvantage to this of course is that it's much harder to move these resources from site to site - and there's always the risk of losing them if you accidentally delete a site.

2. The Reflecto Method

Products.reflecto is a third-party add-on product which allows you to expose a section of your file system as if it were Plone content. In this case then, you can drop your static resources into a directory alongside your theme.html template, and work with them on the file-system. Once you've installed reflecto and set up a reflector content item to point at your static resources directory, your images and other files will be served just like any other piece of content in your Plone site.

3. The Slightly More Complicated

A more daunting option - particularly for the average web designer - is to set up a web server in front of Zope and Plone on your development instance and serve the static resources through these. In fact, it actually isn't as hard as you think to run a web server for development purposes. If you have a Mac running OS X.5, then the next page, Apache on your Mac, will take you through the basics. If you are running Windows, or a flavour of Linux, then many of the configuration details will be the same, but you will probably need to install Apache first.

4. The Hybrid Approach

This approach combines a traditional Theme Product Package with collective.xdv. It may well appeal to those designers schooled and seasoned in the old Plone 3 theming methods. Indeed, as an advanced technique, it combines the best of both worlds, in that Plone's registries can be used to cache resources or set conditions on when they are used. Other configuration details which might be required can also be embedded in this product. Denys Mishunov's Advanced XDV Theming tutorial will walk you through this technique.

Apache comes ready installed on a Mac, so it is reasonably quick and easy to set it up to serve up static resources for your collective.xdv theme. This configuration is intended for development purposes only and simply configures Apache to deliver your Plone site via http://localhost/ (i.e. through port 80) and to deliver your images, style sheets and JavaScript via http://localhost/staticresources. You'll still be able to get to plain vanilla Zope and Plone through http://localhost:8080 and http://127.0.0.1:8080.

Configuration

First we need to locate and edit Apache's configuration file - httpd.conf. If you're going to do this via the easy route using Finder, you'll first need to reveal invisible files. Ironically, the quickest way to do this is to use a terminal window:

defaults write com.apple.finder AppleShowAllFiles Yes

Relaunch Finder - Apple Menu > Force Quit > Finder and you should then be able to see a folder at the root of your Mac's hard disk /private/etc/apache2 containing the main Apache configuration file - httpd.conf.

To be on the safe side, make a back-up of httpd.conf and then open the original httpd.conf with a text editor. First, we're going to make Apache only respond when you type http://localhost in your browser address bar. Scroll down a few lines until you see

Listen 80

replace this with

Listen localhost:80

We're making this change on the assumption that you're setting the configuration up for development purposes only. For a deployment server you would leave this line as it is.

Next, we're going to tell Apache to deliver your Plone site and your static resources via http://localhost. Head down to the section marked #main server configuration and add these three lines:

RewriteEngine On
RewriteRule ^/staticresources/?(.*) - [L]
RewriteRule ^/(.*)$ http://localhost:8080/VirtualHostBase/http/localhost:80/[your plone site name]/VirtualHostRoot/$1 [L,P]

• it doesn't matter much where you add this, except make sure you don't insert it inside another directive. I slipped mine in just before the #Default type section.
  
• [your plone site name] is the name of the plone site you're working on. If you're working with the site created by the default installation, then this will be Plone.

Save the file, you'll probably have to type your password.

Now add your staticresources folder. Using Finder, go to /Library/Webserver/Documents on your Mac hard disk and add a folder there with the name staticresources.

Note this is the Library at the root of your Mac hard disk, not the Library in your own user folder

Running the Server

Start Zope/Plone in the usual way. Then open a terminal window to check your configuration file:

sudo apachectl checkconfig

or

sudo apachectl -t

will check that the configuration file you've just altered is OK, you can then start the server:

sudo apachectl start

will start Apache.

Note sudo apachectl stop will stop the server. If you make a change to your httpd.conf file, you'll need to restart Apache (sudo apachectl restart) to reload the configuration.

Now go to http://localhost/ in your browser - if everything is working you should see your Plone site. Next go to http://localhost/staticresources/ - you should see a directory listing of your staticresources folder.

Engaging your static theme

The next job is to tell collective.xdv to deliver your Plone site wrapped in your static theme through the domain http://localhost (rather than localhost:8080). Access your site via http://127.0.0.1:8080 to get the plain vanilla version and go to Site Setup - Theme transform. In the Domains box, add:

locahost

Once you've made sure that your theme transform is switched on and saved your changes, refreshing http://localhost/ in your browser should now deliver your site wrapped in your static theme.

Finally test out your staticresources folder by dropping a css file into it. Remember this folder can be found in /Library/Webserver/Documents on your hard disk. Add a link to this CSS file in the head of your theme file, the href attribute should look something like this:

href="/staticresources/test.css"

Make sure that your compiled theme will pick this up by double-checking that, in your rules file, you aren't completely replacing the head tag with the head tag generated by Plone (you'll need a prepend or an append rule to combine the Plone head tag with your theme head tag).

Variations

The above is the quick and dirty approach - designed to get you up and running as quickly as possible with minimum changes to the Apache configuration provided with your Mac - but there are other things you can do.

Relocating your Static Resources

You might want to change the physical location of your static resources on your hard disk. In that case, look for the DocumentRoot directive (and its corresponding Directory directive) in httpd.conf and edit these entries to point to your chosen folder.

Multiple Sites

If you want to see more than one Plone site through Apache, then try replacing the VirtualHost rewrite rule in your httpd.conf with this:

RewriteRule  ^(.*)  http://localhost:8080/VirtualHostBase/http/localhost:80/VirtualHostRoot/$1 [L,P]

You'll then need to type http://localhost/[your Plone site name]/ to see your site, but there will be no need to change the links to your static resources in your theme file. One important thing to note: if you use collective.xdv while running Zope in debug mode, you can have as many rule and theme files as you do sites on localhost  (the rules and theme are compiled with every request). This is very convenient for development purposes, if, for instance, you have two projects running at once. However, this doesn't translate into production mode. With debug turned off, you are limited to one set of rules and theme files per domain. This is because the rules and theme are compiled once, when the Theme transform is switched to 'On', and then cached.

Starting and Stopping Apache

It's possible to start Apache via your System Preferences panel, go to Sharing and then turn on Web Sharing. Your Mac will tell you that users of other computers can view web pages in the Sites folder on your computer, however, this won't be the case because we've set Apache to listen for localhost:80 only. Set your httpd.conf file back to Listen 80, if you want other people to access your pages.

Once you have your static resources set up to be delivered by a webserver like Apache, you have the power to apply variations to the same theme for different Plone sites.

Set up your Sites

To try this out, add a second Plone site to the root of your Zope Management Interface. Install the Theme Transforms Add On and, via Site Setup - Theme transform, add the same domain, theme and rules as your first Plone site.

Next, assuming that your static resources live in a folder on your hard disk called staticresources, edit the entry in the Absolute URL Prefix box in Site Setup - Theme transform to read:

http://localhost/staticresources/greensite/

Finally, go to your original Plone site and edit the Absolute URL Prefix box on that site to read:

http://localhost/staticresources/redsite/

Set  up your Theme

Now, make the links to your static resources in your theme file relative rather than absolute. 

href="test.css"

Turning to the staticresources folder on your hard disk, add a folder called greensite and drop a test.css file into it. Then add a folder called redsite and drop a slightly different version of test.css into that one.

Tweak Apache

You'll need to tweak Apache so that both sites can be seen through http://localhost. Follow the instructions in the variations section of Apache on your Mac to make a slight change to the rewrite rules in the httpd.conf file. Don't forget to restart!