Adventures In Theming: Resources

This is the fourth post in a short series about the ideas, trials and tribulations of my first theme product. I’ll be posting the whole story in one place when the series is complete.

Resources

One of the parts of a theme that really sets it apart from the plone default, regardless of how similar it may be, are it’s resources. These include images, special templates, style sheets, etc.

In these uncertain times, there are different ways that resources are utilized, in the sense of a theme. The traditional "skins directory" still applies. Also at our disposal is the Zope 3 concept of a resource, and a resource directory.

In the first case, ZopeSkel has wired up some convenient places for us to put resources. If you look in the skins directory under your theme product, you’ll see three subdirectories, my_theme_custom_images, my_theme_custom_templates, and my_theme_custom_styles. The purposes of these directories is pretty obvious. You put files relating to the directory name in these directories. Images go into my_theme_custom_images, templates into my_theme_custom_templates (you may recall this is where we put main_template earlier), and CSS style sheets into my_theme_custom_styles.

The primary purpose of the skins directory is to override existing plone resources. When a url is being looked up and acquisition is happening in a plone site, the skins directory is the last place checked. This of course doesn’t limit the skins directory to this purpose. You can put anything there, and acquisition will find it. If you need to use DTML in your CSS, you’ll want to put it here.

The Zope 3 WayTM of handling resources utilizes ZCML registration. You add some tags to your configure.zcml file, and you can access resources via a special URL. This is useful for brand new resources that you aren’t overriding or probably won’t want to override in the future.

I’m going to use both resource approaches to style my theme.

Images

I’ve chopped up the PNG I posted earlier into the necessary bits and pieces for the theme, and I need to put them somewhere. I’ve opted to do this in the Zope 3 style, since these resources are specific to my theme and aren’t likely to ever be overridden. And if they are, this will likely happen via a filesystem product. ZCML resources can be overriden only by more ZCML, so this works out nicely.

Browser resources are established by using a <browser:resourceDirectory> tag. You specify the directory where your images are located, give it a name that’s unique across your Zope instance, and you can pin it down to a specfic layer via a marker interface.

Good news everyone! ZopeSkel has already done this for us.

src/my.theme/my/theme/browser/configure.zcml

...
  <!-- Zope 3 browser resources -->

  <!-- Resource directory for images -->
  <browser:resourceDirectory
      name="my.theme.images"
      directory="images"
      layer=".interfaces.IThemeSpecific"
      />

  <!-- Resource directory for stylesheets -->
  <browser:resourceDirectory
      name="my.theme.stylesheets"
      directory="stylesheets"
      layer=".interfaces.IThemeSpecific"
      />
...

So I just need to put my images into src/my.theme/my/theme/browser/images. Accessing the images gets a little weird, due to the special url convention that Zope 3 uses to locate resources.

To get to one of the images in your images resource directory, you add ++resource++ to any url relative to your plone instance, followed by the name specified in the ZCML above and the name of the image, for example: localhost:8080/plone/++resource++my.theme.images/left_background.png

You’ll notice that it also sets up a resource directory for our style sheets. Nice.

You can also register resources individually, which makes it easier override them individually via ZCML later on (I haven’t done this myself yet, but it’s possible).

Advertisements
This entry was posted in Uncategorized and tagged . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s