<document>
  <header>
    <product>resin</product>
    <resin-2.0>$article/xtp_templates.xtp</resin-2.0>
    <title>Templates</title>
    <authors>
      <person>Scott Ferguson</person>
    </authors>
  </header>

  <body>
    <summary/>

<section title='Displaying the Guest Book'>

The first advantage of XTP is that it separates the JSP code from the
page.  The page design can just use a standard HTML/XML editor.  More
importantly, since it's easy to create tags, you can create tags
meaningful for your specific application.

<p/>The XTP templates example is an expansion of the <a 
href='jsp|templates'>JSP "model 2"</a> example.  You may want to
refer to <a href='xtp|taglib'>Resin's
support of XSLT and JSP</a>.

<p/>The guest book uses three application-specific tags

<deftable>
<tr><th>Tag<th>Meaning
<tr><td>ct:guest-book<td>iterates over the guest book entries.
<tr><td>ct:guest-name<td>writes the guest's name.
<tr><td>ct:guest-comment<td>writes the guest's comment.
</deftable>

<p/>Compare the login.xtp page with the
<a href='jsp|templates#login_display'>login.jsp</a> in the JSP
templates example.  

<example title='login.xtp'>
<eg-em>&lt;?xml-stylesheet href='guestbook.xsl'?></eg-em>
&lt;title>Hogwarts Comments&lt;/title>

&lt;table width='100%'>
&lt;tr>
  &lt;td width='25%'>&lt;em>Name&lt;/em>&lt;/td>
  &lt;td width='75%'>&lt;em>Comment&lt;/em>&lt;/td>
&lt;/tr>
<eg-em>&lt;ct:guest-book></eg-em>
  &lt;tr>
  &lt;td><eg-em>&lt;ct:guest-name/></eg-em>
  &lt;td><eg-em>&lt;ct:guest-comment/></eg-em>
<eg-em>&lt;/ct:guest-book></eg-em>
&lt;/table>
</example>

<p/>HTML tags should be copied to the generated output.  So we just
create a default rule to copy the input to the output.  XSLT is a
pattern based language.  'node()' matches any node and '@*' matches any
attribute.  So any tag that doesn't match any other rules will be
copied.

<p/>It's important to notice that XSLT works with XML trees, not text
streams like JSP.  The xsl:copy of an attribute adds and attribute
to the containing element.

<example title='defaultcopy.xsl: strict XSLT'>
&lt;xsl:template match='node()|@*'>
  &lt;xsl:copy>
    &lt;xsl:apply-templates select='node()|@*'/>
  &lt;/xsl:copy>
&lt;/xsl:template>
</example>

Strict XSLT follows the XML syntax.  There are several advantages of
using XML but readability is not one of them.  To make stylesheets
more readable we've added some simple syntactic sugar to XSLT,
called XSLT-lite.  XML purists can stick to the standard XML syntax:
Resin supports both.  You can look at our <a
href='xslt|index'>XSLT</a> and <a href='xtp|stylescript'>
XSLT-lite</a>
references and also some <a href='xslt|xslt-lite-eg'>
XSLT-lite examples.</a>

<p/>XSLT-lite makes scanning templates easier because the template
pattern is clear, on its own line.  The following is exactly
equivalent to the defaultcopy.xsl above.

<example title='defaultcopy.xsl: XSLT-lite'>
node()|@*
&lt;&lt;
&lt;xsl:copy>
  &lt;xsl:apply-templates select='node()|@*'/>
&lt;/xsl:copy>
>>
</example>

<p/>guestbook.xsl contains the custom tags for the guestbook example.
When Resin looks at a node, it will select the best matching pattern
and execute it.  The element &lt;ct:guest-book> will generate a loop,
while &lt;form action='GuestXtp'> will copy the form to the output.

<example title='guestbook.xsl'>
&lt;!-- Use language=javascript for the XSLT -->
<eg-em>&lt;xtp:directive.page language=javascript/></eg-em>

&lt;xsl:import href='defaultcopy.xsl'/>

&lt;!-- Generated JSP uses language=javascript -->
/ 
&lt;&lt;
<eg-em>&lt;jsp:directive.page language='javascript'/></eg-em>
&lt;xsl:apply-templates/>
>>

ct:guest-book
&lt;&lt;
<eg-em>&lt;% for (var _ct_guest in application.attribute.guest_book) { %></eg-em>
&lt;xsl:apply-templates/>
<eg-em>&lt;% } %></eg-em>
>>

ct:guest-name
&lt;&lt;
<eg-em>&lt;%= _ct_guest.name %></eg-em>
>>

ct:guest-comment
&lt;&lt;
<eg-em>&lt;%= _ct_guest.comment %></eg-em>
>>

</example>

<p/>So now we've created some tags for a custom application.  That's
nice and it shows how XSLT can clean JSP pages.  The guest book JSP
was fairly simple so the added complexity of creating stylesheets
doesn't really show how powerful the XTP concept is.  For a taste of
real power, we'll create a simple form library.

