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.
development:architecture:record_data_formatter

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:architecture:record_data_formatter [2018/05/09 13:30] – [Basic Concept] demiankatzdevelopment:architecture:record_data_formatter [2023/12/11 16:11] (current) – [Option 2: Override the Factory] Add example of re-ordering spec array dltj
Line 1: Line 1:
 ====== RecordDataFormatter view helper ====== ====== RecordDataFormatter view helper ======
  
-:!: // This page describes functionality that was added in VuFind 4.0. //+:!: // This page describes functionality that was added in VuFind® 4.0. //
  
-VuFind includes a RecordDataFormatter view helper designed to make it easier to customize the contents of tabular displays of data generated from [[development:plugins:record_drivers|record driver]] objects.+VuFind® includes a RecordDataFormatter view helper designed to make it easier to customize the contents of tabular displays of data generated from [[development:plugins:record_drivers|record driver]] objects.
  
 ===== Basic Concept ===== ===== Basic Concept =====
Line 12: Line 12:
   * A [[development:plugins:record_drivers|record driver]] object.   * A [[development:plugins:record_drivers|record driver]] object.
  
-As output, getData() returns different formats depending on your VuFind version. In 4.x, it is an associative array of field name <nowiki>=></nowiki> another associative array containing HTML output ('value' key) and contextual information ('context' key) for the corresponding field. :!: Starting with 5.0, the return format changes to a non-associative array of arrays, with each sub-array containing a 'label' key for the field name.+As output, getData() returns different formats depending on your VuFind® version. In 4.x, it is an associative array of field name <nowiki>=></nowiki> another associative array containing HTML output ('value' key) and contextual information ('context' key) for the corresponding field. 
 + 
 +:!: Starting with 5.0, the return format changes to a non-associative array of arrays, with each sub-array containing a 'label' key for the field name
 + 
 +:!: Starting with 9.0, the record driver parameter to getData is optional; you can instead pass it directly to the view helper when the helper is invoked -- e.g. <nowiki>$this->recordDataFormatter($driver)->getData($specs)</nowiki> instead of <nowiki>$this->recordDataFormatter()->getData($driver, $specs)</nowiki>.
  
 Field names are raw and should be translated/escaped when displayed in templates. Field names are raw and should be translated/escaped when displayed in templates.
  
-Additionally, the helper includes getDefaults($key) / setDefaults($key) methods which can be used to store or retrieve default specification arrays. VuFind ships with stored specifications for 'collection-info', 'collection-record', 'core' and 'description', which are used in the corresponding .phtml files in the record driver template directory. See below on how to change/customize these defaults.+Additionally, the helper includes getDefaults($key) / setDefaults($key) methods which can be used to store or retrieve default specification arrays. VuFind® ships with stored specifications for 'collection-info', 'collection-record', 'core' and 'description', which are used in the corresponding .phtml files in the record driver template directory. See below on how to change/customize these defaults.
  
 ===== Specification Array ===== ===== Specification Array =====
Line 26: Line 30:
 | context | optional | An array of contextual values that may be used to help with template rendering; these are always passed through as the 'context' key of the output of the view helper. When template rendering (renderType = RecordDriverTemplate) is used, these values are also passed directly to the target template | | context | optional | An array of contextual values that may be used to help with template rendering; these are always passed through as the 'context' key of the output of the view helper. When template rendering (renderType = RecordDriverTemplate) is used, these values are also passed directly to the target template |
 | dataMethod | :!: required :!: | The record driver method to use for extracting raw field data used for generating output. May be set to boolean true to always generate output without variable input; may be set to boolean false to suppress the entire field. | | dataMethod | :!: required :!: | The record driver method to use for extracting raw field data used for generating output. May be set to boolean true to always generate output without variable input; may be set to boolean false to suppress the entire field. |
 +| dataMethodParams | optional | An array of values to pass to the dataMethod as arguments. Useful, for example,  to call getAllSubjectHeadings with $extended set to true. // Introduced in VuFind® 10.0. // |
 | helperMethod | optional | The Record view helper method to use for output rendering, when renderType = RecordHelper. | | helperMethod | optional | The Record view helper method to use for output rendering, when renderType = RecordHelper. |
 | pos | optional | An integer used for sorting the fields to determine the final display order. | | pos | optional | An integer used for sorting the fields to determine the final display order. |
