.. You may want to use the usual include line. Uncomment and adjust the path. 
.. include:: ../Includes.txt


===============
EXT: SO\_JPSPAN
===============

:Author:
      Kasper Skårhøj

:Created:
      2002-11-01T00:32:00

:Changed by:
      Onno Schuit

:Changed:
      2005-06-09T21:35:49

:Classification:
      JPSpan library as a Typo3 extension

:Keywords:
      jpspan, ajax

:Author:
      Onno Schuit

:Email:
      o.schuit@solin.nl

:Info 3:


:Info 4:


.. _EXT-SO-JPSPAN:

EXT: SO\_JPSPAN
===============

Extension Key:  **so\_jpspan**

Copyright 2000-2002, Onno Schuit, <o.schuit@solin.nl>

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

\- a GNU/GPL CMS/Framework available from www.typo3.com

.. _Table-of-Contents:

Table of Contents
-----------------

**EXT: SO\_JPSPAN 1**

**Introduction 1**

What does it do? 1

Differences with the original JPSpan library 1

Licence 1

**Users manual 1**

**Configuration 2**

Usage 2

**To-Do list 3**


.. _Introduction:

Introduction
------------


.. _What-does-it-do:

What does it do?
^^^^^^^^^^^^^^^^

This extension mainly acts as a container for the slightly modified
“JPSpan Library”, a framework consisting of php and javascript classes
and files for implementing  *AJAX: Asynchronous Javascript And XML.*
Ajax is a technology to reduce page refreshes, thereby enhancing the
usability of a website *.* The Google Suggest autocompletion feature
is a famous example of ajax. With the JPSpan library you can improve
the usability of your own extensions.

In order to avoid redundant code for TYPO3 extensions, we recommend
using the JPSpan library of this extension instead of including it in
your own extension.


.. _Differences-with-the-original-JPSpan-library:

Differences with the original JPSpan library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The so\_jpspan extension uses a slightly modified version of JPSpan to
allow the use of query string parameters. This is necessary to pass on
the value of the Typo3 parameter  *id* with each call of *index.php* .

Please find the original source base here:

http://prdownloads.sourceforge.net/jpspan/


.. _Licence:

Licence
^^^^^^^

The JPSpan Library is released under the PHP License, by Harry Fuecks
and Jason E. Sweat.

Please read the readme and license files in the EXT:so\_jpspan/jpspan/
directory for more information.


.. _Users-manual:

Users manual
------------

“Do not open. No user serviceable parts inside”.

This extension provides a code base for other extensions but does not
offer any functionality to end users.


.. _Configuration:

Configuration
-------------

No configuration is necessary at this point. After installing the
*so\_jpspan* extension, just include the jpspan library in your own
extension with this codeline:

::

   require_once (t3lib_extMgm::extPath('so_jpspan').'JPSpan/JPSpan.php');


.. _Usage:

Usage
^^^^^

All JPSpan examples are based on file names to control the flow of the
application. This is different in Typo3, where we have one file
(index.php) which controls the entire cms using the  *id* parameter to
load specific pages.

I have therefore modified JPSpan to allow the use of query string
parameters. In the so\_jpspan version of JPSpan, a query string is
passed on with each call (except for the “client” parameter, which is
omitted from second and subsequent calls).

The following is the reworked “autocomplete2” example (which itself is
distributed with the JPSpan source code).

