1: <?php
2: /*
3: File: xajaxUserFunction.inc.php
4:
5: Contains the xajaxUserFunction class
6:
7: Title: xajaxUserFunction class
8:
9: Please see <copyright.inc.php> for a detailed description, copyright
10: and license information.
11: */
12:
13: /*
14: @package xajax
15: @version $Id: xajaxUserFunction.inc.php 362 2007-05-29 15:32:24Z calltoconstruct $
16: @copyright Copyright (c) 2005-2007 by Jared White & J. Max Wilson
17: @copyright Copyright (c) 2008-2010 by Joseph Woolley, Steffen Konerow, Jared White & J. Max Wilson
18: @license http://www.xajaxproject.org/bsd_license.txt BSD License
19: */
20:
21: /*
22: Class: xajaxUserFunction
23:
24: Construct instances of this class to define functions that will be registered
25: with the <xajax> request processor. This class defines the parameters that
26: are needed for the definition of a xajax enabled function. While you can
27: still specify functions by name during registration, it is advised that you
28: convert to using this class when you wish to register external functions or
29: to specify call options as well.
30: */
31: final class xajaxUserFunction
32: {
33: /*
34: String: sAlias
35:
36: An alias to use for this function. This is useful when you want
37: to call the same xajax enabled function with a different set of
38: call options from what was already registered.
39: */
40: private $sAlias;
41:
42: /*
43: Object: uf
44:
45: A string or array which defines the function to be registered.
46: */
47: private $uf;
48:
49: /*
50: String: sInclude
51:
52: The path and file name of the include file that contains the function.
53: */
54: private $sInclude;
55:
56: /*
57: Array: aConfiguration
58:
59: An associative array containing call options that will be sent to the
60: browser curing client script generation.
61: */
62: private $aConfiguration;
63:
64: /*
65: Function: xajaxUserFunction
66:
67: Constructs and initializes the <xajaxUserFunction> object.
68:
69: $uf - (mixed): A function specification in one of the following formats:
70:
71: - a three element array:
72: (string) Alternate function name: when a method of a class has the same
73: name as another function in the system, you can provide an alias to
74: help avoid collisions.
75: (object or class name) Class: the name of the class or an instance of
76: the object which contains the function to be called.
77: (string) Method: the name of the method that will be called.
78: - a two element array:
79: (object or class name) Class: the name of the class or an instance of
80: the object which contains the function to be called.
81: (string) Method: the name of the method that will be called.
82: - a string:
83: the name of the function that is available at global scope (not in a
84: class.
85:
86: $sInclude - deprecated syntax - use ->configure('include','/path/to/file'); instead
87: $sInclude - (string, optional): The path and file name of the include file
88: that contains the class or function to be called.
89:
90: $aConfiguration - marked as deprecated - might become reactivated as argument #2
91: $aConfiguration - (array, optional): An associative array of call options
92: that will be used when sending the request from the client.
93:
94: Examples:
95:
96: $myFunction = array('alias', 'myClass', 'myMethod');
97: $myFunction = array('alias', &$myObject, 'myMethod');
98: $myFunction = array('myClass', 'myMethod');
99: $myFunction = array(&$myObject, 'myMethod');
100: $myFunction = 'myFunction';
101:
102: $myUserFunction = new xajaxUserFunction($myFunction, 'myFile.inc.php', array(
103: 'method' => 'get',
104: 'mode' => 'synchronous'
105: ));
106:
107: $xajax->register(XAJAX_FUNCTION, $myUserFunction);
108: */
109: public function xajaxUserFunction($uf) // /*deprecated parameters */ $sInclude=NULL, $aConfiguration=array())
110: {
111: $this->sAlias = '';
112: $this->uf = $uf;
113: $this->aConfiguration = array();
114:
115: /*deprecated parameters */
116: // $this->sInclude = $sInclude;
117: // foreach ($aConfiguration as $sKey => $sValue)
118: // $this->configure($sKey, $sValue);
119:
120: if (is_array($this->uf) && 2 < count($this->uf))
121: {
122: $this->sAlias = $this->uf[0];
123: $this->uf = array_slice($this->uf, 1);
124: }
125:
126: //SkipDebug
127: if (is_array($this->uf) && 2 != count($this->uf))
128: trigger_error(
129: 'Invalid function declaration for xajaxUserFunction.',
130: E_USER_ERROR
131: );
132: //EndSkipDebug
133: }
134:
135: /*
136: Function: getName
137:
138: Get the name of the function being referenced.
139:
140: Returns:
141:
142: string - the name of the function contained within this object.
143: */
144: public function getName()
145: {
146: // Do not use sAlias here!
147: if (is_array($this->uf))
148: return $this->uf[1];
149: return $this->uf;
150: }
151:
152: /*
153: Function: configure
154:
155: Call this to set call options for this instance.
156: */
157: public function configure($sName, $sValue)
158: {
159: if ('alias' == $sName)
160: $this->sAlias = $sValue;
161: if ('include' == $sName)
162: $this->sInclude = $sValue;
163: else
164: $this->aConfiguration[$sName] = $sValue;
165: }
166:
167: /*
168: Function: generateRequest
169:
170: Constructs and returns a <xajaxRequest> object which is capable
171: of generating the javascript call to invoke this xajax enabled
172: function.
173: */
174: public function generateRequest($sXajaxPrefix)
175: {
176: $sAlias = $this->getName();
177: if (0 < strlen($this->sAlias))
178: $sAlias = $this->sAlias;
179: return new xajaxRequest("{$sXajaxPrefix}{$sAlias}");
180: }
181:
182: /*
183: Function: generateClientScript
184:
185: Called by the <xajaxPlugin> that is referencing this function
186: reference during the client script generation phase. This function
187: will generate the javascript function stub that is sent to the
188: browser on initial page load.
189: */
190: public function generateClientScript($sXajaxPrefix)
191: {
192: $sFunction = $this->getName();
193: $sAlias = $sFunction;
194: if (0 < strlen($this->sAlias))
195: $sAlias = $this->sAlias;
196: echo "{$sXajaxPrefix}{$sAlias} = function() { ";
197: echo "return xajax.request( ";
198: echo "{ xjxfun: '{$sFunction}' }, ";
199: echo "{ parameters: arguments";
200:
201: $sSeparator = ", ";
202: foreach ($this->aConfiguration as $sKey => $sValue)
203: echo "{$sSeparator}{$sKey}: {$sValue}";
204:
205: echo " } ); ";
206: echo "};\n";
207: }
208:
209: /*
210: Function: call
211:
212: Called by the <xajaxPlugin> that references this function during the
213: request processing phase. This function will call the specified
214: function, including an external file if needed and passing along
215: the specified arguments.
216: */
217: public function call($aArgs=array())
218: {
219: $objResponseManager = xajaxResponseManager::getInstance();
220:
221: if (NULL != $this->sInclude)
222: {
223: ob_start();
224: require_once $this->sInclude;
225: $sOutput = ob_get_clean();
226:
227: //SkipDebug
228: if (0 < strlen($sOutput))
229: {
230: $sOutput = 'From include file: ' . $this->sInclude . ' => ' . $sOutput;
231: $objResponseManager->debug($sOutput);
232: }
233: //EndSkipDebug
234: }
235:
236: $mFunction = $this->uf;
237: $objResponseManager->append(call_user_func_array($mFunction, $aArgs));
238: }
239: }
240: ?>
241: