subugoe/pazpar2

Pazpar2 for TYPO3

Maintainers

Details

github.com/subugoe/typo3-pazpar2

Source

Issues

Installs: 1 133

Dependents: 0

Suggesters: 0

Security: 0

Stars: 3

Watchers: 8

Forks: 6

Open Issues: 3

Type:typo3-cms-extension

6.0.3 2017-09-12 13:12 UTC

GPL-2.0+ db1eefff7d193b8b5aa0d3b57f503115d46cbddf

  • Ingo Pfennigstorf <pfennigstorf.woop@sub.uni-goettingen.de>

This package is auto-updated.

Last update: 2024-04-11 17:26:57 UTC

README

A TYPO3 extension to include a bibliographic metasearch with Index Data’s pazpar2 software on web pages.

Created by SUB Göttingen

The extension includes the flot JavaScript library for drawing graphs.

Feel free to send in comments or contribute improvements. You can fork the extension’s repository at github.

Introduction

pazpar2 is a bibliographic metasearch software by Index Data for querying multiple Solr, SRU and Z39.50 servers, normalising, merging and deduplicating the results and providing them for presentation.

The pazpar2 TYPO3 extension provides three plug-ins for content elements that let the user initiate search queries and display the results:

  • pazpar2 offering a standard search interface for a pazpar2 service with a search field and extended search options
  • pazpar2 Service Proxy the same search interface for pazpar2 accessed through Service Proxy
  • pazpar2neuerwerbungen which offers checkboxes, the state of which determines the search queries (this has been designed for the specific needs of SUB Göttingen, relies on the nkwgok subject tree TYPO3 extension and is unlikely to be useful elsewhere)

You can see the extension in use at the Library of Anglo-American Culture site which uses the pazpar2 plug-in on its home page and the pazpar2neuerwerbungen plug-in on its New Acquisitions page.

Requirements

To use this extension successfully you need:

TYPO3

  • TYPO3 ≥ 6.2.0
  • at least jQuery 1.7.1 (compatible with jQuery ≥ 1.9) on your pages; use the t3jquery extension for that
    • when using autocomplete you need jQuery UI with the Autocomplete, Menu and Position modules
    • make sure you have the CSS for a jQuery UI theme included in your site to get a correct look
    • PHP XSL Extension
  • pazpar2 ≥ 1.6.2
    • The extension works pretty well with the metadata fields created by pazpar2’s tmarc.xsl. See the section pazpar2 Setup for additional metadata features supported by the extension.

For using this extension directly from git, be sure to run git submodule update --init after cloning this extension.

pazpar2

For searches to work and results to be displayed correctly with the pazpar2 plug-in you need pazpar2 ≥ 1.6.2 available at a URL on your webserver (by default at the path /pazpar2/search.pz2, see Index Data’s instructions on how to proxy it there).

The plug-in supports displaying additional access information as provided by the pazpar2-access proxy.

pazpar2 Service Proxy

For searches to work and results to be displayed correctly with the pazpar2 Service Proxy plug-in, you need pazpar2 ≥ 1.6.2 available through Service Proxy at a URL on your webserver (by default at the path /service-proxy/ for the service itself and /service-proxy-auth for authentication).

pazpar2 Neuerwerbungen

For the pazpar2-neuerwerbungen plug-in to be useful you additionally need:

  • nkwgok extension
  • subject hierarchies that are children of the PPN »NE« imported into the nkwgok extension
    • The extension is designed primarily for the case where just two levels of hierarchy exist. The elements on level 1 provide grouping with a label, those on level two the child elements of a group. If the parent element has a blank search query, its search query is generated by OR-ing the queries of all child elements together. To avoid having complex queries, a simpler query giving the same result set can be explicitly provided. Child elements may not have exactly the same search query as their parent element.
  • if you want to provide RSS feeds for new acquisitions, a script accepting queries in the »q« parameter is expected at the path /opac.atom. See the Opac-2-Atom project for an example script converting Göttingen’s Pica Opac output to Atom.

