doc/ajaxdev.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <section id="ajaxdev">
   3  <title>Ajax client development</title>
   4
   5  <para>
   6   Pazpar2 offers programmer a simple Web Service protocol that can be
   7   used (queried in a request/response fashion) from any, server- or
   8   client-side, programming language with an XML support. However, when
   9   programming a Web-based client to Pazpar2, to achieve certain level of
  10   interactivity and instant notification of latest changes in the result
  11   set, Ajax (Asynchronous JavaScript and XML) technology may be used. An
  12   Ajax client allows user to browse the results before the lengthy
  13   process of information retrieval from the back-end targets is
  14   finished. Blocking and waiting for usually slow back-end targets is
  15   one of the biggest functionality issues in a federated search engine.
  16  </para>
  17
  18  <para><bridgehead>Pz2.js</bridgehead></para>
  19
  20  <para>
  21   Pazpar2 comes with a small JavaScript library called pz2.js. This
  22   library is designed to simplify development of an Ajax-based pazpar2
  23   client and alleviate programmer from the low-level details like
  24   polling the web service, fetching and parsing returned XML output or
  25   managing timers, sessions and basic state variables.
  26  </para>
  27
  28  <para>
  29   The library supports most major browsers including Firefox 1.5+, IE
  30   6+, Safari 2+, Opera 9+ and Konqueror.
  31  </para>
  32
  33  <para>
  34   The library can work in two modes: a session-aware mode and a
  35   session-less mode.
  36  </para>
  37
  38  <para>
  39   In the session-aware mode, the library assumes that the pazpar2
  40   daemon is contacted directly (preferably via Apache proxy to avoid
  41   security breaches) and tracks the session Ids internally.
  42  </para>
  43
  44  <para>
  45   In the session-less mode the library assumes that the client is
  46   identified on the server and the session Ids are not managed
  47   directly. This way of operation requires more sophisticated pazpar2
  48   proxy (preferably a wrapper written in a server-side scripting
  49   language like PHP that can identify clients and relate them to open
  50   pazpar2 sessions).
  51  </para>
  52
  53  <para><bridgehead>Using pz2.js</bridgehead></para>
  54
  55  <para>
  56   Client development with the pz2.js is strongly event based and the
  57   style should be familiar to most JavaScript developers. A simple
  58   client (jsdemo) is distributed with pazpar2's source code and shows
  59   how to set-up and use pz2.js.
  60  </para>
  61
  62  <para>
  63   In short, programmer starts by instantiating the pz2 object and
  64   passing an array of parameters to the constructor. The parameter array
  65   specifies callbacks used for handling responses to the pazpar2
  66   commands. Additionally, the parameter array is used to configure
  67   run-time parameters of the pz2.js like polling timer time-outs,
  68   session-mode and XSLT style-sheets.
  69  </para>
  70
  71  <para><bridgehead>Command callbacks</bridgehead></para>
  72
  73  <para>
  74   Callback naming is simple and follows “on” prefix plus command name
  75   scheme (like onsearch, onshow, onrecord, ... etc.). When programmer
  76   calls a function like show or record on the pz2 object, pz2.js will
  77   keep on polling pazpar2 (until the backend targets are idle) and with
  78   each command's response an assigned callback will be called. In case
  79   of pazpar2's internal error an error callback is called.
  80  </para>
  81
  82  <screen>
  83   my_paz = new pz2 (
  84   {
  85    "pazpar2path": "/pazpar2/search.pz2",
  86    "usesessions" : true,
  87
  88    // assigning command handler, turns on automatic polling
  89    "onshow": my_onshow,
  90    // polling period for each command can be specified
  91    "showtime": 500,
  92
  93    "onterm": my_onterm,
  94    // facet terms are specified as a comma separated list
  95    "termlist": "subject,author",
  96
  97    "onrecord": my_onrecord
  98   }
  99   );
 100  </screen>
 101
 102  <para>
 103   Each command callback is a user defined function that takes a hash
 104   object as a parameter. The hash object contains parsed pazpar2
 105   responses (hash members that correspond to the elements in the
 106   response XML document). Within the handler programmer further
 107   processes the data and updates the viewed document.
 108  </para>
 109
 110  <screen>
 111   function my_onstat(data) {
 112    var stat = document.getElementById("stat");
 113    stat.innerHTML = '&lt;span&gt;Active clients: '+ data.activeclients
 114     + '/' + data.clients + ' | &lt;/span&gt;'
 115     + '&lt;span&gt;Retrieved records: ' + data.records
 116     + '/' + data.hits + '&lt;/span&gt;';
 117   }
 118
 119   function my_onshow(data) {
 120    // data contains parsed show response
 121    for (var i = 0; i &lt; data.hits[0].length; i++)
 122     // update page with the hits
 123   }
 124
 125   function on_record(data) {
 126    // if detailsstylesheet parameter was set data array
 127    // will contain raw xml and xsl data
 128    Element_appendTransformResult(someDiv, data.xmlDoc, data.xslDoc);
 129   }
 130  </screen>
 131
 132  <para><bridgehead>pz2.js on runtime</bridgehead></para>
 133
 134  <para>
 135   The search process is initiated by calling the search method on the
 136   instantiated pz2 object. To initiate short status reports and
 137   per-target status information methods stat and bytarget have to be
 138   called accordingly.
 139  </para>
 140
 141  <screen>
 142   my_paz.search (query, recPergPage, 'relevance');
 143  </screen>
 144
 145  <para>
 146   Managing the results (keeping track of the browsed results page and
 147   sorting) is up to the client's programmer. At any point the show
 148   method may be called to bring up the latest result set with a
 149   different sorting criteria or range and without re-executing the
 150   search on the back-end.
 151  </para>
 152
 153  <screen>
 154   my_paz.show (1, 10, 'relevance');
 155  </screen>
 156
 157  <para>
 158   To retrieve a detailed record the record command is called. When
 159   calling record command one may temporarily override its default
 160   callback by specifying the handler parameter. This might be useful
 161   when retrieving raw records that need to be processed differently.
 162  </para>
 163
 164  <screen>
 165   my_paz.record (recId, 2, 'opac', { “callback”: temp_callback, “args”, caller_args});
 166  </screen>
 167
 168  <variablelist>
 169
 170   <para><bridgehead>PARAMATERS ARRAY</bridgehead></para>
 171
 172   <varlistentry><term>pazpar2path</term>
 173   <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>
 174   </varlistentry>
 175
 176   <varlistentry><term>usesessions</term>
 177   <listitem><para>boolean, when set to true pz2.js will manage sessions internally otherwise it's left to the server-side script, default true</para></listitem>
 178   </varlistentry>
 179
 180   <varlistentry><term>autoInit</term>
 181   <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>
 182   </varlistentry>
 183
 184   <varlistentry><term>detailstylesheet</term>
 185   <listitem><para>path to the xsl presentation stylesheet (relative to the portal) used for the detailed record display</para></listitem></varlistentry>
 186
 187   <varlistentry><term>errorhandler</term>
 188   <listitem><para>callback function called on any, pazpar2 or pz2.js' internal, error</para></listitem></varlistentry>
 189
 190   <varlistentry><term>oninit</term>
 191   <listitem><para>specifies init response callback function</para></listitem></varlistentry>
 192
 193   <varlistentry><term>onstat</term>
 194   <listitem><para>specifies stat response callback function</para></listitem></varlistentry>
 195
 196   <varlistentry><term>onshow</term>
 197   <listitem><para>specifies show response callback function</para></listitem></varlistentry>
 198
 199   <varlistentry><term>onterm</term>
 200   <listitem><para>specifies termlist response callback function</para></listitem></varlistentry>
 201
 202   <varlistentry><term>onrecord</term>
 203   <listitem><para>specifies record response callback function</para></listitem></varlistentry>
 204
 205   <varlistentry><term>onbytarget</term>
 206   <listitem><para>specifies bytarget response callback function</para></listitem></varlistentry>
 207
 208   <varlistentry><term>onreset</term>
 209   <listitem><para>specifies reset method callback function</para></listitem></varlistentry>
 210
 211   <varlistentry><term>termlist</term>
 212   <listitem><para>comma separated list of facets</para></listitem></varlistentry>
 213
 214   <varlistentry><term>keepAlive</term>
 215   <listitem><para>ping period, should not be lower than 5000 usec</para></listitem></varlistentry>
 216
 217   <varlistentry><term>stattime</term>
 218   <listitem><para>default 1000 usec</para></listitem></varlistentry>
 219
 220   <varlistentry><term>termtime</term></varlistentry>
 221
 222   <varlistentry><term>showtime</term></varlistentry>
 223
 224   <varlistentry><term>bytargettime</term></varlistentry>
 225
 226  </variablelist>
 227
 228  <variablelist>
 229
 230   <para><bridgehead>METHODS</bridgehead></para>
 231
 232   <varlistentry><term>stop ()</term>
 233   <listitem><para>stop activity by clearing timeouts</para></listitem></varlistentry>
 234
 235   <varlistentry><term>reset ()</term>
 236   <listitem><para>reset state</para></listitem></varlistentry>
 237
 238   <varlistentry><term>init (sesionId)</term>
 239   <listitem><para>session-mode, initialize new session or pick up a session already initialized</para></listitem></varlistentry>
 240
 241   <varlistentry><term>ping ()</term>
 242   <listitem><para>session-mode, intitialize pinging </para></listitem></varlistentry>
 243
 244   <varlistentry><term>search (query, num, sort, filter, showfrom)</term>
 245   <listitem><para>execute piggy-back search and activate polling on every command specified by assigning command callback (in the pz2 constructor)</para></listitem></varlistentry>
 246
 247   <varlistentry><term>show (start, num, sort)</term>
 248   <listitem><para>start or change parameters of polling for a given window of records</para></listitem></varlistentry>
 249
 250   <varlistentry><term>record (id, offset, syntax, handler)</term>
 251   <listitem><para>retrieve detailed or raw record. handler temporarily overrides default callback function.</para></listitem></varlistentry>
 252
 253   <varlistentry><term>termlist ()</term>
 254   <listitem><para>start polling for termlists</para></listitem></varlistentry>
 255
 256   <varlistentry><term>bytarget ()</term>
 257   <listitem><para>start polling for target status</para></listitem></varlistentry>
 258
 259   <varlistentry><term>stat ()</term>
 260   <listitem><para>start polling for pazpar2 status</para></listitem></varlistentry>
 261
 262  </variablelist>
 263
 264  <para/>
 265  <para>Pz2.js comes with a set of cross-browser helper classes and functions.</para>
 266
 267  <variablelist>
 268
 269   <para><bridgehead>Ajax helper class</bridgehead></para>
 270
 271   <varlistentry><term>pzHttpRequest</term>
 272   <listitem><para>a cross-browser Ajax wrapper class</para></listitem></varlistentry>
 273
 274   <varlistentry><term>constructor (url, errorHandler)</term>
 275   <listitem><para>create new request for a given url</para></listitem></varlistentry>
 276
 277   <varlistentry><term>get (params, callback)</term>
 278   <listitem><para>asynchronous, send the request with given parameters (array) and call callback with response as parameter</para></listitem></varlistentry>
 279
 280   <varlistentry><term>post (params, data, callback)</term>
 281   <listitem><para>asychronous, post arbitrary data (may be XML doc) and call callback with response as parameter</para></listitem></varlistentry>
 282
 283   <varlistentry><term>load ()</term>
 284   <listitem><para>synchronous, returns the response for the given request</para></listitem></varlistentry>
 285
 286  </variablelist>
 287
 288  <variablelist>
 289
 290   <para><bridgehead>XML helper functions</bridgehead></para>
 291
 292   <varlistentry><term>document.newXmlDoc (root)</term>
 293   <listitem><para>create new XML document with root node as specified in parameter</para></listitem></varlistentry>
 294
 295   <varlistentry><term>document.parseXmlFromString (xmlString)</term>
 296   <listitem><para>create new XML document from string</para></listitem></varlistentry>
 297
 298   <varlistentry><term>document.transformToDoc (xmlDoc, xslDoc)</term>
 299   <listitem><para>returns new XML document as a result</para></listitem></varlistentry>
 300
 301   <varlistentry><term>Element_removeFromDoc (DOM_Element)</term>
 302   <listitem><para>remove element from the document</para></listitem></varlistentry>
 303
 304   <varlistentry><term>Element_emptyChildren (DOM_Element)</term></varlistentry>
 305
 306   <varlistentry><term>Element_appendTransformResult (DOM_Element, xmlDoc, xslDoc)</term>
 307   <listitem><para>append xsl transformation result to a DOM element</para></listitem></varlistentry>
 308
 309   <varlistentry><term>Element_appendTextNode (DOM_Element, tagName, textContent)</term>
 310   <listitem><para>append new text node to the element</para></listitem></varlistentry>
 311
 312   <varlistentry><term>Element_setTextContent (DOM_Element, textContent)</term>
 313   <listitem><para>set text content of the element</para></listitem></varlistentry>
 314
 315   <varlistentry><term>Element_getTextContent (DOM_Element)</term>
 316   <listitem><para>get text content of the element</para></listitem></varlistentry>
 317
 318   <varlistentry><term>Element_parseChildNodes (DOM_Element)</term>
 319   <listitem><para>parse all descendants into an associative array</para></listitem></varlistentry>
 320
 321  </variablelist>
 322
 323 </section>
 324
 325 <!-- Keep this comment at the end of the file
 326 Local variables:
 327 mode: nxml
 328 nxml-child-indent: 1
 329 End:
 330 -->