MAJOR UPGRADE to TComponent

This adds global 'fx' events, behaviors, class-wide behaviors, intra-object/behavior 'dy' events, and tweaks the raiseEvent to be more advanced (yet backward compatible).  A large amount of documentation is in here too.  Slight changes to the TApplication object is  made to provide events with priorities.  TComponent has a massive amount of test cases as well…  There are now 512 assertions.  Test cases have been added for testing the GetJS and SetJS and ensure functionality of these new getters and setters.

The Behaviors are all tested and fully integrated into the TComponent Object.  Behaviors are more transparently and widely integrated into TComponent.

Class Behaviors rely on the global events to add behaviors to instanced objects.  Class behaviors also allow for behaviors to be added during the instancing of new objects of the class.

Dynamic events enable the object to send events directly to behaviors as intra-object events.  Dynamic events can be chained as multiple behaviors may implement the event.  This allows for parameter filtering.

RaiseEvent allows for raising global events, capturing results, and feeding results forward into the next handlers parameters should the need arise.  This is a forward thinking feature to enable new processes to be designed into the code for PRADO version 3.3 and future version 4.0.  This functionality is transparent when unused.

We are hoping this is fully backward compatible with the existing code base.  It was designed for maximum backward compatibility while expanding the functional base exponentially.

This clears the way for a new way of thinking about how objects relate.

3 files changed, 270 insertions, 0 deletions