::

   require_once(PATH_tslib."class.tslib_pibase.php");
   require_once (t3lib_extMgm::extPath('so_jpspan').'JPSpan/JPSpan.php');
   // Load the PostOffice server
   require_once JPSPAN . 'Server/PostOffice.php';
   
   class tx_sojpspantest_pi1 extends tslib_pibase {
           var $prefixId = "tx_sojpspantest_pi1";                // Same as class name
           var $scriptRelPath = "pi1/class.tx_sojpspantest_pi1.php";     // Path to this script relative to the extension dir.
           var $extKey = "so_jpspantest";        // The extension key.
           var $view;
           
           /**
            * [Put your description here]
            */
           function main($content,$conf)   {
                   $this->conf=$conf;
                   $this->pi_setPiVarDefaults();
                   $this->pi_loadLL();
                           
                   /* Application flow is determined by a GET or POST variable "view".
                    * Is there is no value for view, the default view is presented.
                    * Otherwise, the view ultimately dictates which view is presented next.                                 
                    */
                   if (isset($this->piVars['view'])) {
                           //exit('piVars = '.$this->piVars['view']);
                           $this->view  = $this->piVars['view'];
                   } 
                                   
                   /* Control structure */
                   //t3lib_div::debug($this->piVars);
                   switch ($this->view) {              
                           
                           case "autocomplete2":                                                    
                              include_once($ext_path.'autocomplete2_server.php');                                                                                                   
                                   break;
                                                                                   
                           default:
                                   $GLOBALS['TSFE']->additionalHeaderData[$this->extKey]='
                                           <script type="text/javascript" src="'.t3lib_extMgm::siteRelPath($this->extKey).'actb/actb2.js"></script>                                     
                                           <link rel="stylesheet" href="'.t3lib_extMgm::siteRelPath($this->extKey).'actb/actb2.css"/>                                                                                                 
                                           <script type="text/javascript" src="'.$this->pi_getPageLink($GLOBALS["TSFE"]->id,'',array($this->prefixId.'[view]'=>'autocomplete2','no_cache' => 1,'client' => '1')).'"></script>                                                                 
                                           <script type="text/javascript">
                                           var countries;
                                           ...

Here, we use a query string parameter “view” to control the flow of
the application (using a switch construction), instead of relying on
the file names.

Also, as you can see, the client parameter which JPSPan uses, has been
given a value (1), whereas in the original JPSpan source base, there
is no value.

For this to work, you also need to modify the
autocomplete2\_server.php file:

::

   ...
   //-----------------------------------------------------------------------------------
   // Generates the Javascript client by adding ?client to the server URL
   //-----------------------------------------------------------------------------------
   // Be careful: strrpos cannot take more than 1 character as an argument in PHP4 (but strpos can)
   if (isset($_SERVER['QUERY_STRING']) && (strpos($_SERVER['QUERY_STRING'],'client=1')) ) {
       $S->displayClient();
       
   //-----------------------------------------------------------------------------------
   } else {         
       // Include error handler - PHP errors, warnings and notices serialized to JS
       require_once JPSPAN . 'ErrorHandler.php';
       $S->serve();
   }

The difference is in the way the branch is solved: here, we check if
the query string 'client=1' is present.

If you know JPSpan well, it is probably interesting to learn where the
query string is actually added. This happens in
EXT:so\_jpspan/jpspan/jpspan/server.php:

::

   ...
   /**
   * Sets up the default server url
   * @access public
   */
   function JPSpan_Server() {          
     if ( isset($_SERVER['HTTPS']) && strtolower($_SERVER['HTTPS']) == 'on' ) {
         $prot = 'https://';
     } else {
         $prot = 'http://';
     }
    /***
     * Added by O.S.
     * 
     * The first call to this script is to just output the standard javascript classes.
     * Second and subsequent calls, however, are meant to serve up the data.
     * So, we take the client parameter out of the query_string, to make sure that we do not
     * enter the wrong branch on second and subsequent calls.
     *
     * In other words: this is to enable propagation of query string parameters.
     */         
     $querystring = (isset($_SERVER['QUERY_STRING'])) ? '?'.str_replace('&client=1', "", $_SERVER['QUERY_STRING']) : '';                                
     $this->serverUrl = $prot.$_SERVER['HTTP_HOST'].$this->resolveScriptName() . $querystring;                    
   }
   ...

And in PostOffice.php in two places:

::

   function resolveCall() {
           // Hack between server.php?class/method and server.php/class/method                       
           // Modified by Onno Schuit, Solin, 20050609: querystring may now also contain other parameters        
           $uriPath = (strrpos($_SERVER['QUERY_STRING'],'&')) ? substr($_SERVER['QUERY_STRING'], (strrpos($_SERVER['QUERY_STRING'],'&'))+1) : $_SERVER['QUERY_STRING'];        
   
   ...
   
       oParent.__serverurl = '<?php 
                     // Modified by Onno Schuit, Solin, 20050609: serverUrl may now also contain existing querystring    
             if (strrpos($this->serverUrl,'?')) {
                      echo $this->serverUrl . '&' . $Description->Class;
             } else {        
               echo $this->serverUrl . '?' . $Description->Class;
             }
             ?>';        

This should be all you need to know to rework the standard JPSpan
examples for use with Typo3. And to make your own great ajax-wielding
extensions, of course.


.. _To-Do-list:

To-Do list
----------

\- Every call to a JPSpan “server” file now also includes the entire
Typo3 framework (as is the case for any other extension). Perhaps just
including the necessary functionality, and leaving out things like
templating libraries, would increase performance.

\- Maybe the ajax paradigm could also be applied to (parts of) the
backend of Typo3.

|img-1| EXT: SO\_JPSPAN - 3


.. ######CUTTER_MARK_IMAGES######

.. |img-1| image:: img-1.png
.. :align: left
.. :border: 0
.. :height: 32
.. :id: Graphic1
.. :name: Graphic1
.. :width: 102