Skip to content

Latest commit

 

History

History
231 lines (174 loc) · 18.4 KB

README.markdown

File metadata and controls

231 lines (174 loc) · 18.4 KB
Raw

pazpar2 TYPO3 extension

A TYPO3 extension for including a bibliographic metasearch.

The extension only makes sense if you are running Indexdata’s pazpar2 bibliographic metasearch software on your server.

2010-2011 by Sven-S. Porst, SUB Göttingen <porst@sub.uni-goettingen.de>

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 Indexdata 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 two plug-ins for content elements that let the user initiate search queries and display the results:

  • pazpar2 offering a standard search interface with a search field and extended search options
  • 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 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 run the extension’s code, you need:

  • TYPO3 ≥ 4.5.3
  • with Extbase/Fluid ≥ 1.3
  • the t3jquery extension injecting at least jQuery 1.6 into the pages (jQuery 1.7.0 is buggy and will not work well, use at least 1.7.1 if you need 1.7)

pazpar2

For searches to work and results to be displayed correctly you need

  • pazpar2 ≥ 1.6.2
  • … running at or proxied to the path /pazpar2/search.pz2 on your server (see Indexdata’s instructions on how to proxy it there) ** the implementation also supports displaying additional access information which is provided by the pazpar2-access proxy
  • See below for more details on the assumptions the extension makes regarding pazpar2’s search key and metadata normalisation setup.

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 [https://github.com/ssp/Opac-2-Atom Opac-2-Atom] project for an example script converting Göttingen’s Pica Opac output to Atom.

Setup

Insert the pazpar2 [Neuerwerbungen] content element where you need it and make sure the pazpar2 Settings static include is added for the relevant pages.

Flexform

Fields of the flexform for the content element in the backend 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. [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 »NA« in the subject hierarchy of the nkwgok extension. This is probably useful for SUB Göttingen use only.

Typo Script

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.

  • 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
    • triggeredByNKWGOKMenu [0]: if 1, search will be triggered by selections from menus displayed by the nkwgok extension (probably useful for SUB Göttingen setup only)
    • allowExtendedSearch [1]: if 1, the link to show the extended search form is displayed
    • fulltextSearch [2]: 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 [1]: 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
    • mainSearchFieldPlaceholder [0]: HTML5 placeholder string to be put into the main search field; available options are: 0 -> blank, 1 -> Search Term, 2 -> additional Search term
    • 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 \n 1.direction = descending \n 2.fieldName = author \n 2.direction = ascending \n 3.fieldName = title \n 3.direction = ascending}]
  • Results display:
    • provideCOinSExport [1]: if 1, causes invisible COinS metadata to be inserted into the result lists. It will be used by Zotero to automatically find bibliographics 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 = 1\n bibtex = 1}]: an array with export format names as keys set to the value 1. Based on this list links to downloads of bibliographic metadata are added to the detail view of records. You can empty this array to remove the export links from the detail view. 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 name replace the current page with the bibliographic data.
    • showKVKLink [1]: 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
    • preferSUBOpac [0]: if 1, links to GVK catalogue pages are mapped to the SUB Göttingen Opac for people with 134.76.* IP addresses, to provide greater convenience for Göttingen user
    • 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
  • included files:
    • CSSPath [EXT:pazpar2/Resources/Public/pz2.css]: CSS file included to style the search form and search results
    • pz2JSPath [EXT:pazpar2/Resources/Public/pz2.js]: Indexdata’s pz2.js library to communicate with the pazar2 service
    • pz2-clientJSPath [EXT:pazpar2/Resources/Public/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/flot/jquery.flot.js]: flot graphing library
    • flotSelectionJSPath [EXT:pazpar2/Resources/Public/flot/jquery.flot.selection.js]: selection component of flot graphing library
  • tx_pazpar2_pazpar2-neuerwerbungen
    • useAtomFeed [1]: if 1, a link to an Atom feed is displayed along with the Neuwerbungen form and inserted into the page’s
    • numberOfMonths [13]: the number of months to display in the popup menu for date selection
    • pz2-neuerwerbungenCSSPath [EXT:pazpar2/Resources/Public/pz2-neuerwerbungen.css]: Additional CSS file included if the pazpar2-neuerwerbungen plug-in is used
    • pz2-neuerwerbungenJSPath [EXT:pazpar2/Resources/Public/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)
  • title
  • journal - for journal title search
  • person
  • date
  • nel - month index required by pazpar2 Neuewerbungen only (required format: YYYYMM)
  • subject

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:

  • date
  • medium
  • title
  • title-remainder
  • title-number-section
  • multivolume-title (not part of standard tmarc.xsl)
  • series-title
  • title-responsibility
  • 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
  • doi (not part of standard tmarc.xsl)
  • electronic-url
  • edition
  • publication-name
  • publication-place
  • physical-extent
  • description
  • id
  • 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 ard setup for the various targets.)
  • subject

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
  • 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)
  • 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/convert-pazpar2-record.php is run.

Conversions done by that script use the stylesheets in Resources/Private/XSL. 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 a stylesheet to the Resources/Private/XSL folder, registering it for a format name in the Array the beginning of Resources/Public/convert-pazpar2-record.php and adding the display strings for that format to Resources/Public/pz2-client.js as well as to Resources/Private/Language/locallang.xml

Acknowledgements

Many thanks go to Indexdata 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.

Version History

  • 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

License

MIT License to keep the people happy who need it.

Copyright (C) 2010-2011 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.