Table of Contents
Starting with VuFind 1.0RC2, the search options available to your users are completely customizable through configuration files.
If you are using an earlier version of VuFind, we strongly recommend upgrading. However, if you need information on customizing 1.0RC1 and earlier, see this earlier version of the page.
Defining Search Types
The available search types are defined in a file called searchspecs.yaml. This file may be found in the web/conf directory in VuFind 1.x; in VuFind 2.x, default settings are found in config/vufind and may be copied and customized in the config/vufind subdirectory of your local settings directory.
YAML is a text file format for storing data that is a little more flexible than the standard .ini files used by most of VuFind. Don't be intimidated – most simple changes can be made without needing a deep understanding of how YAML works, and most new searches you will need can be created by copying some of the samples provided with the default VuFind installation.
The comments embedded in the YAML file provide full details on how the searches need to be defined; that information is not duplicated here to avoid redundancy. This Wiki page is intended as a general overview of customization issues rather than a full technical spec.
Dismax vs. Lucene
In order to understand the VuFind search configuration, it is helpful to understand the difference between Dismax and Lucene queries. Both are types of queries that the Solr index can perform. If you are interested in the technical details, see the Solr Wiki. From a practical perspective, the key difference is that Dismax is better at providing relevant results for simple queries, but Lucene offers more features (boolean operators, wildcards, mixed-index searching).
VuFind tries to use Dismax searches when possible, but it uses Lucene when it has to because of advanced features. For best results when creating a new search type, you should try to provide enough settings to allow both Dismax searches (via “DismaxFields”) AND Lucene searches (via “QueryFields”). Note that you must always provide Lucene settings, even if you choose never to use Dismax.
There are a few simple adjustments you can make to tweak search results to your liking.
One of the easiest and most common things you may wish to customize in searchspecs.yaml is search field weighting. The numbers found throughout the YAML file are relative weights applied during searches to rank results, and these can be adjusted to change the order in which search results appear. For example, you might decide that in an AllFields search, Authors are more important than Titles – you could cause records with hits in the author field to rise above records with hits in the title field simply by changing the appropriate numbers. When making changes, be sure to keep the Dismax-related settings consistent with the Lucene-related settings for more predictable results.
Sometimes, you don't want to require matches on all of the terms provided by the user's search string. Finding the right balance between too few and too many search results is another area where trial and error may be necessary. Adjusting the fuzziness of results differs for Dismax vs. Lucene searches due to the varying capabilities of the two search types.
For Dismax, you can configure the “mm” parameter in the “DismaxParams” section of the YAML file. This parameter lets you control the number of required terms based on the number of input terms. It is very flexible, and details of exactly how it works can be found in the Solr Wiki.
For Lucene, you have a bit less flexibility, but many searches in the YAML file combine search terms using both a Boolean AND operator and a Boolean OR operator, giving the ANDed terms a greater weight than the ORed terms. You can read the comments in the YAML file and look at the examples for more details of how this works.
Search Interface Customization
A file called searches.ini is used to control which of the search types defined in searchspecs.yaml are used by VuFind. The [Basic_Searches] section defines which search options are displayed in the basic search box found on most pages of the interface. The [Advanced_Searches] section defines which search options are displayed on the Advanced Search screen. You can adjust the order in both areas to meet your needs. Note that if you are working in a multi-language environment, you will need to create translations for any text you enter into searches.ini in the language files found in the web/lang directory.
Other Customizable Options
The [General] section of searches.ini allows some additional customization of search-related features:
- The case_sensitive_bools setting lets you choose whether boolean operators in the search string must be ALL UPPERCASE in order to be recognized (true) or if they will be used regardless of case (false). The default setting is true.
- The default_handler setting lets you specify which of the searches from searchspecs.yaml is used by default when no other handler is chosen.