doc/src/Tutorial2/tutorial-chapter-intro.xml

<chapter id="intro">
  <title>Introduction</title>
  <para>Welcome to Tapestry!</para>
  <para>
    Tapestry is an application framework for developing web applications.  It uses
    a component object model to represent the pages of a web application.  This is
    similar to spirit to using the Java Swing component object model to build GUIs.
  </para>
  <para>
    This tutorial exists to help newcomers quickly understand Tapestry.
    <xref linkend="intro"/>
    begins by providing some detail on various ways in which you can use Tapestry in your environment.
    <xref linkend="getting-started"/> and <xref linkend="Introductory-examples"/> provide both a basic
    understanding of Tapestry, along with some introductory examples.

    <xref linkend="pages"/>,
    <xref linkend="forms"/>,
    <xref linkend="built-ins"/>,
    <xref linkend="assets"/> and
    <xref linkend="localization"/>
    explain the core Tapestry concepts in detail, providing full
    examples along the way to assist you in learning how the framework is used.

    The remainder of the tutorial provides useful information on advanced topics including component creation,
    usage of the component inspector, EJB support, and optimizations.
  </para>

  <para>

  </para>

  <section id="working-with-tapestry">
    <title>Working with Tapestry</title>
    <para>
      The goal of Tapestry is to eliminate most of the unnecessary <footnote><para>
          Session management, manual validation and other "application plumbing" tasks.  In other words,
          you get to focus on the problem you're trying to solve as opposed to writting a web framework
          every time you go to write a web app or site.
          </para></footnote>
        coding in a web application.  Under Tapestry,
      nearly all code is directly related to application functionality, with very little "plumbing".  If you
      have previously developed a web application using Microsoft Active Server Pages, JavaServer
      Pages or Java Servlets, you may take for granted all the plumbing:  writing servlets, assembling
      URLs, parsing URLs, managing objects inside the &HttpSession;, etc.
    </para>
    <para>
      Tapestry takes care of nearly all of that, for free.  It allows for the development of rich, highly
      interactive applications.
    </para>
    <para>
      Before you get into the wonders of Tapestry, you will need to setup your development
      environment such that you are able to both run the provided tutorial applications,
      and also such that you are able to
      compile and run the code that you develop while moving through this tutorial.
        If you're keen to read through some of the tutorial content without doing this setup,
        you can skip to <xref linkend="getting-started"/>.
    </para>
  </section>

  <section id="environment-setup">
    <title>Setting up the environment</title>

    <para>
      This document expects that you will have extracted the full Tapestry distribution to your
      <filename class="directory">C:</filename> drive.
      <footnote> <para>
          If you are using Solaris or another non-Windows operating system, you're expected
          to be savvy enough to translate to a sensibly constructed file system.
      </para></footnote>

      This will have created a directory <filename class="directory">C:\Tapestry-<replaceable>x.x</replaceable>
      </filename>
      and, beneath it, several more directories.
      <footnote> <para>
          The three numbers are the release number.  At the time of this writing, the release
          was 2.3, but this is constantly changing.  Simply adjust the actual pathname to
          reflect the release of Tapestry you downloaded.
      </para></footnote>
    </para>
    <para>
      The source code for the Tutorial is distributed as a JAR file,
      <filename>src/examples-src.jar</filename>.  A precompiled WAR file,
      <filename>lib/tutorial.war</filename> is included in the distribution.
      The Tapestry distribution includes an &Ant; build file that allows the
      Tutorial to be directly executed.  Ant release 1.5 is required.
    </para>

    <para>
      From the Tapestry root directory,
      execute the command <command>ant -emacs run-tutorial</command>, which will launch the
      Jetty server for the Tutorial.
    </para>
    <para>
      Once Jetty is running, you can access the Tutorials using the URL
      <ulink url="http://localhost:8080/tutorial">
	<filename>http://localhost:8080/tutorial</filename>
      </ulink>.
      You should do this now, in order to check that your
      environment is setup correctly so far.
    </para>
    <figure>
      <title>Tutorial Index Page</title>
      <mediaobject>
	<imageobject>
	  <imagedata fileref="images/tutorial-index.png" format="PNG"/>
	</imageobject>
      </mediaobject>
    </figure>

    Tapestry can exist in any Servlet (v2.1 +) compatible container,
    for example JBoss. If you wish to deploy and run the tutorial in
    an alternative environment please see <xref linkend="integration"/>
  </section>

  <section id="basic-dev-env">
    <title>A basic development environment</title>
    <para>
      This section details how to setup a development environment suitable
      for use with this tutorial. It will provide basic &Ant; support, and
      the ability to test your examples using &Jetty;.
    </para>

    <para>
      Within the <filename>examples</filename> directory, you will find a sample
			build environment (<ulink url="examples/DevelopmentEnvironment.zip">
				<filename>tutorial-environment.zip</filename>.
				</ulink>), which you can use as you progress through this document.
      This includes a build file capable of:
      <orderedlist>
	<listitem>Compiling the code</listitem>
	<listitem>Packaging your developed code into a WAR</listitem>
	<listitem>Running a Jetty instance, using your compiled code, and</listitem>
	<listitem>Deploying your code into a user specified directory (for J2EE containers)</listitem>
      </orderedlist>
    </para>
    <para>
      To setup your environment, perform the following steps:
      <orderedlist>
	<listitem>The first step is to decide a directory for your example code.
	  This tutorial uses <filename class="directory">C:\TapestryExample</filename>.
	  <footnote><para>As before, it is assumed that if you are using a non-Windows environment,
	    that you have the knowledge necessary to translate the paths</para></footnote>
	</listitem>
	<listitem>Extract the contents of the archive <filename>tutorial-environment.zip</filename>
	  into this new directory.</listitem>
	<listitem>Open the file <filename>build.xml</filename> with your favourite editor,
	  and change the properties as listed below:
	  <table>
	    <title>Ant Build Properties</title>
	    <tgroup cols="2" align="left" colsep="1" rowsep="1">
	      <thead>
		<row>
		  <entry>Property Name</entry>
		  <entry>Example Value</entry>
		</row>
	      </thead>
	      <tbody>
		<row>
		  <entry>deployment.dir</entry>
		  <entry><filename>c:\JBoss-3.0.0\server\default\deploy</filename></entry>
		</row>
		<row>
		  <entry>tapestry.install.dir</entry>
		  <entry><filename>c:\Tapestry-<replaceable>x.x</replaceable></filename></entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
	</listitem>
	<listitem>Save the file :-)</listitem>
	<listitem>
	  <para>
	    Go to a command console, to the directory you will be using
	    for development. In the case of this tutorial, that is
	    <filename class="directory">C:\TapestryExample</filename>
	    and type 'ant'. If all goes will, you will see a message saying that the build was successful.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Type 'ant run', and then open a web browser to
	    <ulink url="http://localhost:8081/learn-tapestry">
	      <filename>http://localhost:8081/learn-tapestry</filename>
	    </ulink>
	    <footnote><para>
	      Note that this is intentionally a
	      different port number from the tapestry tutorial example itself.
	      It means you can run both at once if you wish.</para>
	    </footnote>
	  </para>
	  <para>
	    <figure>
	      <title>What you should see, when you click on the link above</title>
	      <mediaobject>
		<imageobject>
		  <imagedata fileref="images/tapestry-dev-env.png" format="PNG"/>
		</imageobject>
	      </mediaobject>
	    </figure>
	  </para>
	</listitem>
      </orderedlist>
      A brief overview of the tasks provided by the script:
      <variablelist>
	<varlistentry>
	  <term>compile</term>
	  <listitem>Compiles any code within the <filename>src\</filename> directory (which is created for you by the
	    script, if you don't create it yourself)</listitem>
	</varlistentry>
	<varlistentry>
	  <term>war</term>
	  <listitem>Packages up the compiled classes, Tapestry libs, and other 3rd party libs into
	    a WAR file for deployment into a Servlet container</listitem>
	</varlistentry>
	<varlistentry>
	  <term>deploy</term>
	  <listitem>Builds the WAR if it does not exist, and copies it to the deployment
	    location specified by <varname>deployment.dir</varname></listitem>
	</varlistentry>
	<varlistentry>
	  <term>run</term>
	  <listitem>Runs your compiled Tapestry Application via Jetty, on port 8081</listitem>
	</varlistentry>
      </variablelist>
    </para>
  </section>
</chapter>