doc/ajaxdev.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <section id="ajaxdev">
   3  <title>Ajax client development</title>
   4  <para>
   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.
  15  </para>
  16  <para>
  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.
  23  </para>
  24  <para>
  25   The library supports most major browsers including Firefox 1.5+, IE
  26   6+, Safari 2+, Opera 9+ and Konqueror.
  27  </para>
  28  <para>
  29   The library can work in two modes: a session-aware mode and a
  30   session-less mode.
  31  </para>
  32  <para>
  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.
  36  </para>
  37  <para>
  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
  43   pazpar2 sessions).
  44  </para>
  45  <para><bridgehead>Using <filename>pz2.js</filename></bridgehead></para>
  46  <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>.
  51  </para>
  52  <para>
  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.
  59  </para>
  60  <para><bridgehead>Command callbacks</bridgehead></para>
  61  <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.
  68  </para>
  69  <screen>
  70   my_paz = new pz2 (
  71   {
  72    "pazpar2path": "/pazpar2/search.pz2",
  73    "usesessions" : true,
  74
  75    // assigning command handler, turns on automatic polling
  76    "onshow": my_onshow,
  77    // polling period for each command can be specified
  78    "showtime": 500,
  79
  80    "onterm": my_onterm,
  81    // facet terms are specified as a comma separated list
  82    "termlist": "subject,author",
  83
  84    "onrecord": my_onrecord
  85   }
  86   );
  87  </screen>
  88  <para>
  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.
  94  </para>
  95  <screen>
  96   function my_onstat(data) {
  97    var stat = document.getElementById("stat");
  98    stat.innerHTML = '&lt;span&gt;Active clients: '+ data.activeclients
  99     + '/' + data.clients + ' | &lt;/span&gt;'
 100     + '&lt;span&gt;Retrieved records: ' + data.records
 101     + '/' + data.hits + '&lt;/span&gt;';
 102   }
 103
 104   function my_onshow(data) {
 105    // data contains parsed show response
 106    for (var i = 0; i &lt; data.hits[0].length; i++)
 107     // update page with the hits
 108   }
 109
 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);
 114   }
 115  </screen>
 116  <para><bridgehead><filename>pz2.js</filename> on runtime</bridgehead></para>
 117  <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
 121   called accordingly.
 122  </para>
 123  <screen>
 124   my_paz.search (query, recPergPage, 'relevance');
 125  </screen>
 126  <para>
 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.
 132  </para>
 133  <screen>
 134   my_paz.show (1, 10, 'relevance');
 135  </screen>
 136  <para>
 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.
 141  </para>
 142  <screen>
 143   my_paz.record (recId, 2, 'opac', { “callback”: temp_callback, “args”, caller_args});
 144  </screen>
 145  <variablelist>
 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>
 149   </varlistentry>
 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>
 152   </varlistentry>
 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>
 155   </varlistentry>
 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>
 158
 159   <varlistentry><term>errorhandler</term>
 160   <listitem><para>callback function called on any, pazpar2 or <filename>pz2.js</filename>' internal, error</para></listitem></varlistentry>
 161
 162   <varlistentry><term>oninit</term>
 163   <listitem><para>specifies init response callback function</para></listitem></varlistentry>
 164
 165   <varlistentry><term>onstat</term>
 166   <listitem><para>specifies stat response callback function</para></listitem></varlistentry>
 167
 168   <varlistentry><term>onshow</term>
 169   <listitem><para>specifies show response callback function</para></listitem></varlistentry>
 170
 171   <varlistentry><term>onterm</term>
 172   <listitem><para>specifies termlist response callback function</para></listitem></varlistentry>
 173
 174   <varlistentry><term>onrecord</term>
 175   <listitem><para>specifies record response callback function</para></listitem></varlistentry>
 176
 177   <varlistentry><term>onbytarget</term>
 178   <listitem><para>specifies bytarget response callback function</para></listitem></varlistentry>
 179
 180   <varlistentry><term>onreset</term>
 181   <listitem><para>specifies reset method callback function</para></listitem></varlistentry>
 182
 183   <varlistentry><term>termlist</term>
 184   <listitem><para>comma separated list of facets</para></listitem></varlistentry>
 185
 186   <varlistentry><term>keepAlive</term>
 187   <listitem><para>ping period, should not be lower than 5000 usec</para></listitem></varlistentry>
 188
 189   <varlistentry><term>stattime</term>
 190   <listitem><para>default 1000 usec</para></listitem></varlistentry>
 191
 192   <varlistentry><term>termtime</term></varlistentry>
 193
 194   <varlistentry><term>showtime</term></varlistentry>
 195
 196   <varlistentry><term>bytargettime</term></varlistentry>
 197
 198  </variablelist>
 199
 200  <variablelist>
 201
 202   <para><bridgehead>METHODS</bridgehead></para>
 203
 204   <varlistentry><term>stop ()</term>
 205   <listitem><para>stop activity by clearing timeouts</para></listitem></varlistentry>
 206
 207   <varlistentry><term>reset ()</term>
 208   <listitem><para>reset state</para></listitem></varlistentry>
 209
 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>
 212
 213   <varlistentry><term>ping ()</term>
 214   <listitem><para>session-mode, intitialize pinging </para></listitem></varlistentry>
 215
 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>
 218
 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>
 221
 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>
 224
 225   <varlistentry><term>termlist ()</term>
 226   <listitem><para>start polling for termlists</para></listitem></varlistentry>
 227
 228   <varlistentry><term>bytarget ()</term>
 229   <listitem><para>start polling for target status</para></listitem></varlistentry>
 230
 231   <varlistentry><term>stat ()</term>
 232   <listitem><para>start polling for pazpar2 status</para></listitem></varlistentry>
 233
 234  </variablelist>
 235
 236  <para/>
 237  <para><filename>pz2.js</filename> comes with a set of cross-browser helper classes and functions.</para>
 238
 239  <variablelist>
 240
 241   <para><bridgehead>Ajax helper class</bridgehead></para>
 242
 243   <varlistentry><term>pzHttpRequest</term>
 244   <listitem><para>a cross-browser Ajax wrapper class</para></listitem></varlistentry>
 245
 246   <varlistentry><term>constructor (url, errorHandler)</term>
 247   <listitem><para>create new request for a given url</para></listitem></varlistentry>
 248
 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>
 251
 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>
 254
 255   <varlistentry><term>load ()</term>
 256   <listitem><para>synchronous, returns the response for the given request</para></listitem></varlistentry>
 257
 258  </variablelist>
 259
 260  <variablelist>
 261
 262   <para><bridgehead>XML helper functions</bridgehead></para>
 263
 264   <varlistentry><term>document.newXmlDoc (root)</term>
 265   <listitem><para>create new XML document with root node as specified in parameter</para></listitem></varlistentry>
 266
 267   <varlistentry><term>document.parseXmlFromString (xmlString)</term>
 268   <listitem><para>create new XML document from string</para></listitem></varlistentry>
 269
 270   <varlistentry><term>document.transformToDoc (xmlDoc, xslDoc)</term>
 271   <listitem><para>returns new XML document as a result</para></listitem></varlistentry>
 272
 273   <varlistentry><term>Element_removeFromDoc (DOM_Element)</term>
 274   <listitem><para>remove element from the document</para></listitem></varlistentry>
 275
 276   <varlistentry><term>Element_emptyChildren (DOM_Element)</term></varlistentry>
 277
 278   <varlistentry><term>Element_appendTransformResult (DOM_Element, xmlDoc, xslDoc)</term>
 279   <listitem><para>append xsl transformation result to a DOM element</para></listitem></varlistentry>
 280
 281   <varlistentry><term>Element_appendTextNode (DOM_Element, tagName, textContent)</term>
 282   <listitem><para>append new text node to the element</para></listitem></varlistentry>
 283
 284   <varlistentry><term>Element_setTextContent (DOM_Element, textContent)</term>
 285   <listitem><para>set text content of the element</para></listitem></varlistentry>
 286
 287   <varlistentry><term>Element_getTextContent (DOM_Element)</term>
 288   <listitem><para>get text content of the element</para></listitem></varlistentry>
 289
 290   <varlistentry><term>Element_parseChildNodes (DOM_Element)</term>
 291   <listitem><para>parse all descendants into an associative array</para></listitem></varlistentry>
 292
 293  </variablelist>
 294
 295 </section>
 296
 297 <!-- Keep this comment at the end of the file
 298 Local variables:
 299 mode: nxml
 300 nxml-child-indent: 1
 301 End:
 302 -->