modules/ac/README.txt

       Ajax Controller
       Developed by Tj Holowaychuk
       Maintained by AC
       $Id: README.txt,v 1.6 2009/06/17 22:48:15 ac Exp $
       
       ------------------------------------------------------------------------------- 
       INSTALLATION
       ------------------------------------------------------------------------------- 
       
       Simple enable the module. 
     
       ------------------------------------------------------------------------------- 
       PERMISSIONS
       ------------------------------------------------------------------------------- 
       
       None 
         
       ------------------------------------------------------------------------------- 
       PUBLIC API
       -------------------------------------------------------------------------------
       
       AC.request();
       AC.checkResponse();   
       ac_debug();   
        
       ------------------------------------------------------------------------------- 
       HOOKS
       -------------------------------------------------------------------------------
          
       - hook_js_response_alter(&$response, $module, $op) 
         Allows modules to alter ajax callback responses before they are outputted
         to the client or browser. This is useful for tasks such as changing the 
         message output wrapper for all responses.
         
       ------------------------------------------------------------------------------- 
       USAGE EXAMPLE
       -------------------------------------------------------------------------------
       
       // example.js      
       AC.request('example', 'delete', { 'content_id' : 1 }, function(response){
          if (AC.checkResponse(response)){
            $('#content-1').remove();
          }
       });  
       
       // example.module
       function example_js_delete(&$state, $args) {
         $state['message_wrapper'] = '#content #message-wrapper';
         
         if ($cid = $args['content_id']){  
           if (example_delete($cid)){
             $state['message'] = t('Request complete');
           }
           else {
             $state['status'] = AC_STATUS_ERROR;
             $state['message'] = t('Failed to delete !cid.', array('!cid' => $cid));
           }
         }

         // Always lock request for 5 seconds regardless of errors
         $state['lock'] = 5;
       }
       
       // Default response members
       // see ac_get_default_response() in ac.inc for details
       status = AC_STATUS_OK
       message = '' 
       message_wrapper = '#ac-messages' 
       message_duration = 3000 
       message_position = NULL
       message_class = ''
       output = NULL 
       encoding = AC_ENCODING_AUTO 
       format = AC_OUTPUT_JSON 
       lock = 0
       headers = array() 

       ------------------------------------------------------------------------------- 
       FUTURE GOALS
       ------------------------------------------------------------------------------- 
       
       - Add hook_ac similar to menu hook instead, which would allow
         for the cache mechanism to work correctly, and store callbacks in includes
         however this would be slight overkill for most implementations. 
         Consider extending menu hook although unlikely.
       - Add caching flags similar to the block module
       - Add message effects
       - Add 'message_func' allowing jQuery to prepend, append, replace, or insert messages
         into the DOM rather than JUST inserting.
       
           
 
 

1	Ajax Controller
2	Developed by Tj Holowaychuk
3	Maintained by AC
4	$Id: README.txt,v 1.6 2009/06/17 22:48:15 ac Exp $
5
6	-------------------------------------------------------------------------------
7	INSTALLATION
8	-------------------------------------------------------------------------------
9
10	Simple enable the module.
11
12	-------------------------------------------------------------------------------
13	PERMISSIONS
14	-------------------------------------------------------------------------------
15
16	None
17
18	-------------------------------------------------------------------------------
19	PUBLIC API
20	-------------------------------------------------------------------------------
21
22	AC.request();
23	AC.checkResponse();
24	ac_debug();
25
26	-------------------------------------------------------------------------------
27	HOOKS
28	-------------------------------------------------------------------------------
29
30	- hook_js_response_alter(&$response, $module, $op)
31	Allows modules to alter ajax callback responses before they are outputted
32	to the client or browser. This is useful for tasks such as changing the
33	message output wrapper for all responses.
34
35	-------------------------------------------------------------------------------
36	USAGE EXAMPLE
37	-------------------------------------------------------------------------------
38
39	// example.js
40	AC.request('example', 'delete', { 'content_id' : 1 }, function(response){
41	if (AC.checkResponse(response)){
42	$('#content-1').remove();
43	}
44	});
45
46	// example.module
47	function example_js_delete(&$state, $args) {
48	$state['message_wrapper'] = '#content #message-wrapper';
49
50	if ($cid = $args['content_id']){
51	if (example_delete($cid)){
52	$state['message'] = t('Request complete');
53	}
54	else {
55	$state['status'] = AC_STATUS_ERROR;
56	$state['message'] = t('Failed to delete !cid.', array('!cid' => $cid));
57	}
58	}
59
60	// Always lock request for 5 seconds regardless of errors
61	$state['lock'] = 5;
62	}
63
64	// Default response members
65	// see ac_get_default_response() in ac.inc for details
66	status = AC_STATUS_OK
67	message = ''
68	message_wrapper = '#ac-messages'
69	message_duration = 3000
70	message_position = NULL
71	message_class = ''
72	output = NULL
73	encoding = AC_ENCODING_AUTO
74	format = AC_OUTPUT_JSON
75	lock = 0
76	headers = array()
77
78	-------------------------------------------------------------------------------
79	FUTURE GOALS
80	-------------------------------------------------------------------------------
81
82	- Add hook_ac similar to menu hook instead, which would allow
83	for the cache mechanism to work correctly, and store callbacks in includes
84	however this would be slight overkill for most implementations.
85	Consider extending menu hook although unlikely.
86	- Add caching flags similar to the block module
87	- Add message effects
88	- Add 'message_func' allowing jQuery to prepend, append, replace, or insert messages
89	into the DOM rather than JUST inserting.
90
91
92
93
94