xajax dhtmlHistory-Extension (Bookmark and Backbutton)

Based on Brad Neuberg's "Really Simple History". See: <a href="http://code.google.com/p/reallysimplehistory/" target="new">his page</a> for details

This plugin makes it possible to handle the browsers backbutton functionality and provides a simple bookmarking management.
It works with IE and FF and with the new RSH Version also with Opera and even Safari. <h2>xajax 0.5 Beta4 - Really Simple History 0.6</h2><b>Last changed: 2007-12-03</b>
The package contains the following files:

<table border="1"> <tbody><tr><th>file</th><th>folder</th><th>comment</th></tr> <tr><td colspan="3"><b>plugin files</b></td></tr> <tr><td>dhtmlHistory.inc.php</td><td>./xajax/xajax_plugins/response</td><td>the xajax plugin</td></tr> <tr><td>rsh.compressed.js</td><td>./xajax/xajax_plugins/response</td><td>the original rsh javascript</td></tr> <tr><td>json2007.js</td><td>./xajax/xajax_plugins/response</td><td>default JSON parser supplied with the original rsh javascript</td></tr> <tr><td>blank.html</td><td>./</td><td>a helper file for the IE iframe solution. must be located in the same folder as index.php</td></tr> <tr><td colspan="3"><b>sample files</b></td></tr> <tr><td>index.php</td><td>./</td><td>an example implementation as a simple showcase</td></tr> <tr><td>waypoint.inc.php</td><td>./</td><td>an helper file for the example implementation. implements the waypoint handler</td></tr> </tbody></table>

<h3>Quickstart</h3> 1. Copy the plugin files to your server into the above named folders

2. In your version of "index.php": <ul><li>Call dhtmlHistoryAdd($objResponse, $sWaypointName, $aWaypointData) in your xajax response functions to add waypoints for the backbutton handling</li></ul> 3. In your version of waypoint.inc.php: <ul><li>Implement a xajax response function which will be called when the backbutton is clicked. $sWaypointName and $aWaypointData will be given to you to restore the old waypoint.</li></ul> <h3>Tutorial</h3> <h4>One general ajax "disadvantage"</h4> You may have some kind of menu which calls xajax functions to modify the page content:

<pre><ul id="top_menu">
<li><a href="http://www.blogger.com/post-edit.g?blogID=4291973661386596812&postID=5701704131189757312#" onclick="xajax_top_menu(1); return false;">menu1</a></li>
<li><a href="http://www.blogger.com/post-edit.g?blogID=4291973661386596812&postID=5701704131189757312#" onclick="xajax_top_menu(2); return false;">menu2</a></li>
<li><a href="http://www.blogger.com/post-edit.g?blogID=4291973661386596812&postID=5701704131189757312#" onclick="xajax_top_menu(3); return false;">menu3</a></li>
<li><a href="http://www.blogger.com/post-edit.g?blogID=4291973661386596812&postID=5701704131189757312#" onclick="xajax_top_menu(4); return false;">menu4</a></li>
<li><a href="http://www.blogger.com/post-edit.g?blogID=4291973661386596812&postID=5701704131189757312#" onclick="xajax_top_menu(5); return false;">menu5</a></li>
<li><a href="http://www.blogger.com/post-edit.g?blogID=4291973661386596812&postID=5701704131189757312#" onclick="xajax_top_menu(6); return false;">menu6</a></li>
</ul></pre> <pre>function top_menu($nMenu)
{
$objResponse = new xajaxResponse();
$objResponse->assign('content', 'innerHTML', 'NEW CONTENT');
return $objResponse;
}</pre> <p>Using that kind of navigation you will get no browser history entries and therefore the browsers backbutton can not be used. Here's where the plugin comes in.</p> <h4>Adding a waypoint</h4> <p> By adding a single function call into your response function you can set a browser history entry also called "waypoint". </p> <pre>dhtmlHistoryAdd($objResponse, $sWaypointName, $aWaypointData); </pre> <p> sWaypointName: name of the waypoint which is used like an anchor (string)
aWaypointData: data which is needed to recover this very waypoint (mixed)

Please note that the waypoint data will be lost if the user leaves the actual page since it is stored using a hidden form element. </p> <p> This will lead to: </p> <pre>function top_menu($nMenu)
{
$sWaypointName = 'menu'.$nMenu;
$aWaypointData = array('my data to recover','this waypoint');

$objResponse = new xajaxResponse();

dhtmlHistoryAdd($objResponse, $sWaypointName, $aWaypointData);

$objResponse->assign('content', 'innerHTML', 'NEW CONTENT');
return $objResponse;
}</pre> <h4>Including the plugin</h4> <p> The function dhtmlHistoryAdd() is provided with the plugin in the file <em class="mono">dhtmlHistory.inc.php</em>. It has to be copied into the xajax/xajax_plugins/response folder to be loaded when creating an instance of the xajax class. </p> <p> The heart of the plugin is the javascript code <em class="mono">dhtmlHistory.js</em> which could be copied into the same folder. </p> <p> The plugin has to be included at the begining: </p> <pre>$xajax = new xajax();
require $xajaxPlugins . '/response/dhtmlHistory.inc.php';</pre> <h4>Implementing the waypoint handler</h4> <p> The last step is to provide a "waypoint handler". This is the function which will be called when the user clicks the browsers backbutton. The waypoint handler is a xajax response function which has to be registered... </p> <pre>$xajax->registerFunction('waypoint_handler','waypoint.inc.php'); </pre> <p> ... and certainly implemented. The function name must be "waypoint_handler" for the time being.
You need to code <b>your</b> logic to rebuild the situation which was saved when adding the waypoint by using the parameters you saved to that waypoint. </p> <pre>function waypoint_handler($sWaypointName, $sWaypointData)
{
$objResponse = new xajaxResponse();
if ($sWaypointName!='')
{
$aWaypointData = decodeWaypointData($sWaypointData);

//TODO: recover your content using the parameters

$objResponse->assign("content", "innerHTML", "YOUR RECOVERED CONTENT");
//or maybe
$objResponse->script("xajax_topmenu('".$aWaypointData[0]."')");
}
return $objResponse;
}</pre> <p> The function call decodeWaypointData() is neccessary because the waypoint data is stored in a serialized format and need to be deserialized to be used. I did not yet hide the decoding within the plugin. </p> <p> That's it.
Please see the inline comments for more details.
Feel free to comment or <a href="mailto:ralf@goldenzazu.de">contact me</a> on any issues or suggestions. </p>