home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-cocoon-addon-1.4.9-installer.exe / eventhandling.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  9.8 KB  |  247 lines
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!--
  3.   Copyright 1999-2004 The Apache Software Foundation
  4.  
  5.   Licensed under the Apache License, Version 2.0 (the "License");
  6.   you may not use this file except in compliance with the License.
  7.   You may obtain a copy of the License at
  8.  
  9.       http://www.apache.org/licenses/LICENSE-2.0
  10.  
  11.   Unless required by applicable law or agreed to in writing, software
  12.   distributed under the License is distributed on an "AS IS" BASIS,
  13.   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.   See the License for the specific language governing permissions and
  15.   limitations under the License.
  16. -->
  17. <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "document-v10.dtd">
  18.  
  19. <document>
  20.   <header>
  21.     <title>Cocoon Forms: Event Handling</title>
  22.     <authors>
  23.       <person name="The Apache Cocoon Team" email="dev@cocoon.apache.org"/>
  24.     </authors>
  25.   </header>
  26.   <body>
  27.     <s1 title="Intro">
  28.       <p>Some types of widgets can emit events. For example, the
  29.       action widget produces ActionEvents and the field widget
  30.       produces ValueChangedEvents. Next to these events, there are
  31.       also ProcessingPhaseEvents, fired in between the various
  32.       phases of the processing of a request.</p>
  33.  
  34.       <p>Handling events can be done in three ways:</p>
  35.  
  36.       <ul>
  37.         <li>by defining event listeners in the form definition (as child
  38.         of wd:on-action for the action widget, or wd:on-value-changed for
  39.         the field widget, ...).</li>
  40.         <li>by adding event listeners dynamically on widget instances.</li>
  41.         <li>by registering a <code>FormHandler</code> on the
  42.         Form object. This FormHandler will receive all events from all widgets.</li>
  43.       </ul>
  44.     </s1>
  45.  
  46.     <s1 title="When are events processed? (Request processing phases)">
  47.       <p>To answer the question "When are events processed?", we have to
  48.       look a bit deeper into how a form request is handled. This is separated
  49.       in a couple of phases, more specifically the following ones:</p>
  50.  
  51.       <ul>
  52.         <li>Any outstanding events are broadcasted to the event listeners.<br/>
  53.         The reason this is done is because events might have been collected while
  54.         the form was loaded with values by the binding framework.</li>
  55.         <li>ProcessingPhaseListeners are informed that the <code>LOAD_MODEL</code> phase has ended.</li>
  56.         <li>All widgets in the widget tree read their value from the request.
  57.         If a widget decides it has to produce an event, it is added to a global
  58.         (i.e. form-level) list (but not yet executed).</li>
  59.         <li>Once all widgets had the opportunity to read their value from the request,
  60.         the events are broadcasted to the event listeners. This assures that event
  61.         listeners have access to the values of all widgets in the tree.</li>
  62.         <li>ProcessingPhaseListeners are informed that the <code>READ_FROM_REQUEST</code> phase has ended.</li>
  63.         <li>It is possible that processing ends now. This usually happens when
  64.         an action widget has caused an event.</li>
  65.         <li>All widgets in the widget tree validate themselves.</li>
  66.         <li>ProcessingPhaseListeners are informed that the <code>VALIDATE</code> phase has ended.</li>
  67.       </ul>
  68.     </s1>
  69.  
  70.     <s1 title="Recursive event loops">
  71.       <p>Event listeners themselves might call methods on widgets which cause
  72.       new events to be generated. You have to be careful not to cause recursive
  73.       event loops by doing this.</p>
  74.  
  75.       <p>For example, calling setValue on a widget
  76.       in a ValueChangedEvent caused by that widget will schedule a new ValueChangedEvent,
  77.       which will then again cause the execution of the event listener
  78.       which will then again call setValue and thus again cause a new event
  79.       to be generated, and so on.</p>
  80.     </s1>
  81.  
  82.     <s1 title="Defining event handlers in the form definition">
  83.       <p>Event handlers can be specified as part of the form definition, as child
  84.       of the various wd:on-xxx elements, such as wd:on-action for the action widget.</p>
  85.  
  86.       <p>Event handlers can be written in either javascript or java.
  87.       The form definition syntax is as follows:</p>
  88.  
  89.       <source><![CDATA[<fd:on-xxxx>
  90.   <javascript>
  91.     ... some inline javascript code ...
  92.   </javascript>
  93.   <java class="..."/>
  94. </fd:on-xxxx>]]></source>
  95.  
  96.       <p>You can specify as many <code><javascript></code> and/or
  97.       <code><java></code> event listeners as you want.</p>
  98.  
  99.       <s2 title="Javascript event listeners">
  100.         <p>Objects available in the Javascript snippet:</p>
  101.         <ul>
  102.           <li><code>event</code>: a subclass of WidgetEvent. The reference documentation
  103.           of the individual widgets mentions which WidgetEvent subclass they provide
  104.           in their events. You can then check the javadoc for those classes to see
  105.           what they provide.</li>
  106.           <li><code>viewData</code>: any data that is normally passed from the flowlayer
  107.           to the view (pipeline). Exact contents depends on which flowscript API version you use.</li>
  108.           <li>if the form processing was started from a flowscript, then everything
  109.           available from the scope of that flowscript, such as global variables,
  110.           functions and the <code>cocoon</code> object (see also
  111.           <link href="../flow/api.html">Flow Object Model</link>).</li>
  112.         </ul>
  113.  
  114.         <note>It does not make sense to create continuations from the Javascript event
  115.         handler. In other words, do not call <code>cocoon.sendPageAndWait</code> or <code>form.showForm</code>
  116.         from there.</note>
  117.       </s2>
  118.  
  119.       <s2 title="Java event listeners">
  120.         <p>The Java class specified in the class attribute on the java element should
  121.         implement a certain event listener interface. Which interface depends on the type of widget.
  122.         See the documentation of the individual widgets for more information.</p>
  123.       </s2>
  124.     </s1>
  125.  
  126.     <s1 title="Adding event listeners on widget instances">
  127.       <p>Adding event listeners on widgets instances allows to dynamically
  128.       add event listeners at runtime. This is often convenient: as you
  129.       control the creation of the event listeners yourself, you can pass
  130.       them any information you need.</p>
  131.  
  132.       <p>To add an event listener on a widget instance, simply call
  133.       the appropriate method on the widget (e.g. addValueChangedListener)
  134.       with an appropriate listener object as argument. You can of course also remove
  135.       the event listener afterwards (e.g. removeValueChangedListener).</p>
  136.  
  137.       <p>When using flowscript, it is possible to simply assign Javascript
  138.       functions as event listeners. This is a very easy and powerful way
  139.       to create event listeners. See the <link href="api_javascript.html">flowscript
  140.       API section</link> for more information.</p>
  141.     </s1>
  142.  
  143.     <s1 title="Handling events using the FormHandler">
  144.       <p>To handle events using a FormHandler, write a class implementing the following interface:</p>
  145.  
  146.       <source><![CDATA[org.apache.cocoon.woody.event.FormHandler]]></source>
  147.  
  148.       <p>Alternatively you can extend from the following abstract class:</p>
  149.  
  150.       <source><![CDATA[org.apache.cocoon.woody.event.AbstractFormHandler]]></source>
  151.  
  152.       <p>which will split ActionEvents and ValueChangedEvents to two different methods.
  153.       See the javadocs of these interfaces and classes for more details.</p>
  154.  
  155.       <p>Once you created the FormHandler, register it on a form instance by calling
  156.       the method <code>setFormHandler(FormHandler formHandler)</code> on it.</p>
  157.     </s1>
  158.  
  159.     <s1 title="Overview of supported events">
  160.       <p>The figure below shows the 3 types of events we currently support, each
  161.       extending from the common WidgetEvent class.</p>
  162.  
  163.       <figure src="images/forms_event_types.png" alt="Overview of event types"/>
  164.  
  165.       <p>The full types of the event listeners and event objects are:</p>
  166.  
  167.       <source><![CDATA[org.apache.cocoon.forms.event.ValueChangedListener
  168. org.apache.cocoon.forms.event.ValueChangedEvent
  169.  
  170. org.apache.cocoon.forms.event.ActionListener
  171. org.apache.cocoon.forms.event.ActionEvent
  172.  
  173. org.apache.cocoon.forms.event.ProcessingPhaseListener
  174. org.apache.cocoon.forms.event.ProcessingPhaseEvent]]></source>
  175.  
  176.       <p>The table below gives an overview of what events are supported on what widgets.</p>
  177.       <table>
  178.         <tr>
  179.           <th>Widget</th>
  180.           <th>Supports ValueChangedEvents</th>
  181.           <th>Supports ActionEvents</th>
  182.         </tr>
  183.         <tr>
  184.           <td>field</td>
  185.           <td><img src="images/yes_mark.png" alt="yes"/></td>
  186.           <td></td>
  187.         </tr>
  188.         <tr>
  189.           <td>multivaluefield</td>
  190.           <td>TODO</td>
  191.           <td></td>
  192.         </tr>
  193.         <tr>
  194.           <td>booleanfield</td>
  195.           <td><img src="images/yes_mark.png" alt="yes"/></td>
  196.           <td></td>
  197.         </tr>
  198.         <tr>
  199.           <td>repeater</td>
  200.           <td></td>
  201.           <td></td>
  202.         </tr>
  203.         <tr>
  204.           <td>output</td>
  205.           <td></td>
  206.           <td></td>
  207.         </tr>
  208.         <tr>
  209.           <td>submit</td>
  210.           <td></td>
  211.           <td><img src="images/yes_mark.png" alt="yes"/></td>
  212.         </tr>
  213.         <tr>
  214.           <td>action</td>
  215.           <td></td>
  216.           <td><img src="images/yes_mark.png" alt="yes"/></td>
  217.         </tr>
  218.         <tr>
  219.           <td>repeater-action</td>
  220.           <td></td>
  221.           <td><img src="images/yes_mark.png" alt="yes"/></td>
  222.         </tr>
  223.         <tr>
  224.           <td>row-action</td>
  225.           <td></td>
  226.           <td><img src="images/yes_mark.png" alt="yes"/></td>
  227.         </tr>
  228.         <tr>
  229.           <td>aggregatefield</td>
  230.           <td>TODO</td>
  231.           <td></td>
  232.         </tr>
  233.         <tr>
  234.           <td>upload</td>
  235.           <td></td>
  236.           <td></td>
  237.         </tr>
  238.         <tr>
  239.           <td>messages</td>
  240.           <td></td>
  241.           <td></td>
  242.         </tr>
  243.       </table>
  244.     </s1>
  245.   </body>
  246. </document>
  247.