A JavaScript client to interact with Index Data’s pazpar2 metasearch software and to display its search results.
2010-2014 by Sven-S. Porst ssp-web@earthlingsoft.net
An example implementation of the markup for use in the TYPO3 content management system is provided by the »pazpar2« TYPO3 extension, available via the TYPO3 Extension Repository as well as github.
This extension and the markup it creates can be seen in use on the Lib AAC or vifanord website.
Source code is inside the src folder.
To »build« the script you need nodejs and Grunt. Inside the pazpar2-client folder run npm install and then grunt. If you plan to edit pz-client.js you can use grunt watch.
Include pz2-client.min.js and pz2.css in your HTML file to load the resources provided by pz-client.
For the scripts to operate successfully, you will need:
- for direct pazpar2 use: a pazpar2 server (or a reverse proxy forwarding to it) set up at the path
/pazpar2/search.pz2of your web server [example apache configuration]. This can be overriden by setting the JavaScript variablepazpar2Pathbefore loading pz2-client.js. - for pazpar2 use through Service Proxy: Service Proxy (or a reverse proxy forwarding to it) set up at the path
/service-proxy/and Service Proxy Authentication set up at the path/service-proxy-auth. This can be overriden by setting the JavaScript variablesserviceProxyPathandserviceProxyAuthPathbefore loading pz2-client.js. - your results will be best if you use the same metadata fields we do. These are based on the ones provided by
tmarc.xsland augmented with additional fields in a few areas. The full list of fields can be found in the Readme of the pazpar2 TYPO3 Extension. - jQuery ≥ 1.7.1 included in your site
- flot with its selection module included in your site if you set the
useHistogramForYearFacetsoption to true; the script is included in the repository as a submodule atflot, a minified version of both is injquery.flot+selection.js - jQuery Storage API included in your site if you want to use the clipboard or search history features; the script is included in the repository as a submodule at
jquery-storage - for the optional usage of ZDB journal availability information (mainly useful in Germany), you are expected to proxy ZDB’s Journals Online & Print service to the /zdb/ and /zdb-local/ paths of your server [example apache configuration].
- your web page to initialise pz-client on domReady with your settings; e.g. using
jQuery.ready(function () { pz2_client.init(yourSettings) })
A number of parameters can be configured in the yourSettings object passed to pz2_client.init(). Essential service specific ones are:
- when querying pazpar2 directly:
serviceID(string): the pazpar2 service to usepazpar2Path(string, default: `/pazpar2/search.pz2): the path of the pazpar2 service on the web server
- when querying pazpar2 through Service Proxy:
useServiceProxy(boolean, default:false): whether or not to use Service Proxy instead of pazpar2 sessionsserviceProxyPath(string, default:/service-proxy): the path of Service Proxy on the web serverserviceProxyAuthPath(string, default:/service-proxy-auth): the path of Service Proxy’s authentication URL on the server
The following options are available to adjust the details of pz2-client’s operation and display:
maxAuthors(integer, default:3): the maximum number of authord to be displayed for the result in the result list (the remaining authors will be added to the detail view).
termLists(object, default:{xtargets: {maxFetch: 25, minDisplay: 1}, medium: {maxFetch: 12, minDisplay: 1}, language: {maxFetch: 5, minDisplay: 1}, filterDate: {maxFetch: 10, minDisplay: 5}}): facet configuration;maxFetchis the maximum number of facet items displayed by default (the rest is hidden),minDisplayis the minimum number of facet items required for the facet to be displayed at allusePazpar2Facets(boolean, default:false): whether to use pazpar2’s native facets; native facets work better with large result sets, our own facets give better in-browser performance otherwise; you probably need to replace thefilterDatetermList setting with one fordatewhen using native facetsuseHistogramForYearFacets(boolean, default:true): if true, year facets are displayed as a histogram rather than as a list
useKeywords: (boolean, default:false): whether to use subject information; iftruethe subject field will be expected in the search form and asubjectindex configuration in pazpar2; Subject names will be displayed in detail view as links that trigger subject searchesuseGoogleBooks(boolean, default:false): whether to use Google Books cover art and preview for items with ISBN or OCLC number; if set to true, you also need to include Google loaderuseMaps(boolean, default:false): whether to use Google Maps to display a map with a highlight for the region covered by the item; if set to true, you also need to include Google loaderuseZDB(boolean, default:false): whether to look up journal availability at the user’s IP (in German university networks) using ZDB’s Journals Online and Print serviceZDBUseClientIP(boolean, default:true): if true, the ZDB-JOP proxy is expected to be at/zdb/, if false, the ZDB-JOP proxy is expected to be at/zdb-local/
exportFormats(array of strings, default:[]): format names for export links, allowed values areris,bibtex,ris-inlineandbibtex-inline.siteName(string, default:undefined): name of the site that can be used for export file namesprovideCOinSExport(boolean, default:true): if true, COinS tags are embedded with the results (for Zotero 3 and above)showKVKLink(boolean, default:false): if true, a link to Karlsruher Virtueller Katalog for searching German union catalogues is included with the export linksshowOpenURLLink(boolean, default:false): if true, a link to an OpenURL resolver is included with the export links; you can set its baseURL using theopenURLBaseURLkey of theexportlocalisation dictionary
autocompleteURLs(object, default:{}): keys are search field names (e.g. all, title, person), values are URLs that can be queried for autocomplete termsautocompleteSetupFunction(function, default:undefined): function (URL, fieldName) that is run when setting up the autocomplete feature. Returns an object for configuring jQuery UI’s autocomplete widget. Functionspz2client.autocompleteSetupArrayfor sources that return JSON arrays,pz2client.autocompleteSolrSpellcheckfor querying a Solr spellcheck component andpz2client.autocompleteSetupHistoryfor using recent search terms (see the next section) are predefined.
historyItems(integer, default:99): Number of recent search queries to store when local storage is available; set to0to deactivateaddHistoryLink(boolean, default:false): whether to add a link for showing the recent search terms insidediv.pz2-featureLinksat the beginning of.pazpar2(alternatively you can usepz2client.autocompleteSetupHistoryasautocompleteSetupFunctionto expose recent search terms via autocompletion)
useClipboard(boolean, default:false): whether to offer storing results in the clipboard when local storage is availableaddClipboardLink(boolean, default:false): whether to add a link for showing the clipboard insidediv.pz2-featureLinksat the beginning of.pazpar2
highlightSearchTerms(boolean, default:false): whether to try and highlight the search terms found in the results’ fields
For localisation to work, pz2-client expects the language to be set in the document’s <html> tag.
Localisation is stored in the pz2client.localisations object. Its keys are dictionary names with objects as values. These objects have ISO 639-1 language codes as keys and objects as values. These final objects have the localisation strings as keys and the localised versions as values.
To overwrite localisation values, prepare your own localisation object and use jQuery.extend() after the document is ready. E.g.:
jQuery().ready( function () {
'facet-xtargets': {
'en': {
'sru.gbv.de/fachopac-vifanord': 'Special Subject Catalogue vifanord',
'swb/wao-vifanord': 'World Affairs Online',
'se-kb/libris-vifanord': 'NB Sweden LIBRIS'
},
'de': {
'sru.gbv.de/fachopac-vifanord': 'Fachkatalog vifanord',
'swb/wao-vifanord': 'World Affairs Online',
'se-kb/libris-vifanord': 'NB Schweden LIBRIS',
'no-bibsys/NBO': 'NB Norwegen BIBSYS'
}
}
});
Things you may want to commonly override:
- facet names in the
facetdictionary - target names in the
facet-xtargetsdictionary; keys in that dictionary are thetargetattributes from the pazpar2 configurations; it may be beneficial to make these independent from the target’s URL usingpz:url
The configuration of the vifanord site can be used as an example:
<html lang="de">
<head>
<title>vifanord</title>
<script src="uploads/tx_t3jquery/jquery-1.8.x-1.10.x.js" type="text/javascript"/>
<script src="typo3conf/ext/pazpar2/Resources/Public/pz2-client/pz2-client.min.js" type="text/javascript"/>
<script src="typo3conf/ext/pazpar2/Resources/Public/pz2-client/jquery-storage/jquery.storageapi.min.js" type="text/javascript"/>
<script src="https://www.google.com/jsapi" type="text/javascript"/>
<script src="typo3conf/ext/pazpar2/Resources/Public/pz2-client/jquery.flot+selection.js" type="text/javascript"/>
<script type="text/javascript">/*<![CDATA[*/
<!--
jQuery(document).ready(function() {pz2client.init(
{
"serviceID": "vifanord",
"pazpar2Path": "/pazpar2/search.pz2",
"useGoogleBooks": true,
"useMaps": true,
"useZDB": true,
"ZDBUseClientIP": true,
"usePazpar2Facets": true,
"useHistogramForYearFacets": true,
"provideCOinSExport": true,
"showExportLinksForEachLocation": false,
"showKVKLink": true,
"showOpenURLLink": true,
"useKeywords": true,
"historyItems": 99,
"addHistoryLink": true,
"useClipboard": true,
"addClipboardLink": true,
"highlightSearchTerms": true,
"exportFormats": [
"ris",
"bibtex"
],
"termLists": {
"region": {
"maxFetch": "5",
"minDisplay": "1"
},
"xtargets": {
"maxFetch": "6",
"minDisplay": "1"
},
"medium": {
"maxFetch": "20",
"minDisplay": "1"
},
"language": {
"maxFetch": "5",
"minDisplay": "1"
},
"date": {
"maxFetch": "6",
"minDisplay": "5"
}
}
}
);
// -->
/*]]>*/</script>
<link rel="stylesheet" type="text/css" href="typo3conf/ext/pazpar2/Resources/Public/pz2-client/pz2.css" media="all"/>
</head>
The script expects specific DOM Elements containing its search form and serving as a container for search results. These should have the following structure:
<div class="pazpar2">
<div class="pz2-JSNote">No JavaScript Notice</div>
<div class="pz2-accessNote"></div>
<form method="get" class="pz2-searchForm pz2-basic">
<div class="pz2-mainForm">
<div class="pz2-fieldContainer pz2-field-all">
<label class="pz2-textFieldLabel" for="pz2-field-all">Alle Felder</label>
<input placeholder="" class="pz2-searchField" id="pz2-field-all" type="text" value="">
<span class="pz2-formControls">
<input class="pz2-submitButton" type="submit" name="submit" value="Search">
<a class="pz2-extendedLink" href="#">extended Search</a>
</span>
<span class="pz2-checkbox pz2-fulltext">
<input id="pz2-checkbox-fulltext" type="checkbox" name="querySwitchFulltext" value="1">
<label for="pz2-checkbox-fulltext">include tables of contents</label>
</span>
</div>
<div class="pz2-extraFields">
<div class="pz2-fieldContainer pz2-field-title">
<label class="pz2-textFieldLabel" for="pz2-field-title">Title</label>
<input class="pz2-searchField" id="pz2-field-title" type="text" name="queryStringTitle" value="1">
<span class="pz2-checkbox pz2-journal-only">
<input id="pz2-checkbox-journal" type="checkbox" name="querySwitchJournalOnly" value="1">
<label for="pz2-checkbox-journal">journal titles only</label>
</span>
</div>
<div class="pz2-fieldContainer pz2-field-person">
<label class="pz2-textFieldLabel" for="pz2-field-person">Person, Author</label>
<input placeholder="e.g. Lincoln or Wilde, Oscar" class="pz2-searchField" id="pz2-field-person" type="text" name="queryStringPerson" value="">
</div>
<div class="pz2-fieldContainer pz2-field-date">
<label class="pz2-textFieldLabel" for="pz2-field-date">Year</label>
<input placeholder="e.g. 2004, 2004-, -2004 oder 2004-2008" class="pz2-searchField" id="pz2-field-date" type="text" name="queryStringDate" value="">
</div>
</div>
</div>
<div class="pz2-ranking">
<select class="pz2-perPage" name="perpage" onchange="onSelectDidChange">
<option value="10">10</option>
<option value="20">20</option>
<option value="50">50</option>
<option value="100" selected="selected">100</option>
</select>
</div>
<input type="hidden" name="useJS" value="no">
</form>
<div class="pz2-clear"></div>
<div class="pz2-recordView">
<div class="pz2-pager pz2-top">
<div class="pz2-progressIndicator"></div>
<div class="pz2-pageNumbers"></div>
<span class="pz2-recordCount" onclick="toggleStatus();"></span>
<div class="pz2-targetView" style="display: none">No information available yet.</div>
</div>
<div class="pz2-termLists"></div>
<div class="pz2-results"></div>
<div class="pz2-pager pz2-bottom">
<div class="pz2-pageNumbers"></div>
</div>
</div>
</div>
The markup consists of the following blocks inside the div.pazpar2:
.pz2-JSNote: contains a note that is hidden by JavaScript on DOM Ready (giving a chance to inform users about JavaScript not being available).pz2-accessNote: information about the access privilegs as supplied by the pazpar2-access script is displayed hereform.pz2-searchForm: The search form:- pz2.css hides the »extended« fields initially and the script will handle expanding/collapsing of the form
.pz2-ranking: Hidden by default, in principle the number of records could be controlled here
.pz2-recordView: The dynamic results appear in here:.pz2-pager.pz2-top: Status information.pz2-progressIndicator: An element that expands from nearly zero width to full width to reflect the process of the pazpar2 search.pz2-pageNumbers: Links for paging appear in here`.pz2-recordCount: The number of results with a hint of status information appear in here.pz2-targetView: Extended status infomration that is revealed/hidden by clicking.pz2-recordCount
.pz2-termLists: Facets will appear in here.pz2-results: The result list will appear in here.pz2-pager.pz2-bottom: The pager is repeated at the bottom of the page.pz2-pageNumbers
- Index Data’s
pz2.jsscript from the pazpar2 repository is included in pz2-client with tiny modifications. - The [https://github.com/subugoe/sub-iconfont](media type icon font) and button graphics that included with the scripts were created by Henrik Cederblad.