diff --git a/framework/Util/TBehavior.php b/framework/Util/TBehavior.php
new file mode 100644
index 00000000..465f9673
--- /dev/null
+++ b/framework/Util/TBehavior.php
@@ -0,0 +1,87 @@
+<?php
+/**
+ * CBehavior class file.
+ *
+ * @author Qiang Xue <qiang.xue@gmail.com>
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright &copy; 2008-2009 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+/**
+ * CBehavior is a convenient base class for behavior classes.
+ * @author Qiang Xue <qiang.xue@gmail.com>
+ * @version $Id: CBehavior.php 564 2009-01-21 22:07:10Z qiang.xue $
+ * @package system.base
+ * @since 1.0.2
+ */
+class TBehavior extends TComponent implements IBehavior
+{
+	private $_enabled;
+	private $_owner;
+
+	/**
+	 * Declares events and the corresponding event handler methods.
+	 * The events are defined by the {@link owner} component, while the handler
+	 * methods by the behavior class. The handlers will be attached to the corresponding
+	 * events when the behavior is attached to the {@link owner} component; and they
+	 * will be detached from the events when the behavior is detached from the component.
+	 * @return array events (array keys) and the corresponding event handler methods (array values).
+	 */
+	public function events()
+	{
+		return array();
+	}
+
+	/**
+	 * Attaches the behavior object to the component.
+	 * The default implementation will set the {@link owner} property
+	 * and attach event handlers as declared in {@link events}.
+	 * Make sure you call the parent implementation if you override this method.
+	 * @param TComponent the component that this behavior is to be attached to.
+	 */
+	public function attach($owner)
+	{
+		$this->_owner=$owner;
+		foreach($this->events() as $event=>$handler)
+			$owner->attachEventHandler($event,array($this,$handler));
+	}
+
+	/**
+	 * Detaches the behavior object from the component.
+	 * The default implementation will unset the {@link owner} property
+	 * and detach event handlers declared in {@link events}.
+	 * Make sure you call the parent implementation if you override this method.
+	 * @param TComponent the component that this behavior is to be detached from.
+	 */
+	public function detach($owner)
+	{
+		foreach($this->events() as $event=>$handler)
+			$owner->detachEventHandler($event,array($this,$handler));
+		$this->_owner=null;
+	}
+
+	/**
+	 * @return CComponent the owner component that this behavior is attached to.
+	 */
+	public function getOwner()
+	{
+		return $this->_owner;
+	}
+
+	/**
+	 * @return boolean whether this behavior is enabled
+	 */
+	public function getEnabled()
+	{
+		return $this->_enabled;
+	}
+
+	/**
+	 * @param boolean whether this behavior is enabled
+	 */
+	public function setEnabled($value)
+	{
+		$this->_enabled=$value;
+	}
+}
\ No newline at end of file
diff --git a/framework/Util/TCallChain.php b/framework/Util/TCallChain.php
new file mode 100644
index 00000000..ae6e02fc
--- /dev/null
+++ b/framework/Util/TCallChain.php
@@ -0,0 +1,147 @@
+<?php
+/**
+ * TCallChain class file.
+ *
+ * @author Brad Anderson <javalizard@gmail.com>
+ * @link http://www.pradosoft.com/
+ * @copyright Copyright &copy; 2008-2011 Pradosoft
+ * @license http://www.pradosoft.com/license/
+ */
+
+/**
+ * TCallChain is a recursive event calling mechanism.  This class implements
+ * the {@link IDynamicMethods} class so that any 'dy' event calls can be caught
+ * and patched through to the intended recipient 
+ * @author Brad Anderson <javalizard@gmail.com>
+ * @version $Id: TCallChain.php 564 2009-01-21 22:07:10Z javalizard $
+ * @package system.base
+ * @since 3.2
+ */
+class TCallChain extends TList implements IDynamicMethods
+{
+	/**
+	 *	@var {@link TListIterator} for moving through the chained method calls
+	 */
+	private $_iterator=null;
+	
+	/**
+	 *	@var string the method name of the call chain
+	 */
+	private $_method=null;
+	
+	/**
+	 * This initializes the list and the name of the method to be called
+	 *	@param string the name of the function call
+	 */
+	public function __construct($method) {
+		$this->_method=$method;
+		parent::__construct();
+	}
+	
+	
+	/**
+	 * This initializes the list and the name of the method to be called
+	 *	@param string|array this is a callable function as a string or array with 
+	 *			the object and method name as string
+	 *  @param array The array of arguments to the function call chain
+	 */
+	public function addCall($method,$args)
+	{
+		$this->add(array($method,$args));
+	}
+	
+	/**
+	 * This method calls the next Callable in the list.  All of the method arguments
+	 * coming into this method are substituted into the original method argument of 
+	 * call in the chain.
+	 * 
+	 * If the original method call has these parameters
+	 * <code>
+	 * $originalobject->dyExampleMethod('param1', 'param2', 'param3')
+	 * </code>
+	 * <code>
+	 * $callchain->dyExampleMethod('alt1', 'alt2')
+	 * </code>
+	 * then the next call in the call chain will recieve the parameters as if this were called
+	 * <code>
+	 * $behavior->dyExampleMethod('alt1', 'alt2', 'param3', $callchainobject)
+	 * </code>
+	 *
+	 * When dealing with {@link IClassBehaviors}, the first parameter of the stored argument
+	 * list in 'dy' event calls is always the object containing the behavior.  This modifies
+	 * the parameter replacement mechanism slightly to leave the object containing the behavior
+	 * alone and only replacing the other parameters in the argument list.  As per {@link __call},
+	 * any calls to a 'dy' event do not need the object containing the behavior as the addition of 
+	 * the object to the argument list as the first element is automatic for IClassBehaviors.
+	 *
+	 * The last parameter of the method parameter list for any callable in the call chain
+	 * will be the TCallChain object itself.  This is so that any behavior implementing
+	 * these calls will have access to the call chain.  Each callable should either call
+	 * the TCallChain call method internally for direct chaining or call the method being
+	 * chained (in which case the dynamic handler will pass through to this call method).
+	 *
+	 * If the dynamic intra object/behavior event is not called in the behavior implemented
+	 * dynamic method, it will return to this method and call the following behavior
+	 * implementation so as no behavior with an implementation of the dynamic event is left
+	 * uncalled.  This does break the call chain though and will not act as a "parameter filter".
+	 *
+	 * When there are no handlers or no handlers left, it returns the first parameter of the
+	 * argument list.
+	 * 
+	 */
+	public function call()
+	{
+		$args=func_get_args();
+		if($this->getCount()===0)
+			return isset($args[0])?$args[0]:null;
+		
+		if(!$this->_iterator)
+		{
+			$chain_array=array_reverse($this->toArray());
+			$this->_iterator=new TListIterator($chain_array);
+		}
+		if($this->_iterator->valid())
+			do {
+				$handler=$this->_iterator->current();
+				$this->_iterator->next();
+				if(is_array($handler[0])&&$handler[0][0] instanceof IClassBehavior)
+					array_splice($handler[1],1,count($args),$args);
+				else
+					array_splice($handler[1],0,count($args),$args);
+				$handler[1][]=$this;
+				$result=call_user_func_array($handler[0],$handler[1]);
+			} while($this->_iterator->valid());
+		else
+			$result = $args[0];
+		return $result;
+	}
+	
+	
+	/**
+	 * This catches all the unpatched dynamic events.  When the method call matches the
+	 * call chain method, it passes the arguments to the original __call (of the dynamic 
+	 * event being unspecified in TCallChain) and funnels into the method {@link call}, 
+	 * so the next dynamic event handler can be called.
+	 * If the original method call has these parameters
+	 * <code>
+	 * $originalobject->dyExampleMethod('param1', 'param2', 'param3')
+	 * </code>
+	 * and within the chained dynamic events, this can be called
+	 * <code>
+	 * class DyBehavior extends TBehavior {
+	 * public function dyExampleMethod($param1, $param2, $param3, $callchain)
+	 * $callchain->dyExampleMethod($param1, $param2, $param3)
+	 * }
+	 * {
+	 * </code>
+	 * to call the next event in the chain.
+	 * @param string method name of the unspecified object method
+	 * @param array arguments to the unspecified object method
+	 */
+	public function __dycall($method,$args)
+	{
+		if($this->_method==$method)
+			return call_user_func_array(array($this,'call'),$args);
+		return null;
+	}
+}
\ No newline at end of file
diff --git a/framework/Util/TClassBehavior.php b/framework/Util/TClassBehavior.php
new file mode 100644
index 00000000..807549b7
--- /dev/null
+++ b/framework/Util/TClassBehavior.php
@@ -0,0 +1,36 @@
+<?php
+/**
+ * TClassBehavior class file.
+ *
+ * @author Brad Anderson <javalizard@gmail.com>
+ * @link http://www.pradosoft.com/
+ * @copyright Copyright &copy; 2008-2011 Pradosoft
+ * @license http://www.pradosoft.com/license/
+ */
+
+/**
+ * TClassBehavior is a convenient base class for whole class behaviors.
+ * @author Brad Anderson <javalizard@gmail.com>
+ * @version $Id: TClassBehavior.php 564 2009-01-21 22:07:10Z javalizard $
+ * @package system.base
+ * @since 3.1.8
+ */
+class TClassBehavior extends TComponent implements IClassBehavior
+{
+
+	/**
+	 * Attaches the behavior object to the component.
+	 * @param TComponent the component that this behavior is to be attached to.
+	 */
+	public function attach($component)
+	{
+	}
+	
+	/**
+	 * Detaches the behavior object from the component.
+	 * @param TComponent the component that this behavior is to be detached from.
+	 */
+	public function detach($component)
+	{
+	}
+}
\ No newline at end of file