Home » tapestry-src-5.0.19 » org.apache.tapestry5.corelib.components » [javadoc | source]

    1   // Copyright 2007, 2008 The Apache Software Foundation
    2   //
    3   // Licensed under the Apache License, Version 2.0 (the "License");
    4   // you may not use this file except in compliance with the License.
    5   // You may obtain a copy of the License at
    6   //
    7   //     http://www.apache.org/licenses/LICENSE-2.0
    8   //
    9   // Unless required by applicable law or agreed to in writing, software
   10   // distributed under the License is distributed on an "AS IS" BASIS,
   11   // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   12   // See the License for the specific language governing permissions and
   13   // limitations under the License.
   14   
   15   package org.apache.tapestry5.corelib.components;
   16   
   17   import org.apache.tapestry5;
   18   import org.apache.tapestry5.annotations.Environmental;
   19   import org.apache.tapestry5.annotations.Parameter;
   20   import org.apache.tapestry5.annotations.SupportsInformalParameters;
   21   import org.apache.tapestry5.dom.Element;
   22   import org.apache.tapestry5.internal.services.ClientBehaviorSupport;
   23   import org.apache.tapestry5.ioc.annotations.Inject;
   24   import org.apache.tapestry5.json.JSONObject;
   25   
   26   
   27   /**
   28    * A Zone is portion of the output page designed for easy dynamic updating via Ajax or other client-side effects.  A
   29    * Zone renders out as a <div> element and may have content initially, or may only get its content as a result of
   30    * client side activity.
   31    * <p/>
   32    * Often, Zones are initially invisible, in which case the visible parameter may be set to false (it defaults to true).
   33    * <p/>
   34    * When a user clicks an {@link org.apache.tapestry5.corelib.components.ActionLink} whose zone parameter is set, the
   35    * corresponding client-side Tapestry.Zone object is located. It will update the content of the Zone's &lt;div&gt; and
   36    * then invoke either a show method (if the div is not visible) or an update method (if the div is visible).  The show
   37    * and update parameters are the <em>names</em> of functions attached to the Tapestry.ElementEffect object.    Likewise,
   38    * a {@link org.apache.tapestry5.corelib.components.Form} component may also trigger an update of a client-side Zone.
   39    * <p/>
   40    * Renders informal parameters, adding CSS class "t-zone" and possibly, "t-invisible".
   41    * <p/>
   42    * You will often want to specify the id parameter of the Zone, in addition to it's Tapestry component id; this "locks
   43    * down" the client-side id, so the same value is used even in later partial renders of the page (essential if the Zone
   44    * is nested inside another Zone).  When you specify the client-side id, it is used exactly as provided (meaning that
   45    * you are responsible for ensuring that there will not be an id conflict even in the face of multiple partial renders
   46    * of the page). Failure to provide an explicit id results in a new, and non-predictable, id being generated for each
   47    * partial render, which will often result in client-side failures to locate the element to update when the Zone is
   48    * triggered.
   49    */
   50   @SupportsInformalParameters
   51   public class Zone implements ClientElement
   52   {
   53       /**
   54        * Name of a function on the client-side Tapestry.ElementEffect object that is invoked to make the Zone's
   55        * &lt;div&gt; visible before being updated.  If not specified, then the basic "show" method is used.
   56        */
   57       @Parameter(defaultPrefix = BindingConstants.LITERAL)
   58       private String show;
   59   
   60       /**
   61        * Name of a function on the client-side Tapestry.ElementEffect object that is invoked after the Zone's content has
   62        * been updated. If not specified, then the basic "highlight" method is used, which performs a classic "yellow fade"
   63        * to indicate to the user that and update has taken place.
   64        */
   65       @Parameter(defaultPrefix = BindingConstants.LITERAL)
   66       private String update;
   67   
   68       /**
   69        * If bound, then the id attribute of the rendered element will be this exact value. If not bound, then a unique id
   70        * is generated for the element.
   71        */
   72       @Parameter(name = "id", defaultPrefix = BindingConstants.LITERAL)
   73       private String clientId;
   74   
   75       @Environmental
   76       private RenderSupport renderSupport;
   77   
   78       @Environmental
   79       private ClientBehaviorSupport clientBehaviorSupport;
   80   
   81       /**
   82        * If true (the default) then the zone will render normally.  If false, then the "t-invisible" CSS class is added,
   83        * which will make the zone initially invisible.
   84        */
   85       @Parameter
   86       private boolean visible = true;
   87   
   88       @Inject
   89       private ComponentResources resources;
   90   
   91       void beginRender(MarkupWriter writer)
   92       {
   93           if (!resources.isBound("id"))
   94               clientId = renderSupport.allocateClientId(resources);
   95   
   96           Element e = writer.element("div", "id", clientId);
   97   
   98           resources.renderInformalParameters(writer);
   99   
  100           e.addClassName("t-zone");
  101   
  102           if (!visible) e.addClassName("t-invisible");
  103   
  104           // And continue on to render the body
  105   
  106           JSONObject spec = new JSONObject();
  107           spec.put("div", clientId);
  108   
  109           clientBehaviorSupport.addZone(clientId, show, update);
  110       }
  111   
  112       void afterRender(MarkupWriter writer)
  113       {
  114           writer.end(); // div
  115       }
  116   
  117       public String getClientId()
  118       {
  119           return clientId;
  120       }
  121   
  122       /**
  123        * Returns the zone's body (the content enclosed by its start and end tags). This is often used as part of an Ajax
  124        * partial page render to update the client with a fresh render of the content inside the zone.
  125        *
  126        * @return the zone's body as a Block
  127        */
  128       public Block getBody()
  129       {
  130           return resources.getBody();
  131       }
  132   }

Home » tapestry-src-5.0.19 » org.apache.tapestry5.corelib.components » [javadoc | source]