About Features Downloads Getting Started Documentation Events Support GitHub

Site Tools


development:howtos:displaying_a_custom_field

Displaying a Custom Field

This page contains general information on how to display new fields in the VuFind interface.

Thanks to Luis Diaz for help in drafting this document.

Understanding VuFind Displays

All of VuFind's displays are rendered using PHP templates within the theme. The data used in these templates is retrieved from a record driver, which is a PHP class with many public methods. The record driver most commonly retrieves its information from either the Solr index or a stored MARC record retrieved from the index.

In the case of Solr, stored field data from the index is made available to the record driver through its fields property; in the case of MARC, convenience methods are provided for extracting data. For other data formats and sources, availability and format of internal data will vary according to the design of the search backend.

For examples of display templates, see the DefaultRecord templates within the Bootstrap3 theme. An understanding of the record data formatter will also help clarify how these work.

For examples of Solr-based retrievals, see the DefaultRecord driver; for examples of MARC-based retrievals, see the SolrMarc driver (and its MarcAdvancedTrait).

Workflow for Adding a Field

The basic workflow for adding a field is:

  1. Make the data available to VuFind
  2. Make the data accessible through a record driver
  3. Display the data in the appropriate template

1. Make the data available to VuFind

It is possible that the data is already available to VuFind. If you are retrieving a value from a field within the stored MARC record, or if you wish to display a field that is already visible elsewhere in VuFind, you can skip this step.

If you need to process data at the indexing stage rather than loading it raw from MARC, you will need to adjust your SolrMarc configuration and/or your Solr schema.xml definition. See the discussion on adding facets for details on how to accomplish this.

Don't forget to reindex your data and restart Solr after making changes like this!

2. Make the data accessible through a record driver

If you are displaying a field that is already defined within VuFind, you can skip this step.

If you are adding a totally new field, you will need to add an appropriate getter method to the record driver used to display your records. In the most common situation, this is going to be the SolrMarc driver, which inherits most of its functionality from the SolrDefault driver. The existing get methods in these classes should serve as useful examples for creating new methods.

If you copy an existing method as a template for your new method, the most important detail to watch out for is the return value: be sure that you return a string when dealing with a single-valued Solr field and that you return an array when dealing with a multi-valued Solr field. This will make it easier for you to deal with data cleanly in your template.

Also note that while you can simply edit the existing record drivers in place, it is generally a better practice to localize your changes within a custom module to ease future upgrades. See the Customizing VuFind page for more details on this. If using VuFind 2.4 or newer, note that code generators can automate most of the setup when building a custom record driver.

3. Display the data in the appropriate template

The final step to display a new field is to make it visible through a display template. Record-relate templates are found in the RecordDriver folder of your chosen theme in a folder that corresponds with the name of the record driver class. When VuFind picks a template to display, it follows the class' inheritance chain – e.g. if SolrMarc/core.phtml does not exist, VuFind will next try SolrDefault/core.phtml, because SolrDefault is SolrMarc's parent. Because of this design, most of VuFind's record display templates are found within the RecordDriver/SolrDefault theme folder even though there are many different drivers available.

Some key templates that you are likely to consider editing:

  • result-grid.phtml - a single search result, when “grid view” is active
  • result-list.phtml - a single search result, when “list view” (the default mode) is active
  • core.phtml - the metadata displayed on the record view, regardless of the active tab (though in VuFind 4.x and newer, it is easier to change this by reconfiguring the record data formatter rather than by overriding the template)

It should be possible to add the new field to the template by imitating some of the other code already present there.

As with code customizations, it is possible to edit templates in-place, but it is often better practice to create your own custom theme and create your custom views there – this will make future upgrades easier. See Customizing VuFind for more details.

4. Step-by-step examples

development/howtos/displaying_a_custom_field.txt · Last modified: 2020/09/22 13:27 by demiankatz