-| renderType | optional (default = Simple) | The method used to render output from the input provided by dataMethod. Legal values: RecordDriverTemplate (render a template associated with the record driver, as specified by the 'template' key); RecordHelper (call a method of the Record view helper, as specified by the 'method' key); Simple (display the raw data, possibly manipulated based on other settings in the specification) | +| renderType | optional (default = Simple) | The method used to render output from the input provided by dataMethod. Legal values: **CombineAlt** (render primary text and matching alternative representation), **Multi** (sort data using a callback function specified by the 'multiFunction' key and potentially render each output group using different rules), **RecordDriverTemplate** (render a template associated with the record driver, as specified by the 'template' key); **RecordHelper** (call a method of the Record view helper, as specified by the 'method' key); **Simple** (display the raw data, possibly manipulated based on other settings in the specification) | 
-| labelFunction | optional | May be set to a callback function which will receive the raw field data as input and produce a custom output label (overriding the key of the spec array) as output. Starting with VuFind 5.0, the callback function also receives the record driver object as a second parameter. | +| labelFunction | optional | May be set to a callback function which will receive the raw field data as input and produce a custom output label (overriding the key of the spec array) as output. Starting with VuFind® 5.0, the callback function also receives the record driver object as a second parameter. 
-| prefix | optional | HTML to prepend to the output generated by the view helper. Applies only when RenderType = Simple. |+| multiFunction | optional | The callback required when renderType = Multi. Accepts three parameters: 1.) raw input data, 2.) the options array from the spec, 3.) the record driver object. Outputs an array of associative arrays with the following keys: **label**: Label to display; **values**: Values to render; **options**: Rendering options (may include renderType, pos, and any other relevant parameters; they will be applied only to the current grouping of data; any options not set here will be inherited from the spec array). | 
 +| multiRenderType | optional | The default type of rendering to apply to each of the sets of values returned by the multiFunction (optional, defaults to Simple, may be overridden by options specified by your multiFunction). | 
 +| itemPrefix | optional | HTML to prepend to each value formatted by the view helper. Use prefix instead if you want to prepend a single value to the whole set of data assembled by the view helper. Applies only when RenderType = Simple. :!: // Introduced in VuFind® 7.0. // | 
 +| itemSuffix | optional | HTML to append to each value formatted by the view helper. Use suffix instead if you want to append a single value to the whole set of data assembled by the view helper. Applies only when RenderType = Simple. :!: // Introduced in VuFind® 7.0. // 
 +| prefix | optional | HTML to prepend to the output generated by the view helper. This is applied once before the full set of values; use itemPrefix if you want to prepend something to each individual value. Applies only when RenderType = Simple. |
 | recordLink | optional | The type of link (from the Record view helper's getLink method) to associate with each value in the raw field data. Applies only when RenderType = Simple. | | recordLink | optional | The type of link (from the Record view helper's getLink method) to associate with each value in the raw field data. Applies only when RenderType = Simple. |
 | separator | optional (default = <nowiki><br /></nowiki>) | Separator to use between multiple data values. Applies only when RenderType = Simple. | | separator | optional (default = <nowiki><br /></nowiki>) | Separator to use between multiple data values. Applies only when RenderType = Simple. |
-| suffix | optional | HTML to append to the output generated by the view helper. Applies only when RenderType = Simple. |+| suffix | optional | HTML to append to the output generated by the view helper. This is applied once after the full set of values; use itemSuffix if you want to append something to each individual value. Applies only when RenderType = Simple. |
 | template | optional | The name of the template to render, when renderType = RecordDriverTemplate | | template | optional | The name of the template to render, when renderType = RecordDriverTemplate |
 | translate | optional (default = false) | Should we run raw field data through the translator? Applies only when RenderType = Simple. | | translate | optional (default = false) | Should we run raw field data through the translator? Applies only when RenderType = Simple. |
-| translationTextDomain | optional (default = '') | Prefix to apply to value string prior to running text through the translator; most useful for applying a text domain, but may be used for other purposes (for example, 'CreatorRole::' or 'location_'). Applies only when RenderType = Simple. :!: // Introduced in VuFind 4.1. // |+| translationTextDomain | optional (default = '') | Prefix to apply to value string prior to running text through the translator; most useful for applying a text domain, but may be used for other purposes (for example, 'CreatorRole::' or 'location_'). Applies only when RenderType = Simple. :!: // Introduced in VuFind® 4.1. // |
 | useCache | optional (default = false) | Should we cache the raw field data in the view helper to avoid duplicate calls? | | useCache | optional (default = false) | Should we cache the raw field data in the view helper to avoid duplicate calls? |
 +| altDataMethod | optional (default = dataMethod value + "AltScript") | Method for fetching alternative representation of value when renderType is set to CombineAlt. :!: // Introduced in VuFind® 9.1. // | 
 +| combineAltRenderType | optional (default = Simple) | Render type used for values when renderType is set to CombineAlt. :!: // Introduced in VuFind® 9.1. // | 
 +| combineAltTemplate | optional (default = combine-alt) | Name of template for rendering side-by-side values when renderType is set to CombineAlt. :!: // Introduced in VuFind® 9.1. // |
 ===== The Specification Builder ===== ===== The Specification Builder =====
  
