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.

Video 3: Creating Themes

The third VuFind® instructional video discusses the process of creating your own theme, and shows you how to do some commonly-needed customizations.

Video is available as an mp4 download or through YouTube.

  1. Example theme files used in the video: tutorial-theme.zip


Hello! I'm Chris Hallberg and today we're going to discuss how to make a new theme in VuFind! Now that we have set up VuFind in the previous videos it's time to make it look like your institution's theme and style it to be all your own. VuFind comes with a few different themes, the default theme that you're seeing here is called bootprint3. We'll get to why it's called that in just a second. VuFind comes with three themes that are designed to be a good jumping-off point for you to do your own customizations, so we're going to talk about how to switch those and make your own in this video.

So I'm going to open up the back-end of VuFind. I have in VSCode here, this is the VuFind folder that we've been working on in the previous videos on the same virtual machine. I just thought a visual look at the folders might be an easier way to go about this. Right now I am currently in “local/config/vufind/config.ini”. This file should exist, if not you'll want to make a copy out of “config/vufind/config.ini”. This is the config file that contains all the basic configurations. One of the sections of this configuration, at the top, is called [Site] and this is where the overall configurations for where the site is, what email address gets the feedback and the support messages, the title, and one of the first things should be the theme. You can see right now bootprint3 is the enabled theme.

I'm going to switch over to bootstrap3 which is a more blank template for you to start your theme on. This is obviously built-in Bootstrap 3 and uses as many stylings of that framework as is reasonable and this is the blankest template that VuFind offers. Bootprint3 that we just switched from is takes some of the original stylings of legacy VuFind and adds them on top of bootstrap3 and, finally, the newest theme that we have is called sandal. We do have a boot and shoe pun going on this is a more modernly styled theme to match the trends of the last two years or so and there should be a brand new theme coming out later in 2020 to match the stylings and the accessibility and modern design practices of the current day.

Another option that you have is you can specify a mobile theme. This isn't as common now that responsive design is a larger thing but if you want to serve a particular theme just to mobile users this is the way that you can configure that. I'm going to scroll down a little farther to two useful things for developers: “alternate_themes” and “selectable_themes”. I'm going to uncomment these. “alternate_themes” allows you to specify like shortcut IDs for different themes so you can switch back and forth between them by using URL parameters. So I'm going to put on these two for now just to show how this works. Now if I go back and I do “?ui=bs3” it'll switch my theme over to bootstrap3 and I can also switch to bootprint3. This is very useful.

It can get even easier if you go a little further down to selectable themes you can actually give yourself a drop-down they'll make this even easier. So, now there's a theme drop-down in the top bar that allows you to do the same kind of switching. This is also useful if you want to present to your users with different UI is such as larger text or higher contrast or things like that. That's one way to enable that feature.

