4. Ajax client development

Pazpar2 offers programmers a simple Web Service protocol that can be used (queried in a request/response fashion) from any, server- or client-side, programming language with an XML support. However, when programming a Web-based client to Pazpar2, to achieve certain level of interactivity and instant notification of latest changes in the result set, Ajax (Asynchronous JavaScript and XML) technology may be used. An Ajax client allows user to browse the results before the lengthy process of information retrieval from the back-end targets is finished. Blocking and waiting for usually slow back-end targets is one of the biggest functionality issues in a federated search engine.

Pazpar2 comes with a small JavaScript library called pz2.js. This library is designed to simplify development of an Ajax-based pazpar2 client and alleviate the programmer from the low-level details like polling the web service, fetching and parsing returned XML output or managing timers, sessions and basic state variables.

The library supports most major browsers including Firefox 1.5+, IE 6+, Safari 2+, Opera 9+ and Konqueror.

The library can work in two modes: a session-aware mode and a session-less mode.

In the session-aware mode, the library assumes that the pazpar2 daemon is contacted directly (preferably via Apache proxy to avoid security breaches) and tracks the session IDs internally.

In the session-less, mode the library assumes that the client is identified on the server and the session IDs are not managed directly. This way of operation requires a more sophisticated pazpar2 proxy (preferably a wrapper written in a server-side scripting language like PHP that can identify clients and relate them to open pazpar2 sessions).

Using pz2.js

Client development with the pz2.js is strongly event based and the style should be familiar to most JavaScript developers. A simple client (jsdemo) is distributed with Pazpar2's source code and shows how to set-up and use pz2.js.

In short, the programmer starts by instantiating the pz2 object and passing an array of parameters to the constructor. The parameter array specifies callbacks used for handling responses to the pazpar2 commands. Additionally, the parameter array is used to configure run-time parameters of the pz2.js like polling timer time-outs, session-mode and XSLT stylesheets.

Command callbacks

Callback naming is simple, and follows “on” prefix plus command name scheme (like onsearch, onshow, onrecord, ... etc.). When the programmer calls a function like show or record on the pz2 object, pz2.js will keep on polling pazpar2 (until the backend targets are idle) and with each command's response an assigned callback will be called. In case of Pazpar2's internal error, an error callback is called.

  my_paz = new pz2 (
  {
   "pazpar2path": "/pazpar2/search.pz2",
   "usesessions" : true,

   // assigning command handler, turns on automatic polling
   "onshow": my_onshow,
   // polling period for each command can be specified
   "showtime": 500,

   "onterm": my_onterm,
   // facet terms are specified as a comma separated list
   "termlist": "subject,author",

   "onrecord": my_onrecord
  }
  );
 

Each command callback is a user-defined function that takes a hash object as a parameter. The hash object contains parsed pazpar2 responses (hash members that correspond to the elements in the response XML document). Within the handler, the programmer further processes the data and updates the viewed document.

  function my_onstat(data) {
   var stat = document.getElementById("stat");
   stat.innerHTML = '<span>Active clients: '+ data.activeclients
    + '/' + data.clients + ' | </span>'
    + '<span>Retrieved records: ' + data.records
    + '/' + data.hits + '</span>';
  }

  function my_onshow(data) {
   // data contains parsed show response
   for (var i = 0; i < data.hits[0].length; i++)
    // update page with the hits
  }

  function on_record(data) {
   // if detailsstylesheet parameter was set data array
   // will contain raw xml and xsl data
   Element_appendTransformResult(someDiv, data.xmlDoc, data.xslDoc);
  }
 

pz2.js on runtime

The search process is initiated by calling the search method on the instantiated pz2 object. To initiate short status reports and per-target status information, methods stat and bytarget are called accordingly.

  my_paz.search (query, recPergPage, 'relevance');
 

Managing the results (keeping track of the browsed results page and sorting) is up to the client's programmer. At any point the show method may be called to bring up the latest result set with a different sorting criteria or range, without re-executing the search on the back-end.

  my_paz.show (1, 10, 'relevance');
 

To retrieve a detailed record, the record command is called. When calling the record command, one may temporarily override its default callback by specifying the handler parameter. This might be useful when retrieving raw records that need to be processed differently.

  my_paz.record (recId, 2, 'opac', { “callback”: temp_callback, “args”, caller_args});
 

PARAMETERS ARRAY

pazpar2path

server path to pazpar2 (relative to the portal). When pazpar2 is installed as a package this does not need to be set.

usesessions

Boolean. When set to true pz2.js will manage sessions internally, otherwise it is left to the server-side script. Default true.

autoInit

Boolean. Sets auto initialization of pazpar2 session on the object instantiation. Default true. Valid only if usesession is set to true.

detailstylesheet

path to the xsl presentation stylesheet (relative to the portal) used for the detailed record display

errorhandler

callback function called on any (pazpar2 or pz2.js) internal error

oninit

specifies init response callback function

onstat

specifies stat response callback function

onshow

specifies show response callback function

onterm

specifies termlist response callback function

onrecord

specifies record response callback function

onbytarget

specifies bytarget response callback function

onreset

specifies reset method callback function

termlist

comma separated list of facets

keepAlive

ping period, should not be lower than 5000 usec

stattime

default 1000 usec

termtime
showtime
bytargettime

METHODS

stop ()

stop activity by clearing timeouts

reset ()

reset state

init (sessionId, serviceId)

session-mode, initialize new session or pick up a session already initialized

ping ()

session-mode, intitialize pinging

search (query, num, sort, filter, showfrom)

execute piggy-back search and activate polling on every command specified by assigning command callback (in the pz2 constructor)

show (start, num, sort)

start or change parameters of polling for a given window of records

record (id, offset, syntax, handler)

retrieve detailed or raw record. handler temporarily overrides default callback function.

termlist ()

start polling for termlists

bytarget ()

start polling for target status

stat ()

start polling for pazpar2 status

pz2.js comes with a set of cross-browser helper classes and functions.

Ajax helper class

pzHttpRequest

a cross-browser Ajax wrapper class

constructor (url, errorHandler)

create new request for a given url

get (params, callback)

asynchronous, send the request with given parameters (array) and call callback with response as parameter

post (params, data, callback)

asynchronous, post arbitrary data (may be XML doc) and call callback with response as parameter

load ()

synchronous, returns the response for the given request

XML helper functions

document.newXmlDoc (root)

create new XML document with root node as specified in parameter

document.parseXmlFromString (xmlString)

create new XML document from string

document.transformToDoc (xmlDoc, xslDoc)

returns new XML document as a result

Element_removeFromDoc (DOM_Element)

remove element from the document

Element_emptyChildren (DOM_Element)
Element_appendTransformResult (DOM_Element, xmlDoc, xslDoc)

append xsl transformation result to a DOM element

Element_appendTextNode (DOM_Element, tagName, textContent)

append new text node to the element

Element_setTextContent (DOM_Element, textContent)

set text content of the element

Element_getTextContent (DOM_Element)

get text content of the element

Element_parseChildNodes (DOM_Element)

parse all descendants into an associative array