-A [[https://github.com/vufind-org/vufind/blob/master/module/VuFind/src/VuFind/View/Helper/Root/RecordDataFormatter/SpecBuilder.php|SpecBuilder]] convenience class has been provided to help generate specification arrays. This handles such functionality as auto-generating useful 'pos' values, reordering/overriding fields, etc.+A [[https://github.com/vufind-org/vufind/blob/dev/module/VuFind/src/VuFind/View/Helper/Root/RecordDataFormatter/SpecBuilder.php|SpecBuilder]] convenience class has been provided to help generate specification arrays. This handles such functionality as auto-generating useful 'pos' values, reordering/overriding fields, etc.
  
 Useful public methods: Useful public methods:
  
 +  * setCombineAltLine($key, $dataMethod, $options = []) - add a CombinedAlt configuration for $key; convenience method wrapped around setLine(), introduced in VuFind® 9.1
   * setLine($key, $dataMethod, $renderType = null, $options = []) - add a configuration for $key; defaults to 'Simple' $renderType   * setLine($key, $dataMethod, $renderType = null, $options = []) - add a configuration for $key; defaults to 'Simple' $renderType
 +  * setMultiLine($key, $dataMethod, $callback, $options = []) - add a multi-function-based configuration for $key; convenience method wrapped around setLine()
   * setTemplateLine($key, $dataMethod, $template, $options = []) - add a template-based configuration for $key; convenience method wrapped around setLine()   * setTemplateLine($key, $dataMethod, $template, $options = []) - add a template-based configuration for $key; convenience method wrapped around setLine()
   * reorderKeys($orderedKeys, $defaultPos = null) - reorder the items within the configuration based on an ordered array of key names   * reorderKeys($orderedKeys, $defaultPos = null) - reorder the items within the configuration based on an ordered array of key names
 ===== Customizing Specifications ===== ===== Customizing Specifications =====
  
-There are two simple ways to change specifications.+There are three simple ways to change specifications. 
 + 
 +==== Option 1: Use Configuration ==== 
 + 
 +Starting in VuFind® 10.0, it is possible to customize record displays using [[https://github.com/vufind-org/vufind/blob/dev/config/vufind/RecordDataFormatter.ini|RecordDataFormatter.ini]] -- see the comments in that file for details and examples. Earlier releases require you to use one of the other two options below. 
 + 
 +==== Option 2: Override the Factory ====
  
-==== Option 1Override the Factory ====+If you want to make global changes to a specification, the easiest solution is to extend [[https://github.com/vufind-org/vufind/blob/dev/module/VuFind/src/VuFind/View/Helper/Root/RecordDataFormatterFactory.php|\VuFind\View\Helper\Root\RecordDataFormatterFactory]] in your own [[development:architecture:customizing_vufind#modules|custom module]] and override getDefaultCoreSpecs() and/or getDefaultDescriptionSpecs() as needed. You can either completely rewrite the spec generation logic, or you can call the parent version of the function and then manipulate the array slightly to add, remove or reorder fields. As an example of array manipulation, this code moves the next and previous titles after the "Language" field.
  
-If you want to make global changes to a specification, the easiest solution is to extend [[https://github.com/vufind-org/vufind/blob/master/module/VuFind/src/VuFind/View/Helper/Root/RecordDataFormatterFactory.php|\VuFind\View\Helper\Root\RecordDataFormatterFactory]] in your own [[development:architecture:customizing_vufind#modules|custom module]] and override getDefaultCoreSpecs() and/or getDefaultDescriptionSpecs() as needed. You can either completely rewrite the spec generation logic, or you can call the parent version of the function and then manipulate the array slightly to add, remove or reorder fields.+<code PHP> 
 +class RecordDataFormatterFactory extends \VuFind\View\Helper\Root\RecordDataFormatterFactory 
 +
 +  public function getDefaultCoreSpecs() 
 +  { 
 +    $spec = new SpecBuilder(parent::getDefaultCoreSpecs()); 
 +    $specArray = $spec->getArray(); 
 +    $specArray['New Title']['pos'= $specArray['Language']['pos'+ 10; 
 +    $specArray['Previous Title']['pos'= $specArray['Language']['pos'] + 20; 
 +    return $specArray; 
 +  } 
 +
 +</code>
  
-==== Option 2: Override the Template ====+In the parent::getDefaultCoreSpecs() code, items are added to the array with 'pos' values automatically assigned in increments of 100 unless explicitly specified. To reorder values or put new fields between existing fields, you can add items with explicit 'pos' values and rely on the re-sorting of the array to display items as desired. 
 +==== Option 3: Override the Template ====
  
 If you want to change behavior for a specific record driver, or if you prefer to keep your code changes at a higher level, you can also customize the appropriate record driver template(s), simply manipulating the spec array between the call to getDefaults() and the call to getData(). If you want to change behavior for a specific record driver, or if you prefer to keep your code changes at a higher level, you can also customize the appropriate record driver template(s), simply manipulating the spec array between the call to getDefaults() and the call to getData().
 ---- struct data ---- ---- struct data ----
 +properties.Page Owner : 
 ---- ----
  
development/architecture/record_data_formatter.1525872627.txt.gz · Last modified: 2018/05/09 13:30 by demiankatz