Setup

Insert the pazpar2 [Neuerwerbungen|Service Proxy] content element where you need it and make sure the pazpar2 Settings static include is added for the relevant pages. Looking at the illustrated setup example may make this easier.

Flex Form

Flex Form configuration is available for the pazpar2 and pazpar2 Neuerwerbungen content elements and offers the following options. The name of the corresponding TypoScript parameter is noted in [].

  • pazpar2 service ID [serviceID]: needs to be the name of a service set up on your pazpar2 server or empty if there is only a single unnamed service running
  • Google Books [useGoogleBooks]: Choose whether the extension should try to look up all records with ISBN and OCLC numbers on Google books once the full record is revealed and try to display the cover art and offer the book preview if possible. If this option is turned on, the plug-in will load and run a JavaScript from Google’s servers on the page the content element is inserted in.
  • Journals Online & Print [useZDB]: Choose whether the extension should try to look up all records with ISSN numbers using ZDB’s Journals Online & Print (JOP) service. If this option is turned on, the plug-in will load information about journal availability from the ZDB Proxy on your server (see the next option) to display the availability of the journal.
  • ZDB Proxy [ZDBIP]: You can set up two distinct proxies for the ZDB JOP service if you plan to use it. The one available at the path /zdb/ on your server should pass the user’s IP address to the ZDB JOP service, thus returning the journal availability for the user’s current location. The one available at /zdb-local/ will do the lookup for the server’s IP address – with the intention to provide availability information for the institution running the server. This option lets you pick which of the proxies will be used for the ZDB JOP lookup. Either proxy configuration needs to contain the sid parameter with your service name. [Apache configuration file for setting up the proxies]
  • Histogram [useHistogramForYearFacets]: The extension displays year facets if results from more than a few years are displayed. Choose whether the year facets should be displayed graphically using a histogram rather than as an (incomplete) list of year numbers in modern browsers. Activating this option will load the flot JavaScript library from your server on the relevant pages.
  • Subjects for pazpar2 Neuerwerbungen [neuerwerbungen-subjects]: A subject has to be picked in the popup menu if you want to use the pazpar2 Neuerwerbungen plug-in. The popup menu is populated using child elements of the PPN »NE« in the subject hierarchy of the nkwgok extension. This is probably useful for SUB Göttingen use only.

TypoScript

In addition to the options exposed in the flexform, a number of additional options can be set using TypoScript in plugin.tx_pazpar2.settings. The default value is noted inside [] after the option name.

  • pazpar2 configuration:
    • pazpar2Path [/pazpar2/search.pz2]: absolute path to pazpar2 service on the web server
  • Search form:
    • showSearchForm [1]: if 1, the search form is shown in the pazpar2 plug-in; turning off the search form still provides the pazpar2 search and result display capabilities which you may want to trigger from your own component
    • autcompleteURLs []: an array with keys: field names (e.g. all, title, person) and values: URLs to which the search term can be appended to create a query for an autocompletion list.
    • autocompleteSetupFunction []: name of a JavaScript function (URL, fieldName) that is run when setting up the autocomplete feature. Returns an object for configuring [jQuery UI’s autocomplete widget](http://api.jqueryui.com/autocomplete/). FunctionsautocompleteSetupArrayfor sources that return JSON arrays andautocompleteSolrSpellcheck` for querying a Solr spellcheck component are predefined.
    • allowExtendedSearch [1]: if 1, the link to show the extended search form is displayed
    • fulltextSearch [0]: configure checkbox to do full text search in the extended search form; 0 -> not shown, 1 -> labelled for full text search, 2 -> labelled for table of contents search
    • journalTitleOnlySearch [0]: if 1, the checkbox to search journal titles only is displayed in the extended search form
    • dateSearch [1]: if 1, the date field is displayed in the extended search form
    • useSortMenu [0]: if 1 a HTML select element letting the user pick the sort order is included in the search form
    • sortOrder [{1.fieldName = date 1.direction = descending}]: the sort order to use; the array may have additional entries to determine the sort order in the case of equality of the precedeing criteria; The fieldNames must be set up in the pazpar2 service’s metadata configuration. More complex example: {1.fieldName = date 1.direction = descending2.fieldName = author 2.direction = ascending 3.fieldName = title 3.direction = ascending 4.fieldname = title-number-section ` 4.direction = ascending}
    • triggeredByNKWGOK [0]: if 1, search will be triggered by selections from subject hierarchies displayed by the nkwgok extension (presumably useful for SUB Göttingen setup only)
    • Override localisations: Using plugin.tx_pazpar2._LOCAL_LANG.[en|default], the strings used in the search form can be overwritten; You can override the strings in Resources/Private/Language/locallang.xml, as well as those in the localisations object at the end of Resources/Public/pz2-client/pz2-client.js and the objects linkDescriptions, mediaTypeNames, catalogueNames (by prefixing their keys with link-description-, media-type- and catalogue-name- respectively. Example: plugin.tx_pazpar2._LOCAL_LANG.en.link-description-Link = Go to Resource.
  • Results display
    • resultsPerPage [100]: number of results to display on each page. Should be one of 10, 20, 50, 100 if you plan to let users select the number
    • useMaps [1]: if 1, enables the display of Google Maps with markers for areas covered by the record displayed
    • provideCOinSExport [1]: if 1, causes invisible COinS metadata to be inserted into the result lists. It will be used by Zotero to automatically find bibliographic records displayed in the page. Note that Zotero 3 is the first version capable of discovering COinS data that are dynamically added to the page.
    • exportFormats [{ris = 0bibtex = 0}]: an array with export format names as keys. Set the value to 1/0 to enable/disable a specific format. For active formats links to downloads of bibliographic metadata are added to the detail view of records. Permitted keys are: ris, bibtex, ris-inline and bibtex-inline for RIS and BibTeX formats. The plain names cause a download of the file, the -inline names replace the current page with the bibliographic data.
    • showKVKLink [0]: for records with an ISBN or media type book a link to the metasearch across German union catalogues in Karlsruhe Virtual Catalogue (KVK) is added along with the export links
    • useKeywords [0]: if 1, the Keywords search field is offered in extended search and keywords are displayed in result details, each linking to a search for the keyword in question; requires pazpar2’s targets to be configured for keyword searches on the »subject« index
    • termLists [{xtargets {maxFetch = 25 minDisplay = 1} medium {maxFetch = 12 minDisplay = 1} language {maxFetch = 5 minDisplay = 1} filterDate {maxFetch = 10 minDisplay = 1}}]: Configuration which facets will be displayed. Set up an array with the pazpar2 metadata field names as keys and arrays as values. The arrays contain the key maxFetch with value the maximum number of facet items to display and the key minDisplay with value the minimum number of facets required for this facet to appear. The filterDate facet used by default is generated automatically by the script from the date field.
  • included files:
    • CSSPath [EXT:pazpar2/Resources/Public/pz2-client/pz2.css]: CSS file included to style the search form and search results
    • pz2JSPath [EXT:pazpar2/Resources/Public/pz2-client/pz2.js]: Index Data’s pz2.js library to communicate with the pazar2 service
    • pz2-clientJSPath [EXT:pazpar2/Resources/Public/pz2-client/pz2-client.js]: JavaScript handling the user interaction and display of results; a lot of the customisation is in here
    • flotJSPath [EXT:pazpar2/Resources/Public/pz2-client/flot/jquery.flot.js]: flot graphing library
    • flotSelectionJSPath [EXT:pazpar2/Resources/Public/pz2-client/flot/jquery.flot.selection.js]: selection component of flot graphing library
  • plugin.tx_pazpar2_pazpar2serviceproxy.settings
    • serviceProxyAuthPath [/service-proxy-auth]: absolute path to Service Proxy authentication on the web server
    • serviceProxyPath [/service-proxy/]: absolute path to Service Proxy on the web server
    • pz2urlrecipeJSPath [EXT:pazpar2/Resources/Public/pz2-client/mk2.js]: JavaScript for applying URL recipes
  • plugin.tx_pazpar2_pazpar2neuerwerbungen.settings
    • useAtomFeed [1]: if 1, a link to an Atom feed is displayed along with the Neuerwerbungen form and inserted into the page’s <head>
    • numberOfMonths [13]: the number of months to display in the popup menu for date selection
    • pz2-neuerwerbungenCSSPath [EXT:pazpar2/Resources/Public/pz2-client/pz2-neuerwerbungen.css]: Additional CSS file included if the pazpar2-neuerwerbungen plug-in is used
    • pz2-neuerwerbungenJSPath [EXT:pazpar2/Resources/Public/pz2-client/pz2-neuerwerbungen.js]: Additional JavaScript included if the pazpar2-neuerwerbungen plug-in is used

pazpar2 Setup

pazpar2 services used by the extension need to have specific settings for the search keys as well as for the metadata they provide for the searches to work and the quality of the displayed data to be reasonable.

Search keys

The search forms provided by pazpar2 use the following search keys which must be set up in the pazpar2 service:

  • term - for default search
  • fulltext - for fulltext/toc search (use same as term if not available) [optional]
  • title
  • journal - for journal title search [optional]
  • person
  • date
  • nel - month index required by pazpar2 Neuerwerbungen only (required format: YYYYMM)
  • subject [optional]

Sorting

The standard configuration requires the pazpar2 service to support sorting by the metadata fields date. It can be reconfigured using the sortOrder TypoScript setting.

For example – if you have those fields set up in your metadata configuration – you get better results by using date, author, title, title-number-section using the TypoScript setup:

plugin.tx_pazpar2.settings.sortOrder {
    1.fieldName = date
    1.direction = descending
    2.fieldName = author
    2.direction = ascending
    3.fieldName = title
    3.direction = ascending
    4.fieldName = title-number-section
    4.direction = ascending
}

Metadata format

The metadata expected by the extension to display results are based on the metadata fields created by Indexdata’s powerful tmarc.xsl style file for extracting information from Marc records. A few additions and changes to the standard output of that stylesheet have been made to improve the display quality.

Fields used to display data if present:

  • id
  • medium
  • title
  • title-remainder
  • title-number-section
  • title-responsibility
  • date
  • multivolume-title (not part of standard tmarc.xsl)
  • series-title
  • author
  • other-person (not part of standard tmarc.xsl)
  • journal-title
  • journal-subpart
  • volume-number
  • issue-number
  • pages-number
  • isbn
  • issn
  • pissn (not part of standard tmarc.xsl)
  • eissn (not part of standard tmarc.xsl)
  • oclc-number
  • zdb-number
  • doi (not part of standard tmarc.xsl)
  • electronic-url
  • edition
  • publication-name
  • publication-place
  • physical-extent
  • description
  • language - ISO 639-2/B language code (not part of standard tmarc.xsl), German and English language names are included in the JavaScript
  • abstract (not part of standard tmarc.xsl)
  • creator (used for Guide links)
  • catalogue-url (URL linking to the catalogue web page for that record, built using the stylesheets and setup for the various targets.)
  • parent-catalogue-url (URL linking to the catalogue web page for related records to the current record, typically the containing parent collection.)
  • subject
  • classification-msc (not part of standard tmarc.xsl)
  • mapscale (not part of standard tmarc.xsl), display the scale of maps and potentially draw the region covered by the map on an interactive map on the web page
  • country (not part of standard tmarc.xsl, used for Guide records)
  • source-type (not part of standard tmarc.xsl, used for Guide records)

For the 'medium' field, the supported types (with a localised name and icon) are. Most of them come from standard tmarc.xsl analysis of MARC records. A few depend on our refinements of tmarc.xsl and additional information/analysis.

  • article
  • audio-visual (may require tmarc.xsl output to be stripped of more specific media type information like dvd)
  • book
  • data (not part of tmarc.xsl)
  • electronic
  • image (not part of tmarc.xsl)
  • journal
  • letter (not part of tmarc.xsl)
  • manuscript (changed tmarc.xsl to recognise these)
  • map
  • microform
  • music-score
  • multivolume (extended tmarc.xsl to recognise these)
  • newspaper
  • recording
  • website (used for websites as found in SUB’s SSG-FI Guides, not coming from tmarc.xsl)
  • multiple (used for merged records of varying media types as well as mixed-media items)

To get a better idea of the general setup, take a look at our setup files, particularly the AAC service and the gbv-sru-neu target. Some of our stylesheets may be helpful as well, particularly those for ISO 639-2 cleaning and ISO 639-1 to 639-2/B conversion.

Bibliographic data export

To create proper downloads these are created in a slightly involved way by sending the pazpar2 metadata back to server where the script Resources/Public/pz2-client/converter/convert-pazpar2-record.php is run.

Conversions done by that script use the stylesheets in Resources/Public/pz2-client/converter. The conversion quality achieved by those scripts is somewhat limited on a syntactic level due to the inadequacies (RIS is defined to be non-Unicode but we, like many others, send UTF-8 to accomodate non-Latin references as well) or complexities (getting BibTeX escaping right is a major effort [and occasionally undesirable as some mathematical sites includ TeX code which benefits from not being escaped] so the lazy compromise is to send UTF-8 as well).

Support for additional formats can be added to the extension by adding an XSL file to the Resources/Public/pz2-client/converter folder, registering it for a format name in the Array the beginning of Resources/Public/pz2-client/converter/convert-pazpar2-record.php and adding the display strings for that format to Resources/Public/pz2-client/pz2-client.js as well as to Resources/Private/Language/locallang.xml

Acknowledgements

Many thanks go to Index Data for their powerful pazpar2 software and quick bug fixes, to my colleague Ingo Pfennigstorf for his TYPO3 expertise and to Henrik Cederblad who created the media type icons.

TODO

  • WAI-ARIA support
  • investigate using pazpar2’s faceting again (following the latest improvements)
  • HTML5 History support?

Version History

4.0.4 (2013-10-25)
  • Readme fixes
4.0.3b (2013-09-26)
  • JavaScript fixes
4.0.2b (2013-09-16)
  • Switch to icon fonts for media types
4.0.1b (2013-08-15)
  • Silly bump of version number to help the confused TER
4.0.0b (2013-08-15)
  • Silly bump of version number to help the confused TER
3.0.1b (2013-07-30)
  • improvements to README, JavaScript client and configuration files
3.0.0b (2013-07-17)
  • add new Plug-In »pazpar2 Service Proxy« for use with Service Proxy
  • process electronic-url fields in Service Proxy plugin
  • support loading autocomplete lists for the form fields
  • add class pz2-electronic-url to links
  • allow overriding JavaScript localisations from TypoScript
  • make number of results per page configurable from TypoScript
2.4.1 (2013-05-10)
  • fix KVK links
  • improve map display
  • improve configuration for turning off export formats
  • make pazpar2 service path configurable in JavaScript
2.4.0 (2013-02-28)
  • sort by title-number-section for identical titles
  • add fake manual for the benefit of TER
  • avoid warning in View Helper
  • add ID to CSS classes in the neuerwerbungen template [dsimm]
2.3.0 (2012-12-19)
  • adapt to new nkwgok database field names
2.2.2 (2012-12-17)
  • fix punctuation problems in md-title-responsibility
2.2.0 (2012-12-12)
  • display fewer ISBNs (JS)
  • fix count of additional facets
  • avoid duplicate facet list updates
  • adapt Neuerwerbungen month queries to new GBV Index format
2.1.0 (2012-09-20)
  • more generic display of journal information for articles
  • better handling of subject search when extended search is not available
  • use ZDB IDs to determine journal availability if no ISSN is available
  • make »No matching Records« display more visible
2.0.0 (2012-06-13)
  • cooperation with nkwgok requires at least version 2 of that extension
  • display improvements
  • support MathJax
  • add visible link to hide the status panel
  • fix bug in Google Books links
1.8.0 (2012-05-29)
  • fix localisation for keyword search field label
  • enable use of boolean operators in extended search fields
  • add display of MSC classification
  • make facet configuration accessible from TypoScript
  • add ability to display facets for the country field containing ISO 3166-1 alpha-2 country codes and the source-type field
1.7.0 (2012-03-30)
  • display the location covered by maps from the coordinates attribute of the mapscale field
  • Display the scale of maps from the mapscale field
  • Remove ZDB-JOP sid configuration from script, it has to be inserted into the URL by the proxy now
  • Add ability to display a link to the parent record (catalogue-url-parent field)
  • Remove hard coded recognition and rewriting of Göttingen OPAC URLs, the same effect is achieved more generically by using at least revision v2 of pazpar2-access
1.6.0 (2012-02-24)
  • restructure Resources/Public to provide the JavaScript interface as a standalone repository: pazpar2-js-client
  • change date format for Neuerwerbungen to YYYYMM
  • improved reliability of triggering the pazpar2 search
1.5.0 (2012-01-18)
  • add Geo-specific placeholder search term to main search field configuration
  • add second set of paging controls beneath the results
  • work around localisation breakage of TYPO3 4.6
1.4.0 (2012-01-16)
  • add keyword search and ability to display keywords in result details
  • add support for additional media types (letter, manuscript, image)
  • small display tweaks
  • stop using deprecated form field View Helper
1.3.0 (2011-12-02)
  • Neuerwerbungen: number of months in popup menu is now configurable in TypoScript
  • if there is just single checkbox, automatically select it
1.2.0 (2011-11-25)
  • add links to show all facets when facets needed to be hidden
  • more reliable tooltip hiding for histogram
  • require nkwgok 1.2.0 or above and use its updated database schema for Neuerwerbungen
1.1.5 (2011-11-23)
  • fix Piwik tracking for metadata export links
1.1.4 (2011-11-22)
  • make automatic query starting more reliable in Neuerwerbungen
  • prevent incorrect usage of the no-JavaScript code path
1.1.3 (2011-11-21)
  • reduce maximum GET query length for pz2.js to 512 (the default limit set by Suhosin on SLES 11)
  • improve Content-Type header information for export formats
1.1.2 (2011-11-21)
  • do not add access information to Fluid template when the query did not run in PHP
1.1.1 (2011-11-17)
  • recognise Göttingen OPAC https URLs
  • fix recognition of Guest access
  • improve automatic restarting of searches on session loss
1.1 (2011-11-15)
  • support Piwik tracking
  • support for pazpar2-access proxy
  • improve URL sorting
  • improve location sorting
  • better total result count in non-JavaScript version
  • leaner Fluid templates
  • single year selection in year histogram
1.0.3 (2011-09-22)
  • add class pz2-neuerwerbungen to container when using Neuerwerbungen
1.0.2 (2011-09-21)
  • add information about feed link to README
  • make Neuerwerbungen feed link optional
  • make fulltext checkbox in extended search form configurable
  • make date field in extended search form configurable
  • fix problem with passed parameters in Neuerwerbungen no-JS mode
  • make catalogue names localisable
1.0.1 (2011-09-20)
  • add icon
  • fix problem with losing the user’s data after sending the form
  • preserve the fulltext setting
1.0.0 (2011-09-19)
  • initial release to TER