Return-Path: 
 <cvs-return-17052-apmail-cocoon-cvs-archive=cocoon.apache.org@cocoon.apache.org>
Delivered-To: apmail-cocoon-cvs-archive@www.apache.org
Received: (qmail 79372 invoked from network); 12 Feb 2004 12:19:45 -0000
Received: from daedalus.apache.org (HELO mail.apache.org) (208.185.179.12)
  by minotaur-2.apache.org with SMTP; 12 Feb 2004 12:19:45 -0000
Received: (qmail 68183 invoked by uid 500); 12 Feb 2004 12:19:41 -0000
Delivered-To: apmail-cocoon-cvs-archive@cocoon.apache.org
Received: (qmail 67432 invoked by uid 500); 12 Feb 2004 12:19:35 -0000
Mailing-List: contact cvs-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
list-help: <mailto:cvs-help@cocoon.apache.org>
list-unsubscribe: <mailto:cvs-unsubscribe@cocoon.apache.org>
list-post: <mailto:cvs@cocoon.apache.org>
Delivered-To: mailing list cvs@cocoon.apache.org
Received: (qmail 67236 invoked by uid 500); 12 Feb 2004 12:19:34 -0000
Delivered-To: apmail-cocoon-2.1-cvs@apache.org
Received: (qmail 67227 invoked from network); 12 Feb 2004 12:19:34 -0000
Received: from unknown (HELO minotaur.apache.org) (209.237.227.194)
  by daedalus.apache.org with SMTP; 12 Feb 2004 12:19:34 -0000
Received: (qmail 79285 invoked by uid 1260); 12 Feb 2004 12:19:34 -0000
Date: 12 Feb 2004 12:19:34 -0000
Message-ID: <20040212121934.79284.qmail@minotaur.apache.org>
From: cziegeler@apache.org
To: cocoon-2.1-cvs@apache.org
Subject: cvs commit: cocoon-2.1/src/documentation/xdocs/developing/portal
 events.xml forms.xml
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N
X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N

