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 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.
   7   </para>
   8
   9   <para><bridgehead>Pz2.js</bridgehead></para>
  10
  11   <para>
  12   Pazapar2 comes with a small JavaScript library called pz2.js. This library is designed to simplify development of an Ajax-based pazpar2 clients and alleviate 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.
  13   </para>
  14
  15   <para>
  16   The library supports most major browsers including Firefox 1.5+, IE 6+, Safari 2+, Opera 9+ and Konqueror.
  17   </para>
  18
  19   <para>
  20   The library can work in two modes: a session-aware mode and a session-less mode.
  21   </para>
  22
  23   <para>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.
  24   </para>
  25
  26   <para>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 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).</para>
  27
  28   <para><bridgehead>Using pz2.js</bridgehead></para>
  29
  30   <para>
  31   Client development with the pz2.js is strongly event based and 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.
  32   </para>
  33
  34   <para>
  35   In short, 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 style-sheets.
  36   </para>
  37
  38   <para><bridgehead>Command callbacks</bridgehead></para>
  39
  40   <para>
  41   Callback naming is simple and follows “on” prefix plus command name scheme (like onsearch, onshow, onrecord, ... etc.). When 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.
  42   </para>
  43
  44   <screen>
  45   my_paz = new pz2 (
  46   {
  47           "pazpar2path": "/pazpar2/search.pz2",
  48           "usesessions" : true,
  49
  50           // assigning command handler, turns on automatic polling
  51           "onshow": my_onshow,
  52           // polling period for each command can be specified
  53           "showtime": 500,
  54
  55           "onterm": my_onterm,
  56           // facet terms are specified as a comma separated list
  57           "termlist": "subject,author",
  58
  59           "onrecord": my_onrecord
  60           }
  61   );
  62   </screen>
  63
  64   <para>
  65   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 programmer further processes the data and updates the the viewed document.
  66   </para>
  67
  68   <screen>
  69     function my_onstat(data) {
  70       var stat = document.getElementById("stat");
  71       stat.innerHTML = '&lt;span&gt;Active clients: '+ data.activeclients
  72           + '/' + data.clients + ' | &lt;/span&gt;'
  73           + '&lt;span&gt;Retrieved records: ' + data.records
  74           + '/' + data.hits + '&lt;/span&gt;';
  75     }
  76
  77     function my_onshow(data) {
  78         // data contains parsed show response
  79         for (var i = 0; i &lt; data.hits[0].length; i++)
  80             // update page with the hits
  81     }
  82
  83     function on_record(data) {
  84         // if detailsstylesheet parameter was set data array will contain raw xml // // and xsl data
  85         Element_appendTransformResult(someDiv, data.xmlDoc, data.xslDoc);
  86     }
  87   </screen>
  88
  89   <para><bridgehead>pz2.js on runtime</bridgehead></para>
  90
  91   <para>
  92   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 have to be called accordingly.
  93   </para>
  94
  95   <screen>
  96     my_paz.search (query, recPergPage, 'relevance');
  97   </screen>
  98
  99   <para>
 100   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 and without re-executing the search on the back-end.
 101   </para>
 102
 103   <screen>
 104     my_paz.show (1, 10, 'relevance');
 105   </screen>
 106
 107   <para>
 108   To retrieve a detailed record the record command is called. When calling 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.
 109   </para>
 110
 111   <screen>
 112     my_paz.record (recId, 2, 'opac', { “callback”: temp_callback, “args”, caller_args});
 113   </screen>
 114
 115   <variablelist>
 116
 117     <para><bridgehead>PARAMATERS ARRAY</bridgehead></para>
 118
 119     <varlistentry><term>pazpar2path</term>
 120     <listitem><para>server path to pazpar2 (relative to the portal), when pazar2 is installed as a package this does not have to be set </para></listitem>
 121     </varlistentry>
 122
 123     <varlistentry><term>usesessions</term>
 124     <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>
 125     </varlistentry>
 126
 127     <varlistentry><term>autoInit</term>
 128     <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>
 129     </varlistentry>
 130
 131     <varlistentry><term>detailstylesheet</term>
 132     <listitem><para>path to the xsl presentation stylesheet (relative to the portal) used for the detailed record display</para></listitem></varlistentry>
 133
 134     <varlistentry><term>errorhandler</term>
 135     <listitem><para>callback function called on any, pazpar2 or pz2.js' internal, error</para></listitem></varlistentry>
 136
 137     <varlistentry><term>oninit</term>
 138     <listitem><para>specifies init response callback function</para></listitem></varlistentry>
 139
 140     <varlistentry><term>onstat</term>
 141     <listitem><para>specifies stat response callback function</para></listitem></varlistentry>
 142
 143     <varlistentry><term>onshow</term>
 144     <listitem><para>specifies show response callback function</para></listitem></varlistentry>
 145
 146     <varlistentry><term>onterm</term>
 147     <listitem><para>specifies termlist response callback function</para></listitem></varlistentry>
 148
 149     <varlistentry><term>onrecord</term>
 150     <listitem><para>specifies record response callback function</para></listitem></varlistentry>
 151
 152     <varlistentry><term>onbytarget</term>
 153     <listitem><para>specifies bytarget response callback function</para></listitem></varlistentry>
 154
 155     <varlistentry><term>onreset</term>
 156     <listitem><para>specifies reset method callback function</para></listitem></varlistentry>
 157
 158     <varlistentry><term>termlist</term>
 159     <listitem><para>coma separated list of facets</para></listitem></varlistentry>
 160
 161     <varlistentry><term>keepAlive</term>
 162     <listitem><para>ping period, should not be lower than 5000 usec</para></listitem></varlistentry>
 163
 164     <varlistentry><term>stattime</term>
 165     <listitem><para>default 1000 usec</para></listitem></varlistentry>
 166
 167     <varlistentry><term>termtime</term></varlistentry>
 168
 169     <varlistentry><term>showtime</term></varlistentry>
 170
 171     <varlistentry><term>bytargettime</term></varlistentry>
 172
 173   </variablelist>
 174
 175   <variablelist>
 176
 177     <para><bridgehead>METHODS</bridgehead></para>
 178
 179     <varlistentry><term>stop ()</term>
 180     <listitem><para>stop activity by clearing timeouts</para></listitem></varlistentry>
 181
 182     <varlistentry><term>reset ()</term>
 183     <listitem><para>reset state</para></listitem></varlistentry>
 184
 185     <varlistentry><term>init (sesionId)</term>
 186     <listitem><para>session-mode, intitialize new session or pick up a session already initialized</para></listitem></varlistentry>
 187
 188     <varlistentry><term>ping ()</term>
 189     <listitem><para>session-mode, intitialize pinging </para></listitem></varlistentry>
 190
 191     <varlistentry><term>search (query, num, sort, filter, showfrom)</term>
 192     <listitem><para>execute piggy-back search and activate polling on every command specfied by assigning command callback (in the pz2 constructor)</para></listitem></varlistentry>
 193
 194     <varlistentry><term>show (start, num, sort)</term>
 195     <listitem><para>start or change parameters of polling for a given window of records</para></listitem></varlistentry>
 196
 197     <varlistentry><term>record (id, offset, syntax, handler)</term>
 198     <listitem><para>retrieve detailed or raw record. handler temporary overrirdes default callback function.</para></listitem></varlistentry>
 199
 200     <varlistentry><term>termlist ()</term>
 201     <listitem><para>start polling for termlists</para></listitem></varlistentry>
 202
 203     <varlistentry><term>bytarget ()</term>
 204     <listitem><para>start polling for target status</para></listitem></varlistentry>
 205
 206     <varlistentry><term>stat ()</term>
 207     <listitem><para>start polling for pazpar2 status</para></listitem></varlistentry>
 208
 209   </variablelist>
 210
 211   <para/>
 212   <para>Pz2.js comes with a set of cross-browser helper classes and functions.</para>
 213
 214   <variablelist>
 215
 216     <para><bridgehead>AJAX helper class</bridgehead></para>
 217
 218     <varlistentry><term>pzHttpRequest</term>
 219     <listitem><para>a cross-browser Ajax wrapper class</para></listitem></varlistentry>
 220
 221     <varlistentry><term>constructor (url, errorHandler)</term>
 222     <listitem><para>create new request for a given url</para></listitem></varlistentry>
 223
 224     <varlistentry><term>get (params, callback)</term>
 225     <listitem><para>asynchronous, send the request with given parameters (array) and call callback with response as parameter</para></listitem></varlistentry>
 226
 227     <varlistentry><term>post (params, data, callback)</term>
 228     <listitem><para>asychronous, post arbitrary data (may be XML doc) and call callback with response as parameter</para></listitem></varlistentry>
 229
 230     <varlistentry><term>load ()</term>
 231     <listitem><para>synchronous, returns the response for the given request</para></listitem></varlistentry>
 232
 233   </variablelist>
 234
 235   <variablelist>
 236
 237     <para><bridgehead>XML helper functions</bridgehead></para>
 238
 239     <varlistentry><term>document.newXmlDoc (root)</term>
 240     <listitem><para>create new XML document with root node as specified in parameter</para></listitem></varlistentry>
 241
 242     <varlistentry><term>document.parseXmlFromString (xmlString)</term>
 243     <listitem><para>create new XML document from string</para></listitem></varlistentry>
 244
 245     <varlistentry><term>document.transformToDoc (xmlDoc, xslDoc)</term>
 246     <listitem><para>returns new XML document as a result</para></listitem></varlistentry>
 247
 248     <varlistentry><term>Element_removeFromDoc (DOM_Element)</term>
 249     <listitem><para>remove element from the document</para></listitem></varlistentry>
 250
 251     <varlistentry><term>Element_emptyChildren (DOM_Element)</term></varlistentry>
 252
 253     <varlistentry><term>Element_appendTransformResult (DOM_Element, xmlDoc, xslDoc)</term>
 254     <listitem><para>append xsl transformation result to a DOM element</para></listitem></varlistentry>
 255
 256     <varlistentry><term>Element_appendTextNode (DOM_Element, tagName, textContent)</term>
 257     <listitem><para>append new text node to the element</para></listitem></varlistentry>
 258
 259     <varlistentry><term>Element_setTextContent (DOM_Element, textContent)</term>
 260     <listitem><para>set text content of the element</para></listitem></varlistentry>
 261
 262     <varlistentry><term>Element_getTextContent (DOM_Element)</term>
 263     <listitem><para>get text content of the element</para></listitem></varlistentry>
 264
 265     <varlistentry><term>Element_parseChildNodes (DOM_Element)</term>
 266     <listitem><para>parse all descendants into an associative array</para></listitem></varlistentry>
 267
 268   </variablelist>
 269
 270 </section>
 271
 272 <!-- Keep this comment at the end of the file
 273  Local variables:
 274  mode: sgml
 275  sgml-omittag:t
 276  sgml-shorttag:t
 277  sgml-minimize-attributes:nil
 278  sgml-always-quote-attributes:t
 279  sgml-indent-step:1
 280  sgml-indent-data:t
 281  sgml-parent-document: nil
 282  sgml-local-catalogs: nil
 283  sgml-namecase-general:t
 284  End:
 285  -->