You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@shale.apache.org by ws...@apache.org on 2006/08/09 05:24:33 UTC
svn commit: r429947 - in /shale/framework/trunk/src/site:
resources/images/remoting-001.jpg resources/images/remoting-002.jpg
resources/images/remoting-003.jpg xdoc/features-remoting.xml
Author: wsmoak
Date: Tue Aug 8 20:24:32 2006
New Revision: 429947
URL: http://svn.apache.org/viewvc?rev=429947&view=rev
Log:
Improve documentation for Shale Remoting.
Submitted By: David Geary
SHALE-130
Added:
shale/framework/trunk/src/site/resources/images/remoting-001.jpg (with props)
shale/framework/trunk/src/site/resources/images/remoting-002.jpg (with props)
shale/framework/trunk/src/site/resources/images/remoting-003.jpg (with props)
Modified:
shale/framework/trunk/src/site/xdoc/features-remoting.xml
Added: shale/framework/trunk/src/site/resources/images/remoting-001.jpg
URL: http://svn.apache.org/viewvc/shale/framework/trunk/src/site/resources/images/remoting-001.jpg?rev=429947&view=auto
==============================================================================
Binary file - no diff available.
Propchange: shale/framework/trunk/src/site/resources/images/remoting-001.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: shale/framework/trunk/src/site/resources/images/remoting-002.jpg
URL: http://svn.apache.org/viewvc/shale/framework/trunk/src/site/resources/images/remoting-002.jpg?rev=429947&view=auto
==============================================================================
Binary file - no diff available.
Propchange: shale/framework/trunk/src/site/resources/images/remoting-002.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: shale/framework/trunk/src/site/resources/images/remoting-003.jpg
URL: http://svn.apache.org/viewvc/shale/framework/trunk/src/site/resources/images/remoting-003.jpg?rev=429947&view=auto
==============================================================================
Binary file - no diff available.
Propchange: shale/framework/trunk/src/site/resources/images/remoting-003.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: shale/framework/trunk/src/site/xdoc/features-remoting.xml
URL: http://svn.apache.org/viewvc/shale/framework/trunk/src/site/xdoc/features-remoting.xml?rev=429947&r1=429946&r2=429947&view=diff
==============================================================================
--- shale/framework/trunk/src/site/xdoc/features-remoting.xml (original)
+++ shale/framework/trunk/src/site/xdoc/features-remoting.xml Tue Aug 8 20:24:32 2006
@@ -10,7 +10,169 @@
<section name="Shale Remoting">
<a name="remoting"/>
- <p>FIXME - Describe remoting feature.</p>
+ <a name="remoting-introduction"/>
+ <subsection name="Remoting Introduction">
+
+ <p>Shale lets you map server-side resources, such as JavaScript or
+ managed bean methods, to URLs. Shale turns URLs into resources with
+ <i>processors</i>, which apply a mapping to a URL and take appropriate
+ action. Out of the box, Shale provides the following processors:</p>
+
+ <ul>
+ <li>
+ <i>Class Resource</i>
+ : access static resources from your classpath
+ </li>
+ <li>
+ <i>Web Resource</i>
+ : access static resources from your web app's document root
+ </li>
+ <li>
+ <i>Method Binding</i>
+ : execute a managed bean's methods on the server
+ </li>
+ <li>
+ <i>Chain</i>
+ : maps a URL to a Jakarta Commons Chain (chains are used internally by Shale)
+ </li>
+ </ul>
+
+ </subsection>
+
+ <a name="remoting-static-resources"/>
+ <subsection name="Accessing Static Resources">
+ FIXME
+ </subsection>
+
+ <a name="remoting-methods"/>
+ <subsection name="Remotely Calling Managed Bean Methods">
+
+ <p>Shale maps URLs to managed bean methods in your appliation with the
+ Method Binding processor. For example, Shale maps the URL
+ <code>remote/userBean/validateUsername.jsf</code> to a call to
+ <code>userBean.validateUsername()</code> as shown in the following
+ figure (assuming the suffix <code>.jsf</code> is mapped to the JSF
+ servlet). This simple mechanism, among other things, lets you easily
+ implement Ajax (Asynchronous JavaScript and XMLHttpRequest)
+ functionality. </p>
+
+ <p><img src="images/remoting-001.jpg"/></p>
+
+ </subsection>
+
+ <a name="remoting-example"/>
+ <subsection name="An Ajax Example">
+
+ <p>Here's a form that implements realtime validation:</p>
+
+ <p><img src="images/remoting-002.jpg"/></p>
+
+ <p> When the user leaves the <code>username</code> textfield, Shale
+ calls the backing bean's <code>validateUsername</code> method. This
+ application only has one registered user, and his name is Joe, so if
+ the user types anything other than Joe in the username field, we
+ display an error message, like this: </p>
+
+ <p><img src="images/remoting-003.jpg"/></p>
+
+ <p>To implement the Ajax call, we first hook up a client-side event
+ handler to our <code>username</code> textfield:</p>
+
+ <pre>
+ ...
+ <h:panelGroup>
+
+ <h:inputText onfocus="hideMessage();"
+ <strong>onblur="validateUsername(this.value);"/></strong>
+
+ <f:verbatim>
+ <div id="message" style="display: none;"></div>
+ </f:verbatim>
+
+ </h:panelGroup>
+ ...
+ </pre>
+
+ <p>Notice the empty <code>DIV</code>. That's the DIV that we'll fill
+ with an error message as appropriate. When the user enters the
+ username field, we clear out the message DIV, like this:</p>
+
+ <pre>
+ function hideMessage() {
+ $("message").style.display = "none"; // the $ is Prototype's shorthand for window.document.getElementById()
+ }
+ </pre>
+
+ <p>Here's the JavaScript <code>validateUsername</code> function:</p>
+
+ <pre>
+ function <strong>validateUsername</strong>(username) {
+ new Ajax.Request(
+ "<strong>dynamic/userBean/validateUsername.faces</strong>",
+ {
+ method: "post",
+ parameters: "username=" + username,
+ onComplete: showMessage
+ }
+ );
+ }
+ </pre>
+
+ <p>The preceding code fragment uses the <a
+ href="http://prototype.conio.net/">Prototype JavaScript Library</a> to
+ make the Ajax call. You can use whatever framework you like, or you
+ can code the Ajax call yourself. The point here is the URL, which
+ Shale maps to <code>userBean.validateUsername()</code>. Remember, when
+ you invoke the URL <code>dynamic/userBean/validateUsername.jsf</code>
+ Shale thinks <i>invoke <code>userBean.validateUsername()</code></i>.
+ Here's what that Java code looks like:</p>
+
+ <pre>
+ public void validateUsername() {
+ FacesContext context = FacesContext.getCurrentInstance();
+ String username = (String)context
+ .getExternalContext()
+ .getRequestParameterMap().get("username");
+
+ if( ! "Joe".equals(username))
+ writeResponse(context, "Sorry, that's an unathorized username");
+ }
+ private void writeResponse(FacesContext context,
+ ResponseWriter writer =
+ (new <strong>ResponseFactory</strong>()).getResponseWriter(context, "text/plain");
+ try {
+ writer.writeText(text, null);
+ }
+ catch (IOException e) {
+ e.printStackTrace();
+ }
+ }
+ </pre>
+
+ <p>We get the username field's value from the corresponding request
+ parameter and validate that value. After Shale invokes the
+ <code>validateUsername</code> method, it short-circuits the JSF
+ lifecycle so that JSF does not render a response.</p>
+
+ <p><i>Note:</i> The <code>ResponseFactory</code> class is part of the
+ Shale remoting package. See the <a
+ href="http://shale.apache.org/shale-remoting/apidocs/index.html">javadocs</a>
+ for more information.</p>
+
+ <p>After the call to <code>userBean.validateUsername()</code> returns,
+ Prototype calls our <i>onComplete</i> JavaScript function, which we
+ specified as <code>showMessage</code>. Here's what that JavaScript
+ function looks like:</p>
+
+ <pre>
+ function showMessage(xhr) {
+ var msg = $("message");
+ msg.style.display = "inline";
+ msg.style.color = "red";
+ msg.innerHTML = xhr.responseText; // set the innerHTML of the message DIV
+ }
+ </pre>
+ </subsection>
<subsection name="Resources">
<ul>
Re: svn commit: r429947 - in /shale/framework/trunk/src/site: resources/images/remoting-001.jpg resources/images/remoting-002.jpg resources/images/remoting-003.jpg xdoc/features-remoting.xml
Posted by Matthias Wessendorf <ma...@apache.org>.
David,
that documentation looks great. Is your second edition covering Shale?
The first image looks very professional ;)
-Matthias
On 8/9/06, David Geary <sa...@gmail.com> wrote:
> I've attached an updated features-remote.xml to SHALE-130 that contains the
> changes outlined below.
>
> Thanks,
>
>
> david
>
> 2006/8/9, David Geary < sabreware@gmail.com>:
> >
> > Thanks for committing this, Wendy. It looks good. If you don't mind, could
> > you add a couple of updates? Thanks.
> >
> > Please add these two paragraphs at the end of Remoting Introduction, after
> > the bulleted list:
> >
> > Processors are associated with URL patterns. Each processor has a default
> > pattern. For example, the Class Resource processor by default, is associated
> > with the URL pattern <code>/static/*</code>, so any URL starting with
> > <code>static</code> is handled by that processor. You can override those
> > default patterns with context initialization parameters if you wish.
> >
> > That's a pretty abstract description of Shale remoting, so let's take a
> > look at a concrete example of remotely calling managed bean methods.
> >
> > At the end of the An Ajax Example, just before Resources, please add this
> > paragrah:
> >
> > The preceeding JavaScript stores the response text, which we generated in
> > the <code>userBean</code>'s <code>validateUsername</code> method. Because
> > Shale calls the Faces context <code>responseComplete()</code> method, which
> > halts the JSF lifecycle and therefore inhibits a page refresh, the updated
> > DIV will be the only thing that changes on the page.
> >
> > Also, could you switch the Accessing Static Resources and Remotely Calling
> > Managed Bean Methods? I think we get more bang for our buck if we open with
> > the Ajax example.
> >
> > Thanks for all your help,
> >
> >
> > david
> >
> > 2006/8/8, wsmoak@apache.org < wsmoak@apache.org>:
> >
> > > Author: wsmoak
> > > Date: Tue Aug 8 20:24:32 2006
> > > New Revision: 429947
> > >
> > > URL: http://svn.apache.org/viewvc?rev=429947&view=rev
> > > Log:
> > > Improve documentation for Shale Remoting.
> > > Submitted By: David Geary
> > > SHALE-130
> > >
> > > Added:
> > > shale/framework/trunk/src/site/resources/images/remoting-001.jpg
> > > (with props)
> > > shale/framework/trunk/src/site/resources/images/remoting-002.jpg
> > > (with props)
> > > shale/framework/trunk/src/site/resources/images/remoting-003.jpg
> > > (with props)
> > > Modified:
> > > shale/framework/trunk/src/site/xdoc/features-remoting.xml
> >
> >
> > [snip]
> >
> >
> >
>
>
--
Matthias Wessendorf
further stuff:
blog: http://jroller.com/page/mwessendorf
mail: mwessendorf-at-gmail-dot-com
Re: svn commit: r429947 - in /shale/framework/trunk/src/site: resources/images/remoting-001.jpg resources/images/remoting-002.jpg resources/images/remoting-003.jpg xdoc/features-remoting.xml
Posted by David Geary <sa...@gmail.com>.
I've attached an updated features-remote.xml to SHALE-130 that contains the
changes outlined below.
Thanks,
david
2006/8/9, David Geary < sabreware@gmail.com>:
>
> Thanks for committing this, Wendy. It looks good. If you don't mind, could
> you add a couple of updates? Thanks.
>
> Please add these two paragraphs at the end of Remoting Introduction, after
> the bulleted list:
>
> Processors are associated with URL patterns. Each processor has a default
> pattern. For example, the Class Resource processor by default, is associated
> with the URL pattern <code>/static/*</code>, so any URL starting with
> <code>static</code> is handled by that processor. You can override those
> default patterns with context initialization parameters if you wish.
>
> That's a pretty abstract description of Shale remoting, so let's take a
> look at a concrete example of remotely calling managed bean methods.
>
> At the end of the An Ajax Example, just before Resources, please add this
> paragrah:
>
> The preceeding JavaScript stores the response text, which we generated in
> the <code>userBean</code>'s <code>validateUsername</code> method. Because
> Shale calls the Faces context <code>responseComplete()</code> method, which
> halts the JSF lifecycle and therefore inhibits a page refresh, the updated
> DIV will be the only thing that changes on the page.
>
> Also, could you switch the Accessing Static Resources and Remotely Calling
> Managed Bean Methods? I think we get more bang for our buck if we open with
> the Ajax example.
>
> Thanks for all your help,
>
>
> david
>
> 2006/8/8, wsmoak@apache.org < wsmoak@apache.org>:
>
> > Author: wsmoak
> > Date: Tue Aug 8 20:24:32 2006
> > New Revision: 429947
> >
> > URL: http://svn.apache.org/viewvc?rev=429947&view=rev
> > Log:
> > Improve documentation for Shale Remoting.
> > Submitted By: David Geary
> > SHALE-130
> >
> > Added:
> > shale/framework/trunk/src/site/resources/images/remoting-001.jpg
> > (with props)
> > shale/framework/trunk/src/site/resources/images/remoting-002.jpg
> > (with props)
> > shale/framework/trunk/src/site/resources/images/remoting-003.jpg
> > (with props)
> > Modified:
> > shale/framework/trunk/src/site/xdoc/features-remoting.xml
>
>
> [snip]
>
>
>
Re: svn commit: r429947 - in /shale/framework/trunk/src/site: resources/images/remoting-001.jpg resources/images/remoting-002.jpg resources/images/remoting-003.jpg xdoc/features-remoting.xml
Posted by David Geary <sa...@gmail.com>.
Thanks for committing this, Wendy. It looks good. If you don't mind, could
you add a couple of updates? Thanks.
Please add these two paragraphs at the end of Remoting Introduction, after
the bulleted list:
Processors are associated with URL patterns. Each processor has a default
pattern. For example, the Class Resource processor by default, is associated
with the URL pattern <code>/static/*</code>, so any URL starting with
<code>static</code> is handled by that processor. You can override those
default patterns with context initialization parameters if you wish.
That's a pretty abstract description of Shale remoting, so let's take a look
at a concrete example of remotely calling managed bean methods.
At the end of the An Ajax Example, just before Resources, please add this
paragrah:
The preceeding JavaScript stores the response text, which we generated in
the <code>userBean</code>'s <code>validateUsername</code> method. Because
Shale calls the Faces context <code>responseComplete()</code> method, which
halts the JSF lifecycle and therefore inhibits a page refresh, the updated
DIV will be the only thing that changes on the page.
Also, could you switch the Accessing Static Resources and Remotely Calling
Managed Bean Methods? I think we get more bang for our buck if we open with
the Ajax example.
Thanks for all your help,
david
2006/8/8, wsmoak@apache.org <ws...@apache.org>:
>
> Author: wsmoak
> Date: Tue Aug 8 20:24:32 2006
> New Revision: 429947
>
> URL: http://svn.apache.org/viewvc?rev=429947&view=rev
> Log:
> Improve documentation for Shale Remoting.
> Submitted By: David Geary
> SHALE-130
>
> Added:
> shale/framework/trunk/src/site/resources/images/remoting-001.jpg
> (with props)
> shale/framework/trunk/src/site/resources/images/remoting-002.jpg
> (with props)
> shale/framework/trunk/src/site/resources/images/remoting-003.jpg
> (with props)
> Modified:
> shale/framework/trunk/src/site/xdoc/features-remoting.xml
[snip]