cziegeler    2004/02/12 04:19:34

  Modified:    src/documentation/xdocs/developing/portal events.xml
                        forms.xml
  Log:
  Updating docs
  
  Revision  Changes    Path
  1.2       +133 -11   cocoon-2.1/src/documentation/xdocs/developing/portal/events.xml
  
  Index: events.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/developing/portal/events.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- events.xml	12 Feb 2004 09:26:46 -0000	1.1
  +++ events.xml	12 Feb 2004 12:19:34 -0000	1.2
  @@ -29,8 +29,8 @@
         of event. In addition each component can send out events.
       </p>
       <p>
  -      The processing of a portal request (a request send to the cocoon portal)
  -      is divided into two parts: event handling and rendering. In the first part
  +      The processing of a portal request (a request send to the Cocoon portal)
  +      is divided into two phases: event handling and rendering. In the first phase
         all events are processed. For example if the user clicks a link this
         triggers an event that is published. Any receiver of this event might
         in turn fire new events that are published as well.
  @@ -51,12 +51,22 @@
         to set.
       </p>
       <p>
  -      A component that processes this request is subscribed to this minimize event
  +      There are different types of events: a type for changing the window state,
  +      a type for removing a coplet, a type for links that are clicked by the user etc.
  +      Each event type is represented by a Java class (or interface).
  +    </p>
  +    <p>
  +      A component that processes for example the window state request is subscribed 
  +      to this minimize event (or: the corresponding class/interface)
         and when such an event is fired, it changes the window state of the
  -      layout object to minimize. Every data this component needs is stored in
  +      coplet to minimize. Every data this component needs is stored in
         the event. This is a very important detail: the event is not directly processed
         (in this case) by the object that is changed (the coplet) but by a central
  -      subscribed component that changes the coplet.
  +      subscribed component that changes the coplet. This is because of the
  +      publisher/subscribe mechanism used: many components in the portal can subscribe
  +      to the same event type if they are interested. So, each component that is
  +      interested in an event needs all information about this event. That's why
  +      all data is stored in the event itself.
       </p>
       <p>
         Let's have a look how such an event is created:
  @@ -75,8 +85,13 @@
         the information about what to change (size) and the new value.
       </p>
       <p>
  -      If you want to fire this event, you have to publish it. Therefore you
  -      need the event manager a central portal component. You can lookup this
  +      All events must implement the marker interface <em>Event</em>, so if
  +      a component is interested in all Events it could subscribe itself
  +      using this event type.
  +    </p>
  +    <p>
  +      If you want to fire an event, you have to publish it. Therefore you
  +      need the event manager, a central portal component. You can lookup this
         component, fire the event and release the manager again. If you fire
         the event, the event is directly published to all subscribed components.
       </p>
  @@ -93,7 +108,7 @@
         As noted above, the event will be directly fired. But usually in a portal
         application, events are not fired directly but are invoked by some user
         action. This means, the user clicks on a link in the browser, the
  -      request is targetted at Cocoon and the portal invokes the correct events.
  +      request is targetted at Cocoon and the portal invokes (fires) the correct events.
       </p>
       <p>
         For this, a link (or a form action) must know, which event it should
  @@ -105,7 +120,7 @@
         The part of the portal that generates the link, creates the event object
         with all necessary data, transforms this event into a usable URI and this
         URI is the target of the link. When the user clicks on this link, the portal
  -      transforms the URI into the Java event object and fires the event.
  +      transforms the URI back into the Java event object and fires the event.
       </p>
       <p>
         The transformation Event->URI->Event is done by another portal component,
  @@ -133,6 +148,12 @@
         transform the event into a URI using the service and then create the
         (html) link using the URI. Everything else is handled by the portal for you.
       </p>
  +    <p>
  +      In addition, you can transform several events into one single link. So
  +      you can create links, the user can click, that do several things at
  +      the same time (minimizing one coplet and maximizing another one etc.).
  +      The link service offers corresponding methods for this.
  +    </p>
     </s1>
     <s1 title="Changing the State of a Coplet">
       <p>
  @@ -162,6 +183,7 @@
         It is of course possible that you write your own events for 
         changing the state of a coplet. But in this case make sure that
         your own event implements the interface <em>CopletInstanceEvent</em>.
  +      This helps the portal engine in tracking if a coplet has been changed.
       </p>
     </s1>
     <s1 title="Subscribing to Events">
  @@ -198,13 +220,13 @@
       <p>
         For example one central component in the portal subscribes for
         all events dealing with coplets, so it returns <em>CopletInstanceEvent</em>
  -      as the class in getEventType().
  +      as the class (interface) in getEventType().
       </p>
     </s1>
     <s1 title="Inter Coplet Communication">
       <p>
         A very interesting feature of the portal is inter-coplet communication.
  -      The sample portal already has a simple sample where the name of an
  +      The demo portal already has a simple sample where the name of an
         image selected in an image gallery is transfered to a different coplet.
       </p>
       <p>
  @@ -225,6 +247,106 @@
         and push the entered city information to a weather coplet and a hotel guide
         coplet. So, these two coplets display the information about the selected
         city.
  +    </p>
  +  </s1>
  +  <s1 title="The Coplet Transformer">
  +    <p>
  +      Apart from the possibility to create events from within your Java code,
  +      it's also possible to create events from within a pipeline by using
  +      for example the coplet transformer. It listens for elements with the
  +      namespace "http://apache.org/cocoon/portal/coplet/1.0".
  +    </p>
  +    <s2 title="The coplet element">
  +      <p>
  +        The coplet element has nothing to do with events :) It can be used
  +        to include information about the current coplet in the SAX stream:
  +      </p>
  +      <source>
  +<![CDATA[...
  +  <coplet:coplet select="attributes/name"/>
  +...]]>
  +      </source>
  +      <p>
  +        The coplet element can only be used inside a coplet pipeline, but
  +        not in the main portal pipeline. The select attribute defines an
  +        JXPath expression that is used to fetch the value that is included
  +        in the stream.
  +      </p>
  +    </s2>
  +    <s2 title="The link element">
  +      <p>
  +        The link element creates a link that will trigger an event if the 
  +        user clicks this link:
  +      </p>
  +      <source>
  +<![CDATA[...
  +  <coplet:link coplet="COPLET_ID" path="JXPATH" value="TO_SET"/>
  +  <coplet:link layout="LAYOUT_ID" path="JXPATH" value="TO_SET"/>
  +...]]>
  +      </source>
  +      <p>
  +        This element generates an HTML link which will eiter trigger an
  +        event to change a coplet instance data or a layout based on
  +        the JXPath and the value provided.
  +      </p>
  +    </s2>
  +  </s1>
  +  <s1 title="Configuring Subscribers">
  +    <p>
  +      In the previous chapters we saw one possibility to subscribe: dynamically
  +      in some Java code. This requires that - of course - this code is executed
  +      at some point of time. This is a solution for dynamic subscribers, which
  +      means a subscriber that is only "available" if a specific feature of 
  +      the portal is used. If the feature is available, the "feature" subscribes
  +      itself (or another component).
  +    </p>
  +    <p>
  +      However, this adds an exta burdon to the development of own events and
  +      their subscribers. Therefore it is possible to configure subscribers
  +      in the cocoon.xconf. These subscribers are instantiated by the
  +      portal engine on startup of Cocoon and subscribed by the portal
  +      engine.
  +    </p>
  +    <p>
  +      You have two possibilites, you can either subscribe Avalon components or
  +      classes. In the first case, you configure the role of the component.
  +      Then the portal engine looks up this component and subscribes it.
  +    </p>
  +    <p>
  +      If you configure a class, the portal engine creates an instance of this
  +      class using the no-argument constructor and subscribes this instance.
  +      For convenience, this instance can implement the Avalon lifecycle
  +      interface like LogEnabled or Serviceable.
  +    </p>
  +    <p>
  +      The configuration takes place in the cocoon.xconf as a configuration for
  +      the event manager:
  +    </p>
  +    <source>
  +<![CDATA[...
  + <component class="org.apache.cocoon.portal.event.impl.DefaultEventManager" 
  +            logger="portal" 
  +            role="org.apache.cocoon.portal.event.EventManager">
  +    ...
  +    <!-- add a new instance of each class as a subscriber: -->
  +    <subscriber-classes>
  +        <class name="org.apache.cocoon.portal.event.subscriber.impl.DefaultJXPathEventSubscriber"/>
  +    </subscriber-classes>
  +    <!-- add each component as a subscriber (the component should be thread safe): -->
  +    <subscriber-roles>
  +        <role name="org.apache.cocoon.portal.samples.location.LocationEventSubscriber"/>
  +    </subscriber-roles>
  + </component>
  +...]]>
  +    </source>
  +    <p>
  +      In the sample configuration above, one class is subscribed (the
  +      <em>DefaultJXPathEventSubscriber</em>) and one Avalon component
  +      (the <em>LocationEventSubscriber</em>).
  +    </p>
  +    <p>
  +      So, if you write your own events and your own subscribers you can either dynamically
  +      add them during execution or statically add them by configuration as shown above.
       </p>
     </s1>
     <s1 title="Further Information">
  
  
  
  1.2       +18 -6     cocoon-2.1/src/documentation/xdocs/developing/portal/forms.xml
  
  Index: forms.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/developing/portal/forms.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- forms.xml	12 Feb 2004 09:26:46 -0000	1.1
  +++ forms.xml	12 Feb 2004 12:19:34 -0000	1.2
  @@ -42,19 +42,31 @@
         <coplet-base-data>CachingURICoplet</coplet-base-data>
         <attribute>
         	<name>buffer</name>
  -      	<value xsi:type="java:java.lang.Boolean" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">true</value>
  +      	<value xsi:type="java:java.lang.Boolean" 
  +               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  +            true
  +        </value>
         </attribute>
         <attribute>
         	<name>handleParameters</name>
  -      	<value xsi:type="java:java.lang.Boolean" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">true</value>
  +      	<value xsi:type="java:java.lang.Boolean" 
  +               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  +             true
  +        </value>
         </attribute>
         <attribute>
         	<name>uri</name>
  -      	<value xsi:type="java:java.lang.String" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">cocoon:/coplets/html/application</value>
  +      	<value xsi:type="java:java.lang.String" 
  +               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  +            cocoon:/coplets/html/application
  +        </value>
         </attribute>
         <attribute>
         	<name>temporary:application-uri</name>
  -      	<value xsi:type="java:java.lang.String" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">cocoon://samples/flow/jxcalc/</value>
  +      	<value xsi:type="java:java.lang.String" 
  +               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  +            cocoon://samples/flow/jxcalc/
  +        </value>
         </attribute>
      </coplet-data>
   ...]]>
  @@ -96,7 +108,7 @@
     <s1 title="Building forms">
       <p>
         In this chapter we demonstrate using a sample how to build forms that can
  -      be used with the portal. We will use Cocoon flow to define the logic for
  +      be used within the portal. We will use Cocoon flow to define the logic for
         the form, but for your own form you can of course use a different approach
         as well. If you want to have complex forms, you can also use Cocoon forms
         (Woody), but you have to be careful with correctly using JavaScript on
  @@ -194,7 +206,7 @@
           is not called.
         </p>
         <p>
  -        The portal caches the response of an application and severes the coplet out
  +        The portal caches the response of an application and serves the coplet out
           of the cache until an action for this coplet is triggered.
         </p>
       </s2>