This page refers to VuFind 1.x; for documentation on version 2.x, see User Interface Customization (VuFind 2.x) .

VuFind is developed using Smarty templates for HTML and CSS for design. Templates and CSS are bundled into themes, which are found in the web/interface/themes folder. You can use one of VuFind's built-in themes (blueprint, classic or default), or you can build your own. The theme used by VuFind is determined by the theme setting in the [Site] section of web/conf/config.ini.

The layout in the classic/default themes is controlled by the Yahoo UI CSS, which means that by modifying the class declarations within the HTML, you can modify the layout. For more information on how to use the Yahoo UI CSS, please see the Yahoo UI web site. The blueprint theme uses Blueprint CSS instead of YUI. Regardless of layout, to modify the colors and design elements, you can edit the styles.css file located in the css directory of your chosen theme.

All of the HTML is stored in Templates. There is one main template that controls the overall web site - the layout.tpl file stored in the root of your chosen theme's directory. Each module also has its own subdirectory in the theme where the individual templates for each web page are stored. They can be modified as needed.

Starting with version 1.0RC2 (or r1293 of the Subversion trunk), VuFind supports theme inheritance. With theme inheritance, you can set “theme” in config.ini to a comma-separated list of theme names, and these themes will be searched in order until a given template or CSS file is found. For example, “theme = MyUniversity,default”

The main benefit of theme inheritance is that it can make it easier for you to manage your local customizations. If you only need to change a few files, creating a separate theme for your custom versions makes it easier to remember exactly what you have changed. As the VuFind code evolves, you won't have to worry about copying templates for new features into your custom theme – inheritance will simply take care of them. The only time you need to worry about reconciling changes is when a template you have customized changes in the trunk, which should be a fairly infrequent event if your theme is simple enough. In the example above, suppose you just want to change headers and footers – you could put a new layout.tpl in your MyUniversity theme but leave everything else in default.

Note that theme inheritance is only one possible strategy for managing your themes. If you are planning something more complicated than the customization of a few files, you might find it helpful to read up on using vendor branches in Subversion as another possible approach to the problem.

The way CSS inheritance works requires a few notes. If you are going to take advantage of this feature, here are some important things to keep in mind:

• Always use the {css} Smarty function to include CSS files. If you don't use this function, CSS inheritance will not happen! The function takes two attributes as parameters:
  • media - the “media” attribute to use when including the CSS file (i.e. “screen” or “print”).
  • filename - the name of the CSS file to load. This must always be relative to the “css” subdirectory of one of your selected theme directories.
• In order for CSS files to load correctly, every theme's CSS folder must include the .htaccess file containing special rules for Apache. If you are creating a new theme including css, be sure to copy .htaccess from one of the existing themes or else your CSS files will not load!
• Watch out for @import statements in your CSS files. The target of the @import must be in the same theme as the caller. Inheritance cannot apply here since ”@import” is resolved by the client's web browser rather than the server-side logic. For example, suppose you customize styles.css and copy it to your MyUniversity theme. styles.css has an ”@import layout.css” statement in it. If you do not copy layout.css into your MyUniversity theme, it will not load at all – the user's browser isn't smart enough to find it in the default theme.

As of this writing, images do NOT follow the same inheritance rules as template and CSS files. Their paths are explicitly set, and many of them exist entirely outside of the theme folders. This may be worth revisiting at some point – an {image} Smarty function similar to {css} could be helpful. For now, though, be careful about using relative paths to images if you are not sure which version of a template or CSS file is going to be loaded.

This feature is not available prior to VuFind 1.1.

VuFind includes a {js filename='xxxx'} Smarty tag that works similarly to the {css} tag. The {js} tag will first go through the theme list searching for files in their js folders. If none of the themes contain the requested file, the web/js folder in the root of the VuFind install will be checked as a last resort. As a general rule, library-specific (i.e. YUI/jQuery) files should be stored inside themes, but generic “pure Javascript” files may be stored in the top level web/js folder to avoid redundancy.

Some of the graphics provided with VuFind's themes come from the Fugue, Silk and Tango icon libraries. For more information on licensing terms and to find additional icons for use in your local customizations, see these links:

• Fugue (Copyright © Yusuke Kamiyamane)
• Silk
• Silk Companion Icons
• Tango