This is an old revision of the document!
Table of Contents
User Interface Customization
This page refers to VuFind 2.x and later; for 1.x documentation, see User Interface Customization (VuFind 1.x).
VuFind uses a theme system to isolate the user interface from the business logic, and to make it easy to customize the software's look and feel. This page provides guidance and background information to help you make the most of VuFind themes.
Getting Started
Creating a Theme
Starting with VuFind 4.1, a command-line generator tool is available to create and configure a new theme using a simple example directory as the foundation. If you are using an earlier version of the software, you can still make use of this example by manually copying the files from GitHub into a new subdirectory of your VuFind installation's themes directory. The structure of a theme is described in more detail below.
Configuring VuFind's Theme Options
The theme setting in the [Site] section of config.ini controls VuFind's default theme.
VuFind also supports the ability to select from one of multiple configured themes, either through a parameter on the URL or through a drop-down control within the user interface. See the comments in config.ini above the alternate_themes and selectable_themes settings for more details on how this works.
If you use the command-line generator tool mentioned earlier, it will automatically set VuFind's default theme to your newly-created theme as well as turning on the theme selector so that you can switch back to VuFind's default theme. If you want other behavior, you will need to comment out or change the appropriate config.ini settings.
Technical Background
VuFind is developed using PHP templates for HTML and CSS for design. Templates and CSS are bundled into themes, which are found in the themes folder under VuFind's home directory.
Starting with release 2.4, VuFind's default theme (bootprint3) uses the Bootstrap library (version 3) for layout. Earlier versions had a different default theme (blueprint) using the Blueprint CSS library. The default mobile theme (jquerymobile) is built with the jquerymobile library. Many basic design elements (such as colors and font sizes) can be customized through small CSS modifications, even if you do not have a detailed understanding of these frameworks.
Theme Structure
Each theme has its own directory under VuFind's themes directory. Each of these directories contains a few important files and directories:
- css - This directory contains CSS files. All files within this directory can be accessed through the web server thanks to a rewrite rule in VuFind's Apache configuration.
- images - This directory contains images. All files within this directory can be accessed through the web server thanks to a rewrite rule in VuFind's Apache configuration.
- js - This directory contains Javascript files. All files within this directory can be accessed through the web server thanks to a rewrite rule in VuFind's Apache configuration.
- languages - This optional directory (supported starting in VuFind 2.5) can contain custom language files to override strings on a per-theme basis.
- templates - This directory contains PHP templates for rendering all of VuFind's pages. Most of these templates are named to correspond with controller actions within the VuFind application, though there are also some plugin-specific directories (i.e. Recommend, RecordDriver) and top-level layout pieces (layout/layout.phtml, header.phtml, footer.phtml).
- theme.config.php - This configuration file controls which resources (CSS, Javascript, etc.) are automatically loaded by all pages using the theme and which view helpers are available to the theme. It also specifies a parent theme when using Theme Inheritance (see below).
Theme Inheritance
Theme inheritance is the mechanism which allows you to override some or all of the elements of a theme without having to copy and paste the entire contents of the theme. For example, if you wanted to create a custom MyUniversity theme derived from the default bootprint3 theme, you would set the theme to “MyUniversity” in config.ini and create a MyUniversity directory under VuFind's themes directory containing a theme.config.php file setting the extends key to “bootprint3” in the configuration array.
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 main distribution, 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 new headers.phtml and footers.phtml files in your MyUniversity theme's templates folder but leave everything else in bootprint3.
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 more helpful to use Git version control as another possible approach to the problem.
CSS Inheritance
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 Zend Framework's $this→headLink() helper to include CSS files. If you don't use the helper, CSS inheritance will not happen!
- 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.
Image Inheritance
To take advantage of image inheritance, use the $this→imageLink() view helper.
Javascript Inheritance
To take advantage of Javascript inheritance, use the $this→headScript() view helper.
Icon Libraries
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)
See also the Icon Set page for more icon-related discussion/notes.