1 <?xml version="1.0" encoding="UTF-8"?>
3 <title>Ajax client development</title>
5 Pazpar2 offers programmer a simple Web Service protocol that can be
6 used (queried in a request/response fashion) from any, server- or
7 client-side, programming language with an XML support. However, when
8 programming a Web-based client to Pazpar2, to achieve certain level of
9 interactivity and instant notification of latest changes in the result
10 set, Ajax (Asynchronous JavaScript and XML) technology may be used. An
11 Ajax client allows user to browse the results before the lengthy
12 process of information retrieval from the back-end targets is
13 finished. Blocking and waiting for usually slow back-end targets is
14 one of the biggest functionality issues in a federated search engine.
17 Pazpar2 comes with a small JavaScript library called
18 <filename>pz2.js</filename>.
19 This library is designed to simplify development of an Ajax-based pazpar2
20 client and alleviate programmer from the low-level details like
21 polling the web service, fetching and parsing returned XML output or
22 managing timers, sessions and basic state variables.
25 The library supports most major browsers including Firefox 1.5+, IE
26 6+, Safari 2+, Opera 9+ and Konqueror.
29 The library can work in two modes: a session-aware mode and a
33 In the session-aware mode, the library assumes that the pazpar2
34 daemon is contacted directly (preferably via Apache proxy to avoid
35 security breaches) and tracks the session Ids internally.
38 In the session-less mode the library assumes that the client is
39 identified on the server and the session Ids are not managed
40 directly. This way of operation requires more sophisticated pazpar2
41 proxy (preferably a wrapper written in a server-side scripting
42 language like PHP that can identify clients and relate them to open
45 <para><bridgehead>Using <filename>pz2.js</filename></bridgehead></para>
47 Client development with the <filename>pz2.js</filename> is strongly event based and the
48 style should be familiar to most JavaScript developers. A simple
49 client (jsdemo) is distributed with pazpar2's source code and shows
50 how to set-up and use <filename>pz2.js</filename>.
53 In short, programmer starts by instantiating the pz2 object and
54 passing an array of parameters to the constructor. The parameter array
55 specifies callbacks used for handling responses to the pazpar2
56 commands. Additionally, the parameter array is used to configure
57 run-time parameters of the <filename>pz2.js</filename> like polling
58 timer time-outs, session-mode and XSLT style-sheets.
60 <para><bridgehead>Command callbacks</bridgehead></para>
62 Callback naming is simple and follows “on” prefix plus command name
63 scheme (like onsearch, onshow, onrecord, ... etc.). When programmer
64 calls a function like show or record on the pz2 object, <filename>pz2.js</filename> will
65 keep on polling pazpar2 (until the backend targets are idle) and with
66 each command's response an assigned callback will be called. In case
67 of pazpar2's internal error an error callback is called.
72 "pazpar2path": "/pazpar2/search.pz2",
75 // assigning command handler, turns on automatic polling
77 // polling period for each command can be specified
81 // facet terms are specified as a comma separated list
82 "termlist": "subject,author",
84 "onrecord": my_onrecord
89 Each command callback is a user defined function that takes a hash
90 object as a parameter. The hash object contains parsed pazpar2
91 responses (hash members that correspond to the elements in the
92 response XML document). Within the handler programmer further
93 processes the data and updates the viewed document.
96 function my_onstat(data) {
97 var stat = document.getElementById("stat");
98 stat.innerHTML = '<span>Active clients: '+ data.activeclients
99 + '/' + data.clients + ' | </span>'
100 + '<span>Retrieved records: ' + data.records
101 + '/' + data.hits + '</span>';
104 function my_onshow(data) {
105 // data contains parsed show response
106 for (var i = 0; i < data.hits[0].length; i++)
107 // update page with the hits
110 function on_record(data) {
111 // if detailsstylesheet parameter was set data array
112 // will contain raw xml and xsl data
113 Element_appendTransformResult(someDiv, data.xmlDoc, data.xslDoc);
116 <para><bridgehead><filename>pz2.js</filename> on runtime</bridgehead></para>
118 The search process is initiated by calling the search method on the
119 instantiated pz2 object. To initiate short status reports and
120 per-target status information methods stat and bytarget have to be
124 my_paz.search (query, recPergPage, 'relevance');
127 Managing the results (keeping track of the browsed results page and
128 sorting) is up to the client's programmer. At any point the show
129 method may be called to bring up the latest result set with a
130 different sorting criteria or range and without re-executing the
131 search on the back-end.
134 my_paz.show (1, 10, 'relevance');
137 To retrieve a detailed record the record command is called. When
138 calling record command one may temporarily override its default
139 callback by specifying the handler parameter. This might be useful
140 when retrieving raw records that need to be processed differently.
143 my_paz.record (recId, 2, 'opac', { “callback”: temp_callback, “args”, caller_args});
146 <para><bridgehead>PARAMETERS ARRAY</bridgehead></para>
147 <varlistentry><term>pazpar2path</term>
148 <listitem><para>server path to pazpar2 (relative to the portal), when pazpar2 is installed as a package this does not have to be set </para></listitem>
150 <varlistentry><term>usesessions</term>
151 <listitem><para>boolean, when set to true <filename>pz2.js</filename> will manage sessions internally otherwise it's left to the server-side script, default true</para></listitem>
153 <varlistentry><term>autoInit</term>
154 <listitem><para>bolean, sets auto initialization of pazpar2 session on the object instantiation, default true, valid only if usesession is set to true</para></listitem>
156 <varlistentry><term>detailstylesheet</term>
157 <listitem><para>path to the xsl presentation stylesheet (relative to the portal) used for the detailed record display</para></listitem></varlistentry>
159 <varlistentry><term>errorhandler</term>
160 <listitem><para>callback function called on any, pazpar2 or <filename>pz2.js</filename>' internal, error</para></listitem></varlistentry>
162 <varlistentry><term>oninit</term>
163 <listitem><para>specifies init response callback function</para></listitem></varlistentry>
165 <varlistentry><term>onstat</term>
166 <listitem><para>specifies stat response callback function</para></listitem></varlistentry>
168 <varlistentry><term>onshow</term>
169 <listitem><para>specifies show response callback function</para></listitem></varlistentry>
171 <varlistentry><term>onterm</term>
172 <listitem><para>specifies termlist response callback function</para></listitem></varlistentry>
174 <varlistentry><term>onrecord</term>
175 <listitem><para>specifies record response callback function</para></listitem></varlistentry>
177 <varlistentry><term>onbytarget</term>
178 <listitem><para>specifies bytarget response callback function</para></listitem></varlistentry>
180 <varlistentry><term>onreset</term>
181 <listitem><para>specifies reset method callback function</para></listitem></varlistentry>
183 <varlistentry><term>termlist</term>
184 <listitem><para>comma separated list of facets</para></listitem></varlistentry>
186 <varlistentry><term>keepAlive</term>
187 <listitem><para>ping period, should not be lower than 5000 usec</para></listitem></varlistentry>
189 <varlistentry><term>stattime</term>
190 <listitem><para>default 1000 usec</para></listitem></varlistentry>
192 <varlistentry><term>termtime</term></varlistentry>
194 <varlistentry><term>showtime</term></varlistentry>
196 <varlistentry><term>bytargettime</term></varlistentry>
202 <para><bridgehead>METHODS</bridgehead></para>
204 <varlistentry><term>stop ()</term>
205 <listitem><para>stop activity by clearing timeouts</para></listitem></varlistentry>
207 <varlistentry><term>reset ()</term>
208 <listitem><para>reset state</para></listitem></varlistentry>
210 <varlistentry><term>init (sessionId, serviceId)</term>
211 <listitem><para>session-mode, initialize new session or pick up a session already initialized</para></listitem></varlistentry>
213 <varlistentry><term>ping ()</term>
214 <listitem><para>session-mode, intitialize pinging </para></listitem></varlistentry>
216 <varlistentry><term>search (query, num, sort, filter, showfrom)</term>
217 <listitem><para>execute piggy-back search and activate polling on every command specified by assigning command callback (in the pz2 constructor)</para></listitem></varlistentry>
219 <varlistentry><term>show (start, num, sort)</term>
220 <listitem><para>start or change parameters of polling for a given window of records</para></listitem></varlistentry>
222 <varlistentry><term>record (id, offset, syntax, handler)</term>
223 <listitem><para>retrieve detailed or raw record. handler temporarily overrides default callback function.</para></listitem></varlistentry>
225 <varlistentry><term>termlist ()</term>
226 <listitem><para>start polling for termlists</para></listitem></varlistentry>
228 <varlistentry><term>bytarget ()</term>
229 <listitem><para>start polling for target status</para></listitem></varlistentry>
231 <varlistentry><term>stat ()</term>
232 <listitem><para>start polling for pazpar2 status</para></listitem></varlistentry>
237 <para><filename>pz2.js</filename> comes with a set of cross-browser helper classes and functions.</para>
241 <para><bridgehead>Ajax helper class</bridgehead></para>
243 <varlistentry><term>pzHttpRequest</term>
244 <listitem><para>a cross-browser Ajax wrapper class</para></listitem></varlistentry>
246 <varlistentry><term>constructor (url, errorHandler)</term>
247 <listitem><para>create new request for a given url</para></listitem></varlistentry>
249 <varlistentry><term>get (params, callback)</term>
250 <listitem><para>asynchronous, send the request with given parameters (array) and call callback with response as parameter</para></listitem></varlistentry>
252 <varlistentry><term>post (params, data, callback)</term>
253 <listitem><para>asychronous, post arbitrary data (may be XML doc) and call callback with response as parameter</para></listitem></varlistentry>
255 <varlistentry><term>load ()</term>
256 <listitem><para>synchronous, returns the response for the given request</para></listitem></varlistentry>
262 <para><bridgehead>XML helper functions</bridgehead></para>
264 <varlistentry><term>document.newXmlDoc (root)</term>
265 <listitem><para>create new XML document with root node as specified in parameter</para></listitem></varlistentry>
267 <varlistentry><term>document.parseXmlFromString (xmlString)</term>
268 <listitem><para>create new XML document from string</para></listitem></varlistentry>
270 <varlistentry><term>document.transformToDoc (xmlDoc, xslDoc)</term>
271 <listitem><para>returns new XML document as a result</para></listitem></varlistentry>
273 <varlistentry><term>Element_removeFromDoc (DOM_Element)</term>
274 <listitem><para>remove element from the document</para></listitem></varlistentry>
276 <varlistentry><term>Element_emptyChildren (DOM_Element)</term></varlistentry>
278 <varlistentry><term>Element_appendTransformResult (DOM_Element, xmlDoc, xslDoc)</term>
279 <listitem><para>append xsl transformation result to a DOM element</para></listitem></varlistentry>
281 <varlistentry><term>Element_appendTextNode (DOM_Element, tagName, textContent)</term>
282 <listitem><para>append new text node to the element</para></listitem></varlistentry>
284 <varlistentry><term>Element_setTextContent (DOM_Element, textContent)</term>
285 <listitem><para>set text content of the element</para></listitem></varlistentry>
287 <varlistentry><term>Element_getTextContent (DOM_Element)</term>
288 <listitem><para>get text content of the element</para></listitem></varlistentry>
290 <varlistentry><term>Element_parseChildNodes (DOM_Element)</term>
291 <listitem><para>parse all descendants into an associative array</para></listitem></varlistentry>
297 <!-- Keep this comment at the end of the file