VuFind Orientation

This post will try to be a brief guide to getting a feel for administrating a VuFind installation.

It’s not a definitive account, just my own experience so far. I’m still learning.

Installation

VuFind uses Apache Solr to index records and provide such things as facets. Some have described Vufind as a lite frontend to Solr, but I feel this is a little unfair, a car is more than an engine, and VuFind does more than just return search results.

VuFind is PHP based, making use of various PEAR libraries and uses MySQL for various settings. Solr is written in Java and will essentially run a web server on a different port which VuFind will use to query it. VuFind uses Smarty for templates.

The VuFind installer takes care of all of this, but at times you may find it needs a little tweaking (when I used it a few months a go it wasn’t downloading/installing Smarty correctly.

So in all, VuFind requires a based LAMP stack (Linux , Apache, MySQL, PHP), PEAR, Java (Tomcat), Solr, and Smarty. Other OS can be used with a little extra work.

I’ve also created an install script which works on Fedora based systems (I tested it on the Amazon AWS Linux installation which is based on Fedora). The difference with my script is that it will allow you to install multiple instances of VuFind on to the same server with ease. It uses an instance name which is used for the installation directory, url, database name etc, it also uses a different port number for the Solr server for the instance. Even if you don’t use the script I recommend you look at it to get a feel of what it is doing.

The installation notes for the CReDAUL project can be found here.

Useful urls

Vufind comes with an administration site. http://vufind.yourdomain.org/vufind/Admin/Home

This provides a way to view some statistics, some configuration (including ability to edit), and internal Record view. the htpasswd file is located in services/Admin directory, you can add a user to gain entry to the admin site. Also change the password on the default admin user, and consider restricting to local IP addresses.

You can also view the solr index on the port number it is running on e.g. http://vufind.yourdomain.org:17080/solr/biblio/

Layout

The top level of the vufind directory (by default /usr/local/vufind/ ) is of use for (a) starting/stopping vufind (b) importing records.

I should say here, when we talk about starting/stopping VuFind (using vufind.sh) we are really talking about starting/stopping the Solr service (Vufind wont do anything without it).

You will spend 90% of your time administrating VuFind within the ‘web’ directory, but before will move on to that we’ll mention the ‘solr’ directory.

solr – you’ll never guess – contains the solr installation. Including relevant logs and configuration. A useful file is solr/jetty/etc/jetty.xml which contains the configuration, including such things as port number and the number of threads to run. The actual index is stored in solr/biblio/index – if you’ve got a problem with your records, just delete the directory and re-import your MARC files.

Just before we move on to the ‘web’ directory I’ll mention the import directory, if contains the config for the import script which may need some tweaking.

The web directory.

These are the main sub-directories of the web directory:

• conf – the first file you will probably play with is the config.ini within this directory. It contains a lot of settings, from the core (what URL does it use), to quite specific settings and options. You’ll also find here the configuration file for the driver which is used to connected to your ILS (aka LMS), and a few more to configure facets (which ones are shown in which order) and searches.
• Drivers – the driver file which connects to your ILS is found here. Depending on what system you use you may find it needs tweaking to meet your needs.
• interface – you’ll find the smarty templates in interface/themes – more on this below
• lang – language files. Useful to define local terms, in your library do you refer to a Lending Desk, Issue desk, Service Point or Circulation desk? Vufind makes it easy to set this, for us in the English speaking world in the en.ini file, in fact this is much neater than many commercial products.
• RecordDrivers – two key files IndexRecord and MarcRecord.php. The latter is a child/extension of the former. IndexRecord contains methods for exposing record details (for use in smarty templates) for any sort of bib record. MarcRecord extends this with MARC specific information.
• services – key php application files. I haven’t found the need to edit anything in here yet, but can help to understand how system is structured.

Smarty

I quite like how Smarty is used, it keeps the interface quite separate from the rest of the logic and code. Though I have heard others say that it is essentially a templating system (with it’s own code and syntax) built on top of a language that in many ways was designed to be just that (PHP).

Vufind has a number of out-the-box themes, by default it uses the one called, well, default. And also mobile if it detects the user is on a mobile device.

I wont describe everything here, you can often guess which file is used for what on screen, it may take a couple of guesses but it is normally quite quick to see if this contains the html code you are interested in changing once you have opened the file.

At the top level there is layout.tpl, and footer.tpl which contain system wide layout templates. There’s also a css and a images file (there’s also a images dir higher up for images which are not theme specific).

• The homepage is in Web/home.tpl
• Record and Search dirs have contained most of the files I’ve needed to edit
• You can see many Smarty tags within the files to translate terms in to the local language and local terminology. for example {translate text=”Add to favorites”} which insert what text you have chosen for ‘adding to favorites’, e.g. ‘Add to My List’ etc.
• The Record files use variables created in the IndexRecord/MarcRecord files (see above ‘RecordDrivers’). So you can refer to those files to see which variables will contain the information you want to show. Different information is exposed to different views, e.g. the export citation option has just the information required to create a citation. If you want to add an extra bit of information to a citation then you will need to probably edit the RecordDriver files to make sure they expose the data, and then edit the appropriate smarty template file to incorporate it.

Some examples of changes

• For internet resources we use the MARC 856 field, subfield $u contains the actual link and subfield $y contains the text to use for the link. However vufind presumes the link text will be in subfield $z (which we don’t use) so out the box it would use the URL itself as the text for the link as we had no z. To fix this we edited RecordDrivers/MarcRecord.php so that the getURLs function uses the y subfield.
• Our setup actually searches two libraries, those of the University of Sussex and University of Brighton. We pre-process the MARC records from each University to add a 969 field for each University which has the item in question. The 969 contains the University code (susx/brighton), and the bibid the library uses for the item (if both Libraries have the item then the record has two 969 fields). When we display a record we want the user to be able to easy link to the record in the main catalogue of the University in question. To do this we edited MarcRecord to create a function which can take this MARC field and turn it in to a link (using the bibid to create a link to the catalogue record in question). I think we also created a skelton function in IndexRecord (which the function in MarcRecord over rides). Finally we edited interface/themes/default/RecordDrivers/Index/core.tpl to add the field to the default record display. [to see the MARC tags referred to here and the example above see this record ]
• We didn’t want the search results to show availability/shelfmark. With two library systems there was too much potential for mistakes to creep in, best left to the record view of the item. Plus it meant VuFind had to get information for every item on the search results page, potentially putting a load on the original ILS (LMS) server(s). This is actually something which uses AJAX. And this is something which uses the design where a MARC record extends what a ‘default’ record can do (i.e MarcRecord.php extends IndexRecord.php in RecordDrivers). VuFind decides that if something is a MARC record it has come from a Library system and so it can try and find holdings/availability. Essentially the IndexRecord function getSearchResult() will set $interface->assign(‘summAjaxStatus’, false); so it wont try and get availability via AJAX. Where as MarcRecord overrides the function, doing all but the same with everything else but sets that value to true. The smarty template for search results (interface/themes/default/RecordDrivers/Index/result.tpl) then uses the value of summAjaxStatus in a if statement, if true it will output some html/javascript code to perform thee AJAX calcode to call and display the results. So, to do what we wanted, we changed MarcRecord to set summAjaxStatus to false (so it should always be false). And then edited the smarty file so that what gets shown when it is false meets our needs.
• We edited the help files in interface/themes/default/Help/
• we changed the order of facets in conf/facets.ini
• We edited interface/themes/default/Record/view-holdings.tpl so that it doesn’t show ‘item 1’, ‘item 2’ etc next to each copy of the item (we found the numbers weren’t really helpful and didn’t mean anything).
• And much more….

These examples show that it is quite easy to customise vufind, once you know which files to poke around in.

I can say that the only other system which compares in this flexibility, in my experience, is Eprints. I have not come across a single commercial system (catalogue or otherwise) which we use as a library which has such a structured and logical design.