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.

Alphabetical Heading Browse


The AlphaBrowse module provides a traditional alphabetical heading browse which allows users to see all of the authors, subjects and titles in your collection, including cross-references extracted from authority data.

This article describes the motivation of the author, use cases, design and FAQ.

In order to take advantage of this functionality, you need to add an extra step to your indexing process so that the databases used for heading lookup are correctly generated.

Generating Heading Databases

To build the databases used for heading lookup, you need to run a simple command-line tool.

IMPORTANT: You need to rebuild your headings every time your index is updated in order to keep things in sync.

In Linux

Go to your VuFind® directory and run:


:!: When running this script, it is best to log in as the same user account that runs Solr. The Solr process will need to read and write the files produced by the script, and if you run it as a different user, permission problems could prevent correct operation of the browse process.

If you encounter problems after running the script, you may need to restart VuFind® to see the headings. However, in most versions of VuFind®, a restart is not necessary.

In Windows

Go to your VuFind® directory and run:


If you encounter problems after running the script, you may need to restart VuFind® to see the headings. However, in most versions of VuFind®, a restart is not necessary.

Modifying Heading Databases

You can change the field used to create any of the databases by modifying the following:

  • index-alphabetic-browse.sh: change the second parameter of the relevant build_browse call
  • local/config/vufind/searchspecs.yaml: change the relevant field; search for the comment “# Fields for exact matches originating from alphabetic browse”
  • solr/biblio/conf/solrconfig.xml: change the field used by the browse request handler; search for “BrowseRequestHandler”. This is the solr field to be searched once the alphabrowse index has reretrieved what it calls a “heading” (basically the 'value' portion of an entry). So you should enter your value field here.
  • Make sure you've turned on the page in local/config/vufind/config.ini

You may want one of your alphabrowse index to use one field for sorting and a different field for display (e.g. for call numbers)

  • index-alphabetic-browse.sh: set field leech params valuefield (used for display) and sortfield (used for sorting) example:
    build_browse "lcc" "callnumber_browse" 1 "-Dbibleech=StoredFieldLeech -Dsortfield=callnumber_browse_sort" -Dvaluefield=callnumber_browse
  • local/config/vufind/searchspecs.yaml: use the value field
  • solr/biblio/conf/solrconfig.xml: use the value field

Then, when a query is submitted to alphabrowse, the field you used as the sortfield is the one that will be matched against. You may want to create a custom normalizer to translate user-entered data into the right format.

Custom Normalizers

The alphabrowse system uses normalization code to attempt to reconcile textual variations and allow more accurate match-up between indexed terms and user search queries.

Normalization affects the order in which results are sorted, since normalization is applied to sort keys.

Ideally, the same normalization logic should be applied during indexing and when processing user queries to ensure consistent behavior.

It is sometimes useful to build custom normalizers; for example, when dealing with call numbers, normalization is often necessary to put items into proper shelf order.

Creating a Custom Normalizer

Implementing a new normalizer would just be implementing the Normalizer interface. It’s pretty minimal:

package org.vufind.util;

 * An interface for alphabetical browse normalizers.
 * @author Tod Olson <tod@uchicago.edu>

public interface Normalizer {

* Normalizes the input string to a collation key, which will be used for the 
* sort order of the browse index.
* @param s the string to be normalized, e.g. a term for the browse index
* @return collation key for determining browse order
public byte[] normalize (String s);


SolrMarc is built with OneJar which makes it hard to access its internals from other Java applications. If you include anything from solrmarc, you will need to break open SolrMarc.jar and the the right jar to put in the libs/ directory of the browse handler. Then build the handler and drop that, along with whatever you needed out of SolrMarc.jar, into your vufind solr/lib directory.

Using a Custom Normalizer

  • in index-alphabetic-browse.sh add a normalizer parameter to your build_browse call, example:
     build_browse "lcc" "callnumber_browse" 1 "-Dbibleech=StoredFieldLeech -Dsortfield=callnumber_browse_sort -Dvaluefield=callnumber_browse -Dbrowse.normalizer=org.vufind.util.UChicagoLCCallNormalizer”
  • You can also use the normalizer without the leech. The advantage of doing it this way is you don't have to worry about mis-matched numbers of fields (which happens when the sortfield and valuefield have different-length arrays). Also you won't have to has that extra index field in solr. example:
     build_browse "lcc" "callnumber_browse" 1 "-Dbrowse.normalizer=org.vufind.util.UChicagoLCCallNormalizer”
  • in solr/biblio/conf/solrconfig.xml add a normalizer to the browse handler configuration, example:
        <lst name="lcc">
          <str name="DBpath">${solr.solr.home:./solr}/alphabetical_browse/lcc_browse.db</str>
          <str name="field">callnumber_browse</str>
          <str name="normalizer">org.vufind.util.UChicagoLCCallNormalizer</str>


VuFind®'s display of alphabetical browse results has some configurable options; see the [AlphaBrowse] section of config.ini for details.

More Information

For more information on this feature, including full documentation and source code for the Solr plug-in that drives it, see the vufind-browse-handler project.

Other Implementations

The Alphabetic Index Search article from swisscollections describes an alternate implementation of VuFind® AlphaBrowse.

indexing/alphabetical_heading_browse.txt · Last modified: 2024/04/17 14:30 by demiankatz