modules/xajax/README.txt

Overview
--------
This module facilitates using the xajax javascript library with your drupal site.
It handles adding the js library include and looks for hooks in other modules
to register xajax functions.

Installation
------------
  1. Copy the xajax folder into your modules directory.
  2. Download the xajax library from http://www.xajaxproject.org/ and put it
in a folder named "inc" in the xajax folder (sorry, Drupal gods don't want
external libraries included in CVS).
  3. Enable the module in your drupal administration.

Usage
-----
For any module that you wish to add ajax functionality to, simply create a function 
named <module>_ajax_init. If your module is named "mymodule," the function would be
named "mymodule_ajax_init" and should take a single parameter by reference named
$xajax. 

That function should look something like the following:

	function mymodule_xajax_init(&$xajax){
		$xajax->registerFunction("mymodule_dosomething");
	}

You should then define the function "mymodule_dosomething." This function performs
drupal operations such as database updates in addition to xajax operations such
as updating the UI. See http://xajax.sourceforge.net/#update for info on performing
xajax operations.

Xajax works by mapping php function names to javascript function names and passing 
javascript parameters through to the php function. So if you define a php function
named "mymodule_dosomething" and register it in your init function (as above), it
automatically gets added to the javascript include and can be used in your ui, as
follows:

	<a href="javascript:void(0)" onclick="xajax_mymodule_dosomething(45); return false;">Test</a>

The value 'test' is the first parameter to the corresponding php function, which 
might be defined as follows:

	function mymodule_dosomething($val){
		$objResponse = new xajaxResponse();
		if(user_access('can test')){
			$result=db_query("UPDATE mymodule SET test=1 WHERE mid=%d",$val);
			$objResponse->addAssign("response_div","innerHTML","test complete!");
		}
		return $objResponse->getXML();
	}

Rather more briefly, the steps are as follows:

	1. Define a workhorse function to do drupal and xajax heavy lifting.
	2. In your module, create a function named <module>_xajax_init.
	3. In that function, register any workhorse functions you've created for this module.
	4. Add js hooks within your ui; function calls match the workhorse function names
	   with "xajax_" prepended.

1	Overview
2	--------
3	This module facilitates using the xajax javascript library with your drupal site.
4	It handles adding the js library include and looks for hooks in other modules
5	to register xajax functions.
6
7	Installation
8	------------
9	1. Copy the xajax folder into your modules directory.
10	2. Download the xajax library from http://www.xajaxproject.org/ and put it
11	in a folder named "inc" in the xajax folder (sorry, Drupal gods don't want
12	external libraries included in CVS).
13	3. Enable the module in your drupal administration.
14
15	Usage
16	-----
17	For any module that you wish to add ajax functionality to, simply create a function
18	named <module>_ajax_init. If your module is named "mymodule," the function would be
19	named "mymodule_ajax_init" and should take a single parameter by reference named
20	$xajax.
21
22	That function should look something like the following:
23
24	function mymodule_xajax_init(&$xajax){
25	$xajax->registerFunction("mymodule_dosomething");
26	}
27
28	You should then define the function "mymodule_dosomething." This function performs
29	drupal operations such as database updates in addition to xajax operations such
30	as updating the UI. See http://xajax.sourceforge.net/#update for info on performing
31	xajax operations.
32
33	Xajax works by mapping php function names to javascript function names and passing
34	javascript parameters through to the php function. So if you define a php function
35	named "mymodule_dosomething" and register it in your init function (as above), it
36	automatically gets added to the javascript include and can be used in your ui, as
37	follows:
38
39	<a href="javascript:void(0)" onclick="xajax_mymodule_dosomething(45); return false;">Test</a>
40
41	The value 'test' is the first parameter to the corresponding php function, which
42	might be defined as follows:
43
44	function mymodule_dosomething($val){
45	$objResponse = new xajaxResponse();
46	if(user_access('can test')){
47	$result=db_query("UPDATE mymodule SET test=1 WHERE mid=%d",$val);
48	$objResponse->addAssign("response_div","innerHTML","test complete!");
49	}
50	return $objResponse->getXML();
51	}
52
53	Rather more briefly, the steps are as follows:
54
55	1. Define a workhorse function to do drupal and xajax heavy lifting.
56	2. In your module, create a function named <module>_xajax_init.
57	3. In that function, register any workhorse functions you've created for this module.
58	4. Add js hooks within your ui; function calls match the workhorse function names
59	with "xajax_" prepended.
60