About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

VuFind Documentation

Site Tools

You are here: start » development » howtos » displaying_a_custom_field
Trace:
Warning: This page has not been updated in over over a year and may be outdated or deprecated.
development:howtos:displaying_a_custom_field

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
development:howtos:displaying_a_custom_field [2015/12/11 18:53] – ↷ Links adapted because of a move operation demiankatzdevelopment:howtos:displaying_a_custom_field [2020/09/22 13:27] (current) – demiankatz
Line 7: Line 7:
 ===== Understanding VuFind Displays ===== ===== Understanding VuFind Displays =====
  
-All of VuFind's displays are rendered using PHP templates within the [[vufind2:customizing_the_user_interface|theme]]. The data used in these templates is retrieved from a [[development:plugins:record_drivers|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.+All of VuFind's displays are rendered using PHP templates within the [[development:architecture:user_interface|theme]]. The data used in these templates is retrieved from a [[development:plugins:record_drivers|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 [[vufind2:connecting_a_new_external_data_source|search backend]].+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 [[development:howtos:connecting_a_new_external_data_source|search backend]].
  
-For examples of display templates, see the [[https://github.com/vufind-org/vufind/tree/master/themes/bootstrap3/templates/RecordDriver/SolrDefault|SolrDefault]] templates within the Bootstrap3 theme.+For examples of display templates, see the [[https://github.com/vufind-org/vufind/tree/dev/themes/bootstrap3/templates/RecordDriver/DefaultRecord|DefaultRecord]] templates within the Bootstrap3 theme. An understanding of the [[development:architecture:record_data_formatter|record data formatter]] will also help clarify how these work.
  
-For examples of Solr-based retrievals, see the [[https://github.com/vufind-org/vufind/blob/master/module/VuFind/src/VuFind/RecordDriver/SolrDefault.php|SolrDefault]] driver; for examples of MARC-based retrievals, see the [[https://github.com/vufind-org/vufind/blob/master/module/VuFind/src/VuFind/RecordDriver/SolrMarc.php|SolrMarc]] driver.+For examples of Solr-based retrievals, see the [[https://github.com/vufind-org/vufind/blob/dev/module/VuFind/src/VuFind/RecordDriver/DefaultRecord.php|DefaultRecord]] driver; for examples of MARC-based retrievals, see the [[https://github.com/vufind-org/vufind/blob/dev/module/VuFind/src/VuFind/RecordDriver/SolrMarc.php|SolrMarc]] driver (and its [[https://github.com/vufind-org/vufind/blob/dev/module/VuFind/src/VuFind/RecordDriver/MarcAdvancedTrait.php|MarcAdvancedTrait]]).
  
 ===== Workflow for Adding a Field ===== ===== Workflow for Adding a Field =====
Line 27: Line 27:
 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. 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|SolrMarc]] configuration and/or your Solr schema.xml definition. See the discussion on [[:adding_facets|adding facets]] for details on how to accomplish this.+If you need to process data at the indexing stage rather than loading it raw from MARC, you will need to adjust your [[indexing:solrmarc|SolrMarc]] configuration and/or your Solr schema.xml definition. See the discussion on [[indexing:adding_facets|adding facets]] for details on how to accomplish this.
  
 Don't forget to reindex your data and restart Solr after making changes like this! Don't forget to reindex your data and restart Solr after making changes like this!
Line 34: Line 34:
 If you are displaying a field that is already defined within VuFind, you can skip this step. 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 [[https://github.com/vufind-org/vufind/blob/master/module/VuFind/src/VuFind/RecordDriver/SolrMarc.php|SolrMarc]] driver, which inherits most of its functionality from the [[https://github.com/vufind-org/vufind/blob/master/module/VuFind/src/VuFind/RecordDriver/SolrDefault.php|SolrDefault]] driver. The existing get methods in these classes should serve as useful examples for creating new methods.+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 [[https://github.com/vufind-org/vufind/blob/dev/module/VuFind/src/VuFind/RecordDriver/SolrMarc.php|SolrMarc]] driver, which inherits most of its functionality from the [[https://github.com/vufind-org/vufind/blob/dev/module/VuFind/src/VuFind/RecordDriver/SolrDefault.php|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. 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 [[development:architecture:customizing_vufind|Customizing VuFind]] page for more details on this. If using VuFind 2.4 or newer, note that [[vufind2:code_generators|code generators]] can automate most of the setup when building a custom record driver.+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 [[development:architecture:customizing_vufind|Customizing VuFind]] page for more details on this. If using VuFind 2.4 or newer, note that [[development:code_generators|code generators]] can automate most of the setup when building a custom record driver.
 ===== 3. Display the data in the appropriate template ===== ===== 3. Display the data in the appropriate template =====
  
Line 45: Line 45:
 Some key templates that you are likely to consider editing: Some key templates that you are likely to consider editing:
  
-  * core.phtml - the metadata displayed on the record view, regardless of the active tab 
   * result-grid.phtml - a single search result, when "grid view" is active   * 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   * 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 [[development:architecture:record_data_formatter|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. 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 [[development:architecture:customizing_vufind|Customizing VuFind]] for more details. 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 [[development:architecture:customizing_vufind|Customizing VuFind]] for more details.
-===== 4. Step-by-step example ===== +===== 4. Step-by-step examples =====
- +
-// This example shows you how to set up a custom module, custom theme and custom record driver. It assumes that you have already added a custom field to your Solr index named RecID -- you can see more concrete examples of adding fields on the [[:adding_facets|Adding Facets]] page. // +
- +
-1. Create a custom module (if you haven't already done so) +
-   cd $VUFIND_HOME +
-   php install.php +
- +
-   * At the prompt "What module name would you like to use? [blank for none]" type in your module name +
-   * Link configuration to apache’s config.d directory per the install.php directions +
-   * Restart apache (sudo /etc/init.d/apache2 restart) +
-  +
-2. From $VUFIND_HOME enter the following code generator command: +
-   php public/index.php generate extendservice vufind/plugin_managers/recorddriver/factories/solrmarc ModuleName +
- +
-   * You should see the following:  +
- +
-   Saved file: /usr/local/vufind/module/ModuleName/src/ModuleName/RecordDriver/SolrMarc.php +
-   Saved file: /usr/local/vufind/module/ModuleName/src/ModuleName/RecordDriver/Factory.php +
-   Successfully updated /usr/local/vufind/module/ModuleName/config/module.config.php +
- +
-   * If you get an error like "Class ModuleName\RecordDriver\Factory does not exist", or if the files do not get written, then do the following: +
- +
-   export VUFIND_LOCAL_MODULES=ModuleName +
-   php public/index.php generate extendservice vufind/plugin_managers/recorddriver/factories/solrmarc ModuleName +
- +
-3.  Update the SolrMarc.php file to add a new field.  +
-  * Make sure the namespace line reads “namespace ModuleName\RecordDriver;” +
-  * Add the getter method. See below for an example, but also reference the SolrMarc.php file in /module/VuFind/src/VuFind/RecordDriver/ for more examples of getter code.   +
- +
-   Example:  +
-   <?php +
-   namespace ModuleName\RecordDriver; +
-   class SolrMarc extends \VuFind\RecordDriver\SolrMarc +
-   { +
-    /** +
-     * Get the record ID of the current record. +
-     * +
-     * @return string +
-     */ +
-    public function getRecordID() { +
-        return isset($this->fields['recID']) ? +
-           $this->fields['recID'] : ''; +
-      } +
-   } +
- +
-4. Customize the template where you want to use that field by copying the appropriate files into your custom theme.  +
-   cd $VUFIND_HOME/themes +
-   mkdir ThemeName +
- +
-  * Make the following sub-directory structure: ThemeName/templates/RecordDriver/SolrDefault/ +
-  * Put the following content in $VUFIND_HOME/themes/ThemeName/theme.config.php: +
- +
-<code> +
-<?php +
-return array( +
-    'extends' => 'bootstrap3' +
-); +
-</code> +
- +
-  * cd $VUFIND_HOME/themes/bootstrap3/templates/RecordDriver/SolrDefault/, and copy core.phtml and result-list.phtml to new theme’s SolrDefault directory +
-  * Edit core.phtml and result-list.phtml to add new fields for display. +
- +
-    Example: +
-      <? $recordID = $this->driver->getRecordID(); if (!empty($recordID)): ?> +
-      <tr> +
-        <th><?=$this->transEsc('Record ID')?>: </th> +
-         <td property="RecID"><?=$this->escapeHtml($recordID)?></td> +
-       </tr> +
-      <? endif; ?> +
- +
-  * Edit local/config/vufind/config.ini to set theme = ThemeName+
  
 +  * [[development:howtos:displaying_a_custom_field:vufind6_example|Example for VuFind 6.x or newer]]
 +  * [[development:howtos:displaying_a_custom_field:vufind3_example|Example for VuFind 3.x]]
 ---- struct data ---- ---- struct data ----
 +properties.Page Owner : 
 ---- ----
  
development/howtos/displaying_a_custom_field.1449859987.txt.gz · Last modified: 2015/12/11 18:53 (external edit)