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.

User Interface Customization

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 LESS / SASS / 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 minimal setup is already included in the template used by the custom theme generator. For a full example, see the bootstrap config file.

After establishing the basic configuration, you can add template and resource files to your theme. Understanding the structure and inheritance rules described below should help you achieve the desired effects.

What Should I Start Editing?

If you want to begin customizing your theme, a useful starting point is to identify a template that you would like to modify – good starting points are the header.phtml and footer.phtml files that define VuFind®'s default header and footer. Copy one of the files from your theme's parent theme into your own, edit the HTML, and see how things change when you access your site through a web browser.

As you do this, you will likely notice bits of code wrapped in “slots”. Slots are a view helper that makes it easy to override and customize content. You can learn all the ways to use them on our view helpers page.

<?php $this->slot('footer-left')->start(); ?>
    <p>Custom left foot(er)</p>
<?php $this->slot('footer-left')->end(); ?>
<?php include $this->parentTemplate('footer.phtml'); ?>

If you want to begin customizing your styles, you can create a brand new CSS file to override some defaults, and register it in your theme's module.config.php – or you can use the more advanced LESS technology to adjust some variables and recompile VuFind®'s core CSS with some local adjustments.

Looking at existing themes and templates should help give you some ideas about how to achieve the effects you need… and if you get stuck, please feel free to reach out to the VuFind® community for help through the channels listed on our support page.

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.
  • less - This directory contains LESS files, often used to generate a compiled.css file in the css directory (unless the theme only supports SASS; see below).
  • scss - This directory contains SASS files, made available as an alternative to LESS files for developers who prefer the SASS technology.
  • 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 Laminas' $this→headLink() helper (as opposed to inline HTML tags) when you need to include specific CSS files in your templates. 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.


VuFind® 4.1 introduced the concept of theme “mix-ins,” inspired by PHP Traits. A mix-in is a package of related templates and assets, very similar to a theme but containing only a subset of functionality. These packages can be “mixed in” to a theme by adding a “mixins” array to the theme's theme.config.php file.

The directory structure and configuration for a mixin is identical to that of a theme – mixins can contain templates, Javascript, CSS, etc. and may define view helpers and other settings. There are only two key differences:

1.) The configuration for a mix-in is called mixin.config.php, not theme.config.php.

2.) A mix-in may not extend anything, nor may it include additional mix-ins.

VuFind® ships with a sample mix-in called local_example_mixin, which simply causes an alert box to appear on every page as a proof of concept. You can use the mix-in code generator command-line tool to create copies of this example as a foundation for your own mix-in work.

Why Use Mix-Ins?

The average VuFind® user will probably not have much need to use mix-ins; however, this feature is useful for sharing functionality between VuFind® instances. By creating a Laminas module full of custom code and a theme mix-in containing custom templates and assets, it should be possible to isolate entire custom features and share them between institutions without having to significantly change core VuFind® code.

Mix-Ins and Inheritance

Note that when you load a mix-in into a custom theme, the custom theme's templates and other files take precedence over the mix-in's. This allows you to load and customize a mix-in. However, it means that you cannot load a mix-in into an existing theme and overwrite that theme's behavior. The expected way of using mix-ins is to create a new custom child theme that extends an existing core theme, adds mix-ins to it, and then locally customizes those mix-ins as needed.

Icon Libraries

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

The Creating Themes video provides an introduction to VuFind®'s theme system.

development/architecture/user_interface.txt · Last modified: 2024/04/24 18:14 by emaijala