Author: hlship
Date: Wed Nov 28 12:03:40 2007
New Revision: 599123
URL: http://svn.apache.org/viewvc?rev=599123&view=rev
Log:
Improve documentation for the Zone component, add suport for the show and
update parameters to Zone, add a limited amount of integration testing for Zone
and Autocomplete (limited by Selenium).
Added:
tapestry/tapestry5/trunk/tapestry-core/src/test/java/org/apache/tapestry/internal/services/ZoneSetupImplTest.java
- copied unchanged from r598842,
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/internal/services/ZoneSetupImplTest.java
Removed:
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/internal/services/ZoneSetupImplTest.java
Modified:
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Zone.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/services/Request.java
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/tapestry.js
tapestry/tapestry5/trunk/tapestry-core/src/site/apt/guide/ajax.apt
tapestry/tapestry5/trunk/tapestry-core/src/test/app1/Start.tml
tapestry/tapestry5/trunk/tapestry-core/src/test/java/org/apache/tapestry/integration/IntegrationTests.java
Modified:
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Zone.java
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Zone.java?rev=599123&r1=599122&r2=599123&view=diff
==============================================================================
---
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Zone.java
(original)
+++
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Zone.java
Wed Nov 28 12:03:40 2007
@@ -29,15 +29,39 @@
/**
* 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 a may
have content initially,
+ * client-side effects. A Zone renders out as a <div> element and may
have content initially,
* or may only get its content as a result of client side activity.
* <p/>
+ * Often, Zone's are initially invisible, in which case the visible parameter
may be set to false (it defaults to false).
+ * <p/>
+ * <p/>
+ * When a user clicks an [EMAIL PROTECTED]
org.apache.tapestry.corelib.components.ActionLink} whose zone parameter is set,
+ * the corresponding client-side Tapestry.Zone object is located. It will
update the content of the Zone's <div> and
+ * then invoke either a show method (if the div is not visible) or an update
method (if the div is visible). The show and update
+ * parameters are the <em>names</em> of functions attached to the
Tapestry.ZoneEffects object.
* <p/>
* Renders informal parameters, adding CSS class "t-zone" and possibly,
"t-invisible".
*/
@SupportsInformalParameters
public class Zone implements ClientElement
{
+ /**
+ * Name of a function on the client-side Tapestry.ZoneEffects object that
is invoked to
+ * make the Zone's <div> visible before being updated. If not
specified, then
+ * the basic "show" method is used.
+ */
+ @Parameter
+ private String _show;
+
+ /**
+ * Name of a function on the client-side Tapestry.ZoneEffects 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.
+ */
+ @Parameter
+ private String _update;
+
private String _clientId;
@Environmental
@@ -73,7 +97,7 @@
JSONObject spec = new JSONObject();
spec.put("div", _clientId);
- _zoneSetup.addZone(_clientId, null, null);
+ _zoneSetup.addZone(_clientId, _show, _update);
}
void afterRender(MarkupWriter writer)
Modified:
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/services/Request.java
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/services/Request.java?rev=599123&r1=599122&r2=599123&view=diff
==============================================================================
---
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/services/Request.java
(original)
+++
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/services/Request.java
Wed Nov 28 12:03:40 2007
@@ -107,7 +107,7 @@
/**
* Returns true if the request originated on the client using
XmlHttpRequest (the core of any Ajax behavior).
* Ajax action requests may behave quite differently than ordinary,
page-based requests. This implementation
- * currently depends on the client side setting a header:
<strong>X-Requested-With=XmlHttpRequest</strong> (this is what
+ * currently depends on the client side setting a header:
<strong>X-Requested-With=XMLHttpRequest</strong> (this is what
* Prototype does).
*
* @return true if the request has an XmlHttpRequest origin
Modified:
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/tapestry.js
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/tapestry.js?rev=599123&r1=599122&r2=599123&view=diff
==============================================================================
---
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/tapestry.js
(original)
+++
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/tapestry.js
Wed Nov 28 12:03:40 2007
@@ -172,7 +172,7 @@
new Tapestry.Zone(spec);
});
- // Each spec is a pair of values suitable for the linkZone method
+ // Each spec is a pair of argument values suitable for the linkZone
method
$A(linkSpecs).each(function (spec)
{
@@ -436,6 +436,16 @@
// Link the div back to this zone.
this.div.zone = this;
+
+ // Look inside the Zone div for the another div with the CSS class
"t-zone-update".
+ // If present, then this is the elements whose content will be
changed, rather
+ // then the entire Zone div. This allows a Zone div to contain
"wrapper" markup
+ // (borders and such). Typically, such a Zone div will initially be
invisible.
+ // The show and update functions apply to the Zone div, not the update
div.
+
+ var updates = div.select("DIV.t-zone-update");
+
+ this.updatediv = updates.length == 0 ? this.div : updates[0];
},
// Updates the content of the div controlled by this Zone, then
@@ -443,13 +453,16 @@
show: function(content)
{
- this.div.innerHTML = content;
+ this.updatediv.innerHTML = content;
var func = this.div.visible() ? this.updateFunc : this.showFunc;
func.call(this, this.div);
}
};
+
+// Find all elements marked with the "t-invisible" CSS class and hide() them,
so that
+// Prototype's visible() method operates correctly.
Event.observe(window, 'load', function()
{
Modified: tapestry/tapestry5/trunk/tapestry-core/src/site/apt/guide/ajax.apt
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/site/apt/guide/ajax.apt?rev=599123&r1=599122&r2=599123&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/site/apt/guide/ajax.apt
(original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/site/apt/guide/ajax.apt Wed Nov
28 12:03:40 2007
@@ -192,7 +192,88 @@
* Zone
- Details coming soon.
+ Initial support for Zones is now in place. Zones are Tapestry's approach to
performing partial updates to
+ the client side. A Zone component renders as a \<div\> element with the
"t-zone" CSS class. It also
+ adds some JavaScript to the page to "wire up" a Tapestry.Zone object to
control updating
+ the \<div\> element.
+
+ A Zone can be updated via an ActionLink component. ActionLink supports a
zone parameter, which is the id
+ of the Zone's \<div\>. Clicking such a link will invoke an event handler
method on the server as normal ...
+ except that the return value of the event handler method is used to send a
<partial page response>
+ to the client, and the content of that response is used to update the
Zone's \<div\> in place.
+
+** Zone div vs. update div
+
+ In many situations, a Zone is a kind of "wrapper" or "container" for dynamic
content, that provides
+ a look and feel ... a bit of wrapping markup to create a border. In that
situtation,
+ the Zone \<div\> may contain an update \<div\>.
+
+ An update \<div\> is a \<div\> with the CSS class "t-zone-update", <inside>
the Zone's \<div\>.
+
+ When an update occurs, the update \<div\>'s content will be changed, rather
than the entire Zone \<div\>.
+
+ The show and update functions apply to the Zone \<div\>.
+
+** Event Handler Return Types
+
+ In a traditional request, the return value of an event handler method is
used to determine
+ which page will render a <complete> response, and a <redirect> is sent to
the client to render the new page (as
+ a new request).
+
+ With a Zone update, the return value is used to render a <partial response>
within the <same request>.
+
+ This return value should be an injected component or block. The value will
be rendered, and that
+ markup will be used on the client side to update the Zone's \<div\>.
+
+** Graceful Degradation
+
+ Users who do not have JavaScript enabled may click ActionLinks that are
configured to update a Zone.
+
+ When that occurs, the request will still be sent to the server, but will be
handled as a <traditional> request.
+
+ To support graceful degradation, you should detect that case and return a
traditional response: a page, page name
+ or page class.
+
+ This is accomplished by injecting the
+ {{{../../apidocs/org/apache/tapestry/services/Request.html}Request}} object,
and invoking the isXHR() method.
+ This value will be true for Ajax requests, and false for traditional request.
+
+** Zone Functions
+
+ A Zone may be initially visible or invisible. When a Zone is updated, it is
made visible if not currently so.
+ This is accomplished via a function on the Tapestry.ZoneEffect client-side
object. By default, the show()
+ function is used for this purpose. The Zone's show parameter is the <name>
of a Tapestry.ZoneEffect function.
+
+ If a Zone is already visible, then a different function is used to highlight
the change. Here it is
+ the Zone's update parameter, and a default highlight() function, which
perfroms a yellow fade to highlight
+ that the content of the Zone has changed.
+
+
+** Zone Limitations
+
+ Unlike many other situations, Tapestry relies on you to specify useful and
unique ids to Zone components,
+ then reference those ids inside ActionLink components. Using Zone
components inside any kind of loop
+ may cause additional problems, as Tapestry will <uniqueify> the client id
you specify (appending an index number).
+
+ The show and update function names are converted to lower case; all the
methods of Tapestry.ZoneEffects should have
+ all lower-case names. Because client-side JavaScript is so fluid (new
methods may be added to
+ existing objects), Tapestry makes no attempt to validate the function names
... however, if the names
+ are not valid, then the default show and highlight methods will be used.
+
+ Currently, the partial page content that is rendered may <<not>> use an
Environmental services. This is expected
+ to change soon.
+
+** Coming Soon
+
+ * zone parameter for Form components
+
+ * Extending a Form with a Zone
+
+ * Additional Tapestry.ZoneEffect functions, plus documentation
+
+ * Real examples ...
+
+ []
Your own Ajax Components
@@ -211,7 +292,8 @@
The possible return values are:
- * A Block or Component to render as the response.
+ * A Block or Component to render as the response. The response will be a
JSON hash, will a "content" key
+ whose value is the rendered markup. This is the basis for updates with
the Zone component.
* A {{{../../apidocs/org/apache/tapestry/json/JSONObject.html}JSONObject}},
which will be sent as the response.
Modified: tapestry/tapestry5/trunk/tapestry-core/src/test/app1/Start.tml
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/test/app1/Start.tml?rev=599123&r1=599122&r2=599123&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/test/app1/Start.tml (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/test/app1/Start.tml Wed Nov 28
12:03:40 2007
@@ -114,7 +114,12 @@
Missing Template Demo
</t:pagelink>
-- Demo for what happens when a template is not found
for a
- page.
+ page
+ </li>
+
+ <li>
+ <t:pagelink page="zonedemo">Zone Demo</t:pagelink>
+ -- dynamic updates within a page
</li>
</ul>
</td>
Modified:
tapestry/tapestry5/trunk/tapestry-core/src/test/java/org/apache/tapestry/integration/IntegrationTests.java
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/test/java/org/apache/tapestry/integration/IntegrationTests.java?rev=599123&r1=599122&r2=599123&view=diff
==============================================================================
---
tapestry/tapestry5/trunk/tapestry-core/src/test/java/org/apache/tapestry/integration/IntegrationTests.java
(original)
+++
tapestry/tapestry5/trunk/tapestry-core/src/test/java/org/apache/tapestry/integration/IntegrationTests.java
Wed Nov 28 12:03:40 2007
@@ -1159,4 +1159,30 @@
assertTextPresent("Thirteen is an unlucky number.");
}
+
+ @Test
+ public void autocomplete_mixin()
+ {
+ start("Autocomplete Mixin Demo");
+
+ // And that's as far as we can go currently, because
+ // of limitations in Selenium 0.8.3 and bugs in Selenium 0.9.2.
+ }
+
+ @Test
+ public void zone_updates()
+ {
+ start("Zone Demo");
+
+ assertTextPresent("No name has been selected.");
+
+ // Hate doing this, but selecting by the text isn't working, perhaps
because of the
+ // HTML entities.
+ click("select_0");
+
+ // And that's as far as we can go currently, because
+ // of limitations in Selenium 0.8.3 and bugs in Selenium 0.9.2.
+
+ // assertTextPresent("Selected: Mr. <Roboto>");
+ }
}
