About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

Site Tools


Warning: This page has not been updated in over over a year and may be outdated or deprecated.
development:architecture:user_interface

This is an old revision of the document!


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. You can use one of VuFind's built-in themes, or you can design your own. This page provides guidance and background information to help you make the most of VuFind themes.

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) was built with the jquerymobile library, but it was discontinued starting with VuFind 4.0. 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.

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.

The mobile_theme setting can also be used to default to a different theme when a mobile device is detected; however, with the advent of responsive design, mobile-specific themes are no longer as useful as they once were, and VuFind no longer includes a default mobile theme as of release 4.0.

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.

Configuring a Theme

The first thing you'll have to set up in a new theme is the file theme.config.php. This file allows you to establish your theme as a child of another theme (see the section below on Theme Inheritance for more on this) and allows you to add new CSS and Javascript files (among other things). If you've created custom view helpers, you will also set up their service manager configuration in this file. You only need to add settings here that wouldn't be loaded from a parent theme via inheritance (such as adding a new jQuery plugin).

A basic setup is already included in the custom theme template. For a full example, see the bootstrap config file.

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 - As described above, 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:

See also the Icon Set page for more icon-related discussion/notes.

development/architecture/user_interface.1501689382.txt.gz · Last modified: 2017/08/02 15:56 by demiankatz