</section>

<section title='Intelligent forms'>

Adding addition functionality to forms makes HTML and JSP complex.
GuestXtp just adds simple filling in of default values.  The GuestXtp
servlet calls <code/request.setAttribute/> to set default values for
form element.  For example, once a user has added a comment, she can
edit the comment.  The default value is the old comment.

<p/>In fact, the w3c now has a new requirements document for the next
generation of intelligent forms.  That doesn't really help web
designers because web sites still need to support old browsers.  XTP
gives web sites the more powerful functionality now.

<p/>There are a few other common form extensions:
<ul>
<li>Server defaults
<li>Server validation
<li>Client validation
<li>Client actions
</ul>

<p/>The XTP file itself is simple.  It just looks like any HTML page,
except form values are called ct:*.

<example title='login.xtp'>

&lt;form action='GuestXtp' method='post'>
  <eg-em>&lt;ct:hidden name='action' value='login'/></eg-em>
  &lt;table>
  &lt;tr>&lt;td>Name&lt;td><eg-em>&lt;ct:input name='Name'/></eg-em>
  &lt;tr>&lt;td>Password&lt;td><eg-em>&lt;ct:password name='Password'/></eg-em>
  &lt;tr>&lt;td colspan=2>Hint: the password is quidditch
  &lt;tr>&lt;td/>&lt;td><eg-em>&lt;ct:submit value='Login'/></eg-em>
&lt;/form>

</example>

<p/>The transformation is relatively simple.  Copy all properties to
the output and add a value attribute if the servlet supplied a default value.

<example>
<example>&lt;ct:input size=40 name='Name'/></example>
<results>&lt;input name=Name size=40 value='Harry Potter'></results>
</example>

<p/>XSLT lets stylesheets pull common formatting code into functions
using the named template mechanism.  The template functions are called
with xsl:call-template.  xsl:call-template works like
xsl:apply-templates, but it passes the current node, not the children
nodes.

<p/>Because the generated JSP will add an attribute at run time, the
form.xsl treats its output as unparsed content.  Unknown elements,
like &lt;form> or &lt;input> are printed as text.  Unparsed content
works just like JSP.

<p/>fun:copy-attrs is a simple XSLT function which copies the
attributes from the XTP element to the output.  In the ct:input example above,
it will copy name=Name and size=40.

<p/>xtp:cache tells Resin that the XSLT results are cacheable.  Once
it's generated the JSP, it doesn't need to run the XSLT engine again.
This greatly improves the performance.

<example title='form.xsl'>
&lt;xsl:stylesheet parsed-content='false'>

&lt;xtp:cache/>

&lt;xsl:template name='fun:copy-attrs'>
  &lt;xsl:for-each select='@*'>
    &lt;xsl:text> &lt;/xsl:text><eg-em>&lt;{name(.)}></eg-em>="<eg-em>&lt;{.}></eg-em>"&lt;xsl:text/>
  &lt;/xsl:for-each>
&lt;/xsl:template>

</example>

<p/>fun:input-attrs is the core of the form processing.  It calls
fun:copy-attrs to copy the user's attributes.  Then it generates the
JSP to add a value attribute if it's available.

<example>

&lt;xsl:template name='fun:input-attrs'>
  &lt;xsl:call-template name='fun:copy-attrs'/>
  &lt;xsl:if test='@value'>
    value="<{@value}>"
  &lt;/xsl:if>
  &lt;xsl:if test='not(@value)'>
<eg-em>    &lt;% { 
         var _ct_v = request.attribute["&lt;{@name}>"];
         if (_ct_v == null)
         _ct_v = "";
         out.write(' value="', _ct_v.replace('"', "&quot;"), '"');
       }
    %></eg-em>
  &lt;/xsl:if>
&lt;/xsl:template>

</example>

<p/>Now that the functions have been defined, creating the individual
tags is simple.

<example>

ct:input
&lt;&lt;
&lt;input &lt;xsl:call-template name='fun:input-attrs'/>>
>>

ct:password
&lt;&lt;
&lt;input type='password' &lt;xsl:call-template name='fun:input-attrs'/>>
>>

ct:submit 
&lt;&lt;
&lt;input type=submit &lt;xsl:call-template name='fun:input-attrs'/>>
>>
</example>
</section>

<section title='Conclusion'>

XTP is a tradeoff.  It takes more work to design custom tags than to
write standard inline JSP.  However, once you've written the tags,
using them is a breeze.  In the next few months, we'll start building
useful libraries of tags similar to Perl's CGI.pl.

<p/>An important value of XTP is that it lets web pages use the latest
W3C specifications without waiting for all the browsers to support
it.  For example, the W3C has proposed requirements for intelligent
forms.  A properly designed form.xsl can implement intelligent forms
on the server and support all browsers, not just the browsers
supporting the spec.

</section>
  </body>
</document>