I'm going switch to Bootstrap and we're going to look at how themes are structured inside of VuFind. If you go back to the roots of the VuFind instance and you go to themes you'll see a bunch of different folders of all the different themes that we have. I'm gonna open up bootstrap3. You'll see it's broken down into several different folders. These are mostly self-explanatory. One that is missing here is languages if you wanted to do a custom language file to add particular strings to just a certain theme you can do that. The most important file in this folder is the theme.config.php. This file tells VuFind what customizations you want and what files to include on every single page. There's a few other option more advanced options down here that we're not going to get to today such as using less or sass/scss pre-compilers. There's also a ways to specify view helpers. I'll talk about a few of those later and also the important thing to note here is this “extends” rule at the top. VuFind's themes inherits from each other. So “roots” is a theme that contains a lot of templates that are used in every single theme and if you look at bootprint3's theme config, it extends from bootstrap3. This allows you to build immediately on top of what we offer and on top of other parent themes to make it easier. If you look you can actually notice that bootprint3 doesn't have any templates of its own. It's just images and CSS on top of all the work that bootstrap3 is doing. So that's kind of the approach that we're going to take today as we make our new theme (and as you'll likely take) is that you're only going to customize the parts that you need. You don't need to copy over the whole bootstrap3 theme to use it. You're just gonna want to pick the parts that you want to customize and use only those files.

I think with that we're ready to get started with a new theme. I will point out there is a command prompt tool to do this but I'm going to keep it simple today and just make things manually so you can see how everything works but if you wanted to auto-generate a theme that's the correct structure and some other things in place there's a good way to do that as well.

So in order to make a new theme it's very simple. I'm going to make a new folder inside of themes. I'm going to call it “tutorial” and I'm going to add a theme config file. I'm actually going to copy bootprint3's particular theme config because it matches what we're going to start with. Save that and we are actually ready to go so I can go up here and I can switch to “tutorial”. I'm also going to add tutorial to our configurable switchable options here. We're going to take a look so I'm going to choose the theme directly. You'll see that it looks identical to bootstrap3 because we haven't customized anything yet but we are in fact in tutorial.

So you can see that even though we haven't added any code we are already leveraging all of the accessibility and all of the structure and all the styling of the bootstrap3 theme. So let's go ahead and customize this. We need to do this in two steps. We need to make the actual folders we're going to put our customizations and we need to tell “theme.config.php” that they exist.

So I'm going to make a “css” folder. We're going to make a new file in that folder. I'm gonna call it “custom.css”. You can call it whatever you like. Then in “theme.config.php”, I'm going to tell VuFind that we want to load this CSS file on every single page. I'm going to just add a little bit of color here so we can see that it works and if we go back you can see that if i refresh it things are now slightly different as I have customized things. Actually, I'm going to punch in a bunch of a bunch more code here that I will share later but not necessarily go over now. This is just for demonstration purposes. I did a couple different things to get us started on showing what a custom look can do. You see we can change the button colors we can change the fonts and everything like that all the things you can do with CSS are available to you.

So now that I've customized the look of it, I actually want to go and change some of the actual templates. So, for example I might want to make this header full width. I might want to change the logo up here. You might want to customize your footer. These are very easy to do because you can take the inheritance qualities and you can build on top of them. So for my demonstration today I'm going to show you how to override and make your own slightly customized header. Now you have to be careful with this kind of thing because if you give something the same name as something in the parent theme, it's going to completely override it. For example in Bootstrap the main CSS file is called “compiled.css”. If I had names this file to “compiled.css”, it would have completely overridden all of the Bootstrap styles and we'd have been left with much more of a mess than we intended to. But we're going to use this to our advantage right now by making a templates folder and I'm going to copy the header from bootstrap3 into our custom theme. Open this up… so now this file, our custom header, is completely overriding the bootstrap3 theme. I'm going to change this to “video tutorial” just as a very small little thing. I'm going to knock out to this container class, which I know will make it full-width, and there's something I needed to do down here but I can't quite remember right now so we'll come back to that later.

Now, if I refresh the page the CSS be fixed and you can see that the logo has changed to what we customized, it is now full width, which looks nice, but it still has all the themes and all the bits in there, which is very nice. Gonna go to a different view to show that it's going from page to page. Excellent.

So that is the absolute bare-bones basics that you would need to customize a theme. I'm gonna go over a few other things particularly some view helpers and some common techniques to make sure that you don't get caught with some common problems and that you're using tools that can make things easier. In particular, with images.

For this example, I'm going to replace this text up here with an actual picture logo, which is basically something that almost everyone will customize if they want to. I'm also going to add add a background image here just that show how to add background images. Now these are gonna be handled in different ways because I'm gonna add the actual image to the template in this case (logo) and I'm gonna add the image to the CSS in this case (background). The first thing I have to do is make an “images” folder. You can put the images folder wherever you like. I know that I like to install my fonts inside the CSS folder for convenience. Just keep in mind that paths are going to be relative to the CSS. I'm gonna grab a few example files that I downloaded earlier.

I'm going to starts with the CSS background. So, I already included the stylings here so, I'll just discuss them. The path is relative to the current CSS folder this is something to keep in mind if you go on to use the pre-processing things like less and scss/sass that it's gonna be relative to the outputted CSS. So we're just going up to the theme root and then down into “images” to get this particular image. And now that the image is in place inside of the folder, if i refresh we should get the background image here inside of our theme.

In order to add images to the templates it might be trickier to figure out the actual path but we have added a view helper to make this easier. So I'm going to go here to our video tutorial logo. I'm going to make it image so “<img src=”(which I get to in a second) and make this alt tag. So the view helper is called “imageLink” and this allows VuFind to find your image for you if you put it in the default spot here. So I just need to type out “<?=$this→imageLink(” and then the name of the image that I want, which is “vufind-logo.png”… This is a nice little helper that helps you find the image in the proper spot regardless of how nested your template folders get this is a very useful tool. Now if I refresh you'll see that I've replaced the image the logo with a sillier little image that I got from flamingtext.com. It just takes a little bit of CSS to make sure that doesn't overstep its bounds. There we go. Absolutely beautiful.

Another common thing that you'll want to keep in mind if you're making your own actual pages is that VuFind has breadcrumbs up at the top. It is fairly easy to customize these breadcrumbs. I just wanted to point out how it looks and how it works. So let me open up a different folder of an existing template just to show you what that code looks like. In the theme that's very common to see “$this→layout()→breadcrumbs”. “$this→layout() is almost a global object. You can write to it from any template and this will come in to come in handy when the page actually renders into layouts. So $this→layout()→breadcrumbs and then breadcrumbs is a string so you can dot append or concat onto it with anything you might want. So, in this case, this is where we're adding the actual search, with “lookfor” here so if you wanted to completely change the breadcrumbs or add some breadcrumbs on your custom pages, this is what you'd want to look for to do that. Very useful if you're making your own unique pages with their own unique routes. Just something I wanted to point out, just in case.

Another thing that I've been saying a lot is that when you change things in “theme.config.php” it adds those files to every single page. This is true of CSS and Java scripts and all the different things that you would be adding to a page but there is a fairly easy way to add CSS to just one or two pages. So for example, in our header or if we have a custom search home page we might want to add to some vendor files or add some unique scripts so I just want to show how that looked so you are aware of what you'd be looking for if you wanted to do that. Scripts look like this. Both of these are helpers that come with Zend Framework and we've tweaked them a little bit to help make sure all the paths are correct. “$this→headScript()→appendFile()” adds a JavaScript file from the JS folder of your theme to the header list. This is useful if you want to add functionality to just one page, so for example the advanced search has a whole bunch of JavaScript so you can add and dynamically remove different fields and move them around. So this file is only included on the advanced search page and that's done with one of these tags at the top of the template. Similarly if you wanted to add specific CSS to just a page you can do it this way with “$this→headLink→appendStylesheet()”. You can pull in vendor files, you can pull-in CSS that you just want on one particularly heavy page. This is a good technique so that way if you have particularly heavy JavaScript or CSS files or ones that are doing a lot of work they don't want to interfere with other pages, this is one way to do it in a way that will stay uniquely on one page. You'll see this most commonly on the search home if you want to add some carousels or things like that. You'll see this throughout the VuFind templates if you take a look.

That more or less summarizes the absolute basics of making your own theme. There are some more advanced topics that we're going to cover in later videos. For example, mix-ins which are very useful for institutions that have multiple looks or multiple themes. For example a college that might have multiple libraries you might want to solve a different look for each one. mix-ins allow you to share files among different themes more easily. It's just another tool for customization. There's also built-in preprocessor abilities for less and scss/sass. I will cover that in another video. There's ways to do that to compile with PHP or if you have node installed, there is a grunt file that we can use to make tasks and load less and CSS files. And finally in order to use those tools it might be easiest to use the command lines generators so when I do those examples I'll show you how those work and how it gives you a pre-built structure for your themes.

So I'm going to leave this up as the final screen so you can see the structure of our new theme. Thank you for watching this video! If you have any questions please feel free to check out the VuFind wiki and send us any emails on our mailing lists that you might have. We'd be more than happy to clarify and cover things in future videos. Thank you for watching and Happy Searching!

videos/creating_themes.txt · Last modified: 2023/04/26 13:27 by crhallberg