Big quickstart doc overhaul, pt. 1

1 files changed, 207 insertions, 0 deletions

diff --git a/demos/quickstart/protected/pages/Fundamentals/Components2.page b/demos/quickstart/protected/pages/Fundamentals/Components2.page
new file mode 100644
index 00000000..7fc3e010
--- /dev/null
+++ b/demos/quickstart/protected/pages/Fundamentals/Components2.page
@@ -0,0 +1,207 @@
+<com:TContent ID="body" >
+<h1 id="701">Components: Part II</h1>
+<com:SinceVersion Version="3.2.3" />
+<h2 id="26001">Global events</h2>
+<p id="130001" class="block-content">
+With the addition of behaviors, a more expansive event model is needed.  There
+are two new event types (global and dynamic events) as well as a more comprehensive
+behavior model that includes class wide behaviors.
+</p>
+<p id="130002" class="block-content">
+A global event is defined by all events whose name starts with 'fx'.
+The event name is potentially a method name and is thus case-insensitive. All 'fx' events
+are valid as the whole 'fx' event/method space is global in nature. Any object may patch into
+any global event by defining that event as a method. Global events have priorities
+just like 'on' events; so as to be able to order the event execution. Due to the
+nature of all events which start with 'fx' being valid, in effect, every object
+has every 'fx' global event. It is simply an issue of tapping into the desired
+global event.
+</p>
+<p id="130003" class="block-content">
+A global event that starts with 'fx' can be called even if the object does not
+implement the method of the global event.  A call to a non-existing 'fx' method
+will, at minimal, function and return null.  If a method argument list has a first
+parameter, it will be returned instead of null.  This allows filtering and chaining.
+'fx' methods do not automatically install and uninstall. To install and uninstall an
+object's global event listeners, call the object's <tt>listen</tt> and
+<tt>unlisten</tt> methods, respectively.  An object may auto-install its global event
+during <tt>__construct</tt> by overriding <tt>getAutoGlobalListen</tt> and returning true.
+</p>
+<p id="130004" class="block-content">
+As of PHP version 5.3, nulled objects without code references will still continue to persist
+in the global event queue because <tt>__destruct</tt> is not automatically called.  In the common
+__destruct method, if an object is listening to global events, then <tt>unlisten</tt> is called.
+<tt>unlisten</tt> is required to be manually called before an object is
+left without references if it is currently listening to any global events. This includes
+class wide behaviors.
+</p>
+<p id="130005" class="block-content">
+An object that contains a method that starts with 'fx' will have those functions
+automatically receive those events of the same name after <tt>listen</tt> is called on the object.
+</p>
+<p id="130006" class="block-content">
+An object may listen to a global event without defining an 'fx' method of the same name by
+adding an object method to the global event list.  For example
+</p>
+<com:TTextHighlighter CssClass="source block-content">
+$component->fxGlobalCheck=$callback;  // or $component->OnClick->add($callback);
+$component->attachEventHandler('fxGlobalCheck',array($object, 'someMethod'));
+</com:TTextHighlighter>
+<h2 id="26002">Events between Objects and their behaviors, Dynamic Events</h2>
+<p id="130007" class="block-content">
+An intra-object/behavior event is defined by methods that start with 'dy'.  Just as with
+'fx' global events, every object has every dynamic event.  Any call to a method that
+starts with 'dy' will be handled, regardless of whether it is implemented.  These
+events are for communicating with attached behaviors.
+</p>
+<p id="130008" class="block-content">
+Dynamic events can be used in a variety of ways.  They can be used to tell behaviors
+when a non-behavior method is called.  Dynamic events could be used as data filters.
+They could also be used to specify when a piece of code is to be run, eg. should the
+loop process be performed on a particular piece of data.  In this way, some control
+is handed to the behaviors over the process and/or data.
+</p>
+<p id="130009" class="block-content">
+If there are no handlers for an 'fx' or 'dy' event, it will return the first
+parameter of the argument list.  If there are no arguments, these events
+will return null.  If there are handlers an 'fx' method will be called directly
+within the object.  Global 'fx' events are triggered by calling <tt>raiseEvent</tt>.
+For dynamic events where there are behaviors that respond to the dynamic events, a
+<tt>TCallChain</tt> is developed.  A call chain allows the behavior dynamic event
+implementations to call further implementing behaviors within a chain.
+</p>
+<p id="130010" class="block-content">
+If an object implements <tt>IDynamicMethods</tt>, all global and object dynamic
+events will be sent to <tt>__dycall</tt>.  In the case of global events, all
+global events will trigger this method.  In the case of behaviors, all undefined
+dynamic events  which are called will be passed through to this method.
+</p>
+<p id="130011" class="block-content">
+<h2 id="26003">Behaviors</h2>
+<p id="130012" class="block-content">
+There are two types of behaviors.  There are individual object behaviors and
+there are class wide behaviors.  Class behaviors depend upon object behaviors.
+</p>
+<p id="130013" class="block-content">
+When a new class implements <tt>IBehavior</tt> or <tt>IClassBehavior</tt> or
+extends <tt>TBehavior</tt> or <tt>TClassBehavior</tt>, it may be added to an
+object by calling the object's <tt>attachBehavior</tt>.  The behaviors associated
+name can then be used to <tt>enableBehavior</tt> or <tt>disableBehavior</tt>
+the specific behavior.
+</p>
+<p id="130014" class="block-content">
+All behaviors may be turned on and off via <tt>enableBehaviors</tt> and
+<tt>disableBehaviors</tt>, respectively.  To check if behaviors are on or off
+a call to <tt>getBehaviorsEnabled</tt> will provide the variable.
+</p>
+<p id="130015" class="block-content">
+Attaching and detaching whole sets of behaviors is done using
+<tt>attachBehaviors</tt> and <tt>detachBehaviors</tt>.  <tt>clearBehaviors</tt>
+removes all of an object's behaviors.
+</p>
+<p id="130016" class="block-content">
+<tt>asa</tt> returns a behavior of a specific name.  <tt>isa</tt> is the
+behavior inclusive function that acts as the PHP operator <tt>instanceof</tt>.
+A behavior could provide the functionality of a specific class thus causing
+the host object to act similarly to a completely different class.  A behavior
+would then implement <tt>IInstanceCheck</tt> to provide the identity of the
+different class.
+</p>
+<p id="130017" class="block-content">
+Class behaviors are similar to object behaviors except that the class behavior
+is the implementation for all instances of the class.  A class behavior
+will have the object upon which is being called be prepended to the parameter
+list.  This way the object is known across the class behavior implementation.
+</p>
+<p id="130018" class="block-content">
+Class behaviors are attached using <tt>attachClassBehavior</tt> and detached
+using <tt>detachClassBehavior</tt>.  Class behaviors are important in that
+they will be applied to all new instances of a particular class.  In this way
+class behaviors become default behaviors to a new instances of a class in
+<tt>__construct</tt>.  Detaching a class behavior will remove the behavior
+from the default set of behaviors created for an object when the object
+is instanced.
+</p>
+<p id="130019" class="block-content">
+Class behaviors are also added to all existing instances via the global 'fx'
+event mechanism.  When a new class behavior is added, the event
+<tt>fxAttachClassBehavior</tt> is raised and all existing instances that are
+listening to this global event (primarily after <tt>listen</tt> is called)
+will have this new behavior attached.  A similar process is used when
+detaching class behaviors.  Any objects listening to the global 'fx' event
+<tt>fxDetachClassBehavior</tt> will have a class behavior removed.
+</p>
+<h2 id="26004">Dynamic Intra-Object Events</h2>
+<p id="130020" class="block-content">
+Dynamic events start with 'dy'.  This mechanism is used to allow objects
+to communicate with their behaviors directly.  The entire 'dy' event space
+is valid.  All attached, enabled behaviors that implement a dynamic event
+are called when the host object calls the dynamic event.  If there is no
+implementation or behaviors, this returns null when no parameters are
+supplied and will return the first parameter when there is at least one
+parameter in the dynamic event.
+</p>
+<com:TTextHighlighter CssClass="source block-content">
+	null == $this->dyBehaviorEvent();
+	5 == $this->dyBehaviorEvent(5); //when no behaviors implement this dynamic event
+</com:TTextHighlighter>
+<p id="130021" class="block-content">
+Dynamic events can be chained together within behaviors to allow for data
+filtering. Dynamic events are implemented within behaviors by defining the
+event as a method.
+</p>
+<com:TTextHighlighter CssClass="source block-content">
+class TObjectBehavior extends TBehavior {
+    public function dyBehaviorEvent($param1, $callchain) {
+			//Do something, eg:  $param1 += 13;
+			return $callchain->dyBehaviorEvent($param1);
+    }
+}
+</com:TTextHighlighter>
+<p id="130022" class="block-content">
+This implementation of a behavior and dynamic event will flow through to the
+next behavior implementing the dynamic event.  The first parameter is always
+return when it is supplied.  Otherwise a dynamic event returns null.
+</p>
+<p id="130023" class="block-content">
+In the case of a class behavior, the object is also prepended to the dynamic
+event.
+</p>
+<com:TTextHighlighter CssClass="source block-content">
+class TObjectClassBehavior extends TClassBehavior {
+    public function dyBehaviorEvent($hostobject, $param1, $callchain) {
+			//Do something, eg:  $param1 += $hostobject->getNumber();
+			return $callchain->dyBehaviorEvent($param1);
+    }
+}
+</com:TTextHighlighter>
+</p>
+<p id="130024" class="block-content">
+When calling a dynamic event, only the parameters are passed.  The host object
+and the call chain are built into the framework.
+</p>
+
+<h2 id="26005">Global Event and Dynamic event catching</h2>
+
+<p id="130025" class="block-content">
+Given that all global 'fx' events and dynamic 'dy' events are valid and
+operational, there is a mechanism for catching events called that are not
+implemented (similar to the built-in PHP method <tt>__call</tt>).  When
+a dynamic or global event is called but a behavior does not implement it,
+yet desires to know when an undefined dynamic event is run, the behavior
+implements the interface <tt>IDynamicMethods</tt> and method <tt>__dycall</tt>.
+</p>
+<p id="130026" class="block-content">
+In the case of dynamic events, <tt>__dycall</tt> is supplied with the method
+name and its parameters.  When a global event is raised, via <tt>raiseEvent</tt>,
+the method is the event name and the parameters are supplied.
+</p>
+<p id="130027" class="block-content">
+When implemented, this catch-all mechanism is called for event global event event
+when implemented outside of a behavior.  Within a behavior, it will also be called
+when the object to which the behavior is attached calls any unimplemented dynamic
+event.  This is the fall-back mechanism for informing a class and/or behavior
+of when an global and/or undefined dynamic event is executed.
+</p>
+
+</com:TContent>