org.apache.tapestry5.corelib.components

## Class Zone

- java.lang.Object
- - org.apache.tapestry5.corelib.components.Zone

- All Implemented Interfaces:
    ClientBodyElement, ClientElement

      @SupportsInformalParameters
       @Import(module="t5/core/zone")
      public class Zone
      extends Object
      implements ClientBodyElement

  A Zone is portion of the output page designed for easy dynamic updating via Ajax or other client-side effects. A Zone renders out as a <div> element (or whatever is specified in the template) and may have content initially, or may only get its content as a result of client side activity. When a user clicks an `ActionLink` whose zone parameter is set triggers a series of client-side behaviors, and an Ajax request to the server. The server side event handler can return a `Block` or a component to render as the new content on the client side. Often, re-rendering the Zone's body is useful. Multiple client-side zones may be updated via the `AjaxResponseRenderer` service. You will often want to specify the id parameter of the Zone, in addition to its Tapestry component id; this "locks down" the client-side id, so the same value is used even in later partial renders of the page (essential if the Zone is nested inside another Zone). When you specify the client-side id, it is used exactly as provided (meaning that you are responsible for ensuring that there will not be an id conflict even in the face of multiple partial renders of the page). Failure to provide an explicit id results in a new, and non-predictable, id being generated for each partial render, which will often result in client-side failures to locate the element to update when the Zone is triggered. In some cases, you may want to know (on the server side) the client id of the zone that was updated; this is passed as part of the Ajax request, as the `QueryParameterConstants.ZONE_ID` parameter. An example use of this would be to provide new content into a Zone that updates the same Zone, when the Zone's client-side id is dynamically allocated (rather than statically defined). In most cases, however, the programmer is responsible for assigning a specific client-side id, via the id parameter. A Zone starts and stops a `Heartbeat` when it renders (both normally, and when re-rendering). After the client-side content is updated, a client-side event is fired on the zone's element. The constant `core/events:zone.didUpdate` can be used to listen to the event.
  See Also:
    `AjaxFormLoop`, `FormFragment`

  Component Parameters
  Name | Type | Flags | Default | Default Prefix
  --- | --- | --- | --- | ---
  elementName | String | Required, Not Null |  | literal
  The element name to render for the zone; this defaults to the element actually used in the template, or "div" if no specific element was specified.
  id | String |  |  | literal
  If bound, then the id attribute of the rendered element will be this exact value. If not bound, then a unique id is generated for the element.
  show | String |  |  | literal
  Name of a function on the client-side Tapestry.ElementEffect object that is invoked to make the Zone's <div> visible before being updated. If not specified, then the basic "show" method is used.
  simpleIds | boolean | Since 5.4 |  | prop
  if set to true, then Ajax updates related to this Zone will, when rending, use simple IDs (not namespaced ids). This is useful when the Zone contains a simple Form, as it (hopefully) ensures that the same ids used when initially rendering, and when processing the submission, are also used when re-rendering the Form (to present errors to the user). The default is false, maintaining the same behavior as in Tapestry 5.3 and earlier.
  update | String |  |  | literal
  Name of a function on the client-side Tapestry.ElementEffect object that is invoked after the Zone's content has been updated. If not specified, then the basic "highlight" method is used, which performs a classic "yellow fade" to indicate to the user that and update has taken place.
  visible | boolean |  |  | prop
  In prior releases, this parameter could be overridden to false to force the outer element of the rendered Zone to be non-visible. This behavior is no longer supported.

  ### Examples

    ### ZoneDemo.tml (partial)

        <t:zone t:id="counterZone" id="counterZone">
          <p>You have clicked the link <strong>${clickCount}</strong> times.</p>
        </t:zone>

        <p>
          <t:actionlink t:id="clicker" zone="counterZone">increment the count</t:actionlink>
        </p>

    It's pretty standard to bind the id parameter of a zone; the zone parameter of ActionLink and Form are theclient-side element id, not the component id. They are often, but not always, the same. Binding the id parameter ensures that a particular, fixed value is used.

    Binding the zone parameter of the ActionLink, EventLink or Form (the "trigger" component) is what triggers the partial-render and update logic.

    ### ZoneDemo.java

        public class ZoneDemo
        {
          @Property
          @Persist
          private int clickCount;

          @InjectComponent
          private Zone counterZone;

          Object onActionFromClicker()
          {
            clickCount++;

            return counterZone.getBody();
          }
        }

    The event handler method for the clicker component increments the count, then returns the body of the zone. The body will be re-rendered (reflecting the new count), and sent to the client, which will update the zone in place, and trigger and animation (by default, a simple yellow fade) to draw the user's attention.

    Not shown here, but fully valid, is to include JavaScript libraries and generate initialization JavaScript. This fully consistent with ordinary full-page renders.

    ### Configuring the Zone Component in the AppModule class

    It is possible to configure the show and update parameters of the Zone component in the AppModule class of your application. All your Zone components will use this default configuration until you define a value for one of these parameters.

        public static void contributeApplicationDefaults(MappedConfiguration<String, String> configuration)
        {
          configuration.add(ComponentParameterConstants.ZONE_SHOW_METHOD, "show");

          configuration.add(ComponentParameterConstants.ZONE_SHOW_METHOD, "highlight");
        }

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Zone()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Block` | `getBody()` Returns the zone's body (the content enclosed by its start and end tags).
    `String` | `getClientId()` The client id of the Zone; this is set when the Zone renders and will either be the value bound to the id parameter, or an allocated unique id.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Zone

          public Zone()

  - ### Method Detail

    - #### getClientId

          public String getClientId()

      The client id of the Zone; this is set when the Zone renders and will either be the value bound to the id parameter, or an allocated unique id. When the id parameter is bound, this value is always accurate. When the id parameter is not bound, the clientId is set during the begin render phase and will be null or inaccurate before then.
      Specified by:
        `getClientId` in interface `ClientElement`
      Returns:
        client-side element id

    - #### getBody

          public Block getBody()

      Returns the zone's body (the content enclosed by its start and end tags). This is often used as part of an Ajax partial page render to update the client with a fresh render of the content inside the zone.
      Specified by:
        `getBody` in interface `ClientBodyElement`
      Returns:
        the zone's body as a Block

5.6.4 - Copyright © 2003-2021 The Apache Software Foundation.