A TYPO3 extension to include a bibliographic metasearch with Index Data’s pazpar2 software on web pages.
2010-2014 by Sven-S. Porst <[email protected]>
The extension includes the flot and jQuery Storage API JavaScript libraries.
Feel free to send in comments or contribute improvements. You can fork the extension’s repository at github.
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 on the vifanord and Library of Anglo-American Culture sites.
To use this extension successfully you need:
- TYPO3 ≥ 6.1.5
- the t3jquery Extension
supplying at least jQuery 1.7.1 (compatible with jQuery ≥ 1.9) on your pages
- 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
- pazpar2 ≥ 1.6.39
- 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 searches to work and results to be displayed correctly with the
pazpar2 plug-in you need pazpar2 ≥ 1.6.39 available at a URL on your
web server (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.
For searches to work and results to be displayed correctly with the
pazpar2 Service Proxy plug-in, you need pazpar2 ≥ 1.6.39 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).
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.
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 configuration is available for the pazpar2 and pazpar2
Neuerwerbungen content elements and offers the following options.
To fully configure the extension from TypoScript, use the flexformOverride
setting with the keys given in [] to override the value from the Flex Form.
- 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 thesid
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.
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.
pazpar2Path
[/pazpar2/search.pz2
]: absolute path to pazpar2 service on the web server
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 componentallowExtendedSearch
[1
]: if1
, the link to show the extended search form is displayedfulltextSearch
[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 searchjournalTitleOnlySearch
[0
]: if1
, the checkbox to search journal titles only is displayed in the extended search formdateSearch
[1
]: if1
, the date field is displayed in the extended search formsortConfiguration
[{1{id=date default=1 order{1.fieldName=date 1.direction=descending 2.fieldName=author 2.direction=ascending}}
]: the sort order to use; array entries: items for the sort order menu which is hidden by the default CSS. Each item has anid
and aorder
configuration. The configuration is a list of objects with keysfieldName
anddirection
.triggeredByNKWGOK
[0
]: if1
, search will be triggered by selections from subject hierarchies displayed by the nkwgok extension (presumably useful for SUB Göttingen setup only)- Override localisations of strings in the form using
plugin.tx_pazpar2._LOCAL_LANG.[en|default]
, the strings used in the search form can be overwritten; You can override the strings inResources/Private/Language/locallang.xml
, as well as those in thelocalisations
object of pz2-client.
resultsPerPage
[100
]: number of results to display on each page. Should be one of10
,20
,50
,100
if you plan to let users select the number
usePazpar2Facets
[0
]: if0
, create facets in the browser (smoother to use, works well with small result sets); if1
use pazpar2’s own facets (preferable for large result sets)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 keymaxFetch
with value the maximum number of facet items to display and the keyminDisplay
with value the minimum number of facets required for this facet to appear. ThefilterDate
facet used by default is generated automatically by the script whenusePazpar2Facets
is set to0
– otherwise usedate
instead
useKeywords
[0
]: if1
, thesubject
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 thesubject
index and including thesubject
field in brief formatuseMaps
[1
]: if1
, enables the display of Google Maps with markers for areas covered by the record displayed
provideCOinSExport
[1
]: if1
, 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=0 bibtex=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
andbibtex-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
]: if1
, for records with 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 linksshowOpenURLLink
[0
]: if1
, a link to an OpenURL resolver is included with the export links; you can set its baseURL using theopenURLBaseURL
key of theexport
localisation dictionary
autocompleteURLs
[]: 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 JavaScriptfunction (URL, fieldName)
that is run when setting up the autocomplete feature. Returns an object for configuring jQuery UI’s autocomplete widget. Functionspz2client.autocompleteSetupArray
for sources that return JSON arrays,pz2client.autocompleteSolrSpellcheck
for querying a Solr spellcheck component andpz2client.autocompleteSetupHistory
for using recent search queries (see below) are predefined.
historyItems
[99
]: Number of recent search queries to store when local storage is available; set to0
to deactivateaddHistoryLink
[0
]: if1
, add a link for showing the recent search terms insidediv.pz2-featureLinks
at the beginning of#pazpar2
(alternatively you can usepz2client.autocompleteSetupHistory
asautocompleteSetupFunction
to expose recent search terms via autocompletion)
useClipboard
[0
]: if1
, offer storing results in the clipboard when local storage is availableaddClipboardLink
[0
]: if1
, add a link for showing the clipboard insidediv.pz2-featureLinks
at the beginning of#pazpar2
highlightSearchTerms
[0
]: if1
, try to highlight the search terms found in the results’ fields
CSSPath
[EXT:pazpar2/Resources/Public/pz2-client/pz2.css
]: CSS file included to style the search form and search resultspz2-clientJSPath
[EXT:pazpar2/Resources/Public/pz2-client/pz2-client.min.js
]: JavaScript handling the user interaction and display of resultsflotJSPath
[EXT:pazpar2/Resources/Public/pz2-client/jquery.flot+selection.min.js
]: flot graphing library with selection modulejquery-storageJSPath
[EXT:pazpar2/Resources/Public/pz2-client/jquery-storage/jquery.storageapi.min.js
]: jQuery Storage API module
serviceProxyAuthPath
[/service-proxy-auth
]: absolute path to Service Proxy authentication on the web serverserviceProxyPath
[/service-proxy/
]: absolute path to Service Proxy on the web serverpz2urlrecipeJSPath
[EXT:pazpar2/Resources/Public/pz2-client/mk2.js
]: JavaScript for applying URL recipes
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 selectionpz2-neuerwerbungenCSSPath
[EXT:pazpar2/Resources/Public/pz2-client/pz2-neuerwerbungen.css
]: Additional CSS file included if the pazpar2-neuerwerbungen plug-in is usedpz2-neuerwerbungenJSPath
[EXT:pazpar2/Resources/Public/pz2-client/pz2-neuerwerbungen.js
]: Additional JavaScript included if the pazpar2-neuerwerbungen plug-in is used
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.
The search forms provided by the plug-ins use the following search keys which must be set up in the pazpar2 service:
term
- for default searchfulltext
- for fulltext/toc search (use same as term if not available) [if thefulltextSearch
setting is1
]title
journal
- for journal title search [if thejournalTitleOnlySearch
setting is1
]person
date
nel
- month index required by pazpar2 Neuerwerbungen only (required format:YYYYMM
)subject
[if theuseKeywords
setting is1
]
The standard configuration requires the pazpar2 service to support
sorting by the metadata fields date
and author
. It can be
reconfigured using the sortConfiguration
TypoScript setting.
For example – if you want to offer a refined sorting by date, author and relevance and have the fields involved in this set up in your pazpar2 metadata configuration, you can use the TypoScript setup:
plugin.tx_pazpar2.settings.sortConfiguration { 1 { id = date default = 1 order { 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 } } 2 { id = author order { 1.fieldName = author 1.direction = ascending 2.fieldName = date 2.direction = descending } } 3 { id = relevance order { 1.fieldName = relevance 1.direction = descending 2.fieldName = date 2.direction = descending 3.fieldName = author 3.direction = ascending } } }
The metadata expected by the extension to display results are based on the metadata fields created by Index Data’s powerful tmarc.xsl stylesheet for extracting information from MARC records. In particular we are using a slightly extended version of tmarc.xsl to improve the display quality even further.
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)corporate
(not part of standard tmarc.xsl)meeting
(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 JavaScriptabstract
(not part of standard tmarc.xsl)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 pagecreator
(used for Guide records)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 target.
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 the localisation.
The extension can provide the full set of records retrieved from the pazpar2 service for the query. To retrieve it, use the following URL parameters in addition to those for the query:
tx_pazpar2_pazpar2[useJS]:no
- force PHP to run the pazpar2 querytx_pazpar2_pazpar2[maximumResults]:10000
- set the number of results you want to retrieve; for large result sets beware of PHP running out of memorytx_pazpar2_pazpar2[format]:json
- JSON outputtype:1393975639
- page type without template andapplication/json
MIME-Type
The resulting JSON object has two keys:
results
- an object of the pazpar2 results * keys: pazpar2 merge keys * values: pazpar2 records as converted to arrays by TYPO3’sxml2array
functionstat
- the last pazpar2 stat reply (to make errors available to the consumer)
- originally created 2010-2013 for SUB Göttingen, many thanks to Ingo Pfennigstorf for his TYPO3 help
- with Service Proxy improvements 2013 for Index Data
- with improvements 2014 for vifanord
- includes media type icons by Henrik Cederblad
- WAI-ARIA support
- HTML5 History support?
- 5.0.1 (2014-03-07)
- improve compatibility with old / weirdly configured IE versions
- 5.0.0 (2014-03-06)
- Require TYPO3 6.1
- Require t3jquery
- Change certain aspects of the configuration (localisation, sort) and setup that will require users with customisations to review those
- Make use of localisation for target names obligatory
- pz2-client:
- Complete restructuring
- Re-introduce ability to use pazpar2’s native facets
- Add Clipboard
- Add Search History
- Add Search Term Highlighting
- Add Open URL link in detail view
- Re-work sort order configuration
- Display
corporate
andmeeting
fields - Add
settings.flexformOverride
to configure without the Flex Form - Add JSON/XML output of all search results
- 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]
- sort by
- 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 thesource-type
field
- 1.7.0 (2012-03-30)
- display the location covered by maps from the
coordinates
attribute of themapscale
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
- display the location covered by maps from the
- 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
- add class
- 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
MIT License to keep the people happy who need it.
Copyright (C) 2010-2014 by Sven-S. Porst
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.