Author: steveh
Date: Mon Nov 1 13:50:04 2004
New Revision: 56285
Modified:
incubator/beehive/site/build/site/controls/tutorial_controls.html
incubator/beehive/site/build/site/pageflow/tutorial_pageflow.html
incubator/beehive/site/src/documentation/content/xdocs/controls/tutorial_controls.xml
Log:
Control tutorial rewritten from a "distribution" perspective, not a "source"
perspective.
Modified: incubator/beehive/site/build/site/controls/tutorial_controls.html
==============================================================================
--- incubator/beehive/site/build/site/controls/tutorial_controls.html
(original)
+++ incubator/beehive/site/build/site/controls/tutorial_controls.html Mon Nov
1 13:50:04 2004
@@ -253,31 +253,28 @@
<li>
<a href="#Tutorial+Goals">Tutorial Goals</a>
</li>
+<li>
+<a href="#Assumptions+Made+in+This+Tutorial">Assumptions Made in This
Tutorial</a>
+</li>
</ul>
</li>
<li>
-<a href="#step1">Step 1: Begin the Controls Tutorial</a>
+<a href="#step1">Step 1: Begin the Page Flow Tutorial</a>
<ul class="minitoc">
<li>
-<a href="#Note+on+the+current+state+of+the+Controls+tutorial">Note on the
current state of the Controls tutorial</a>
-</li>
-<li>
-<a href="#Download+and+Install+JDK5">Download and Install JDK5</a>
+<a href="#To+Download+and+Install+J2SE5">To Download and Install J2SE5</a>
</li>
<li>
-<a href="#Download+and+Install+SVN+%28Subversion+Source+Control%29">Download
and Install SVN (Subversion Source Control)</a>
+<a href="#To+Install+ANT+1.6.2">To Install ANT 1.6.2</a>
</li>
<li>
-<a href="#Download+and+Install+Beehive">Download and Install Beehive</a>
+<a href="#To+Download+and+Install+Tomcat+5">To Download and Install Tomcat
5</a>
</li>
<li>
-<a href="#Install+ANT+">Install ANT</a>
+<a href="#To+Download+and+Install+a+Beehive+Binary+Distribution">To Download
and Install a Beehive Binary Distribution</a>
</li>
<li>
-<a href="#Run+the+">Run the bootstrap Target</a>
-</li>
-<li>
-<a href="#Compile+Beehive">Compile Beehive</a>
+<a href="#To+Set+up+the+Development+Environment">To Set up the Development
Environment</a>
</li>
</ul>
</li>
@@ -288,19 +285,22 @@
<a href="#Introduction">Introduction</a>
</li>
<li>
-<a href="#To+Create+a+Control%27s+Implementation+File">To Create a Control's
Implementation File</a>
+<a href="#To+Create+a+Control+Application+Folder">To Create a Control
Application Folder</a>
</li>
<li>
-<a href="#To+Create+the+Control%27s+Interface+File">To Create the Control's
Interface File</a>
+<a href="#To+Add+Beehive+Runtime+JARs+to+Your+Application.">To Add Beehive
Runtime JARs to Your Application.</a>
</li>
<li>
-<a href="#To+Create+the+WEB-INF+directory">To Create the WEB-INF directory</a>
+<a href="#To+Create+the+Control%27s+Implementation+File">To Create the
Control's Implementation File</a>
</li>
<li>
-<a href="#Edit+a+JSP+Page+to+Test+the+Control">Edit a JSP Page to Test the
Control</a>
+<a href="#To+Create+the+Control%27s+Interface+File">To Create the Control's
Interface File</a>
</li>
<li>
-<a href="#Compile+the+Control">Compile the Control</a>
+<a href="#To+Create+a+JSP+Page+to+Test+the+Control">To Create a JSP Page to
Test the Control</a>
+</li>
+<li>
+<a href="#To+Compile+the+Page+Flow">To Compile the Page Flow</a>
</li>
<li>
<a href="#To+Start+the+Tomcat+Server">To Start the Tomcat Server</a>
@@ -308,8 +308,14 @@
<li>
<a href="#To+Test+the+Control">To Test the Control</a>
</li>
+<li>
+<a href="#To+Shutdown+the+Tomcat+Server">To Shutdown the Tomcat Server</a>
+</li>
</ul>
</li>
+<li>
+<a href="#Step+3%3A+Add+a+Parameterized+Method+to+the+Control">Step 3: Add a
Parameterized Method to the Control</a>
+</li>
</ul>
<a name="N1000C"></a><a name="intro"></a>
@@ -335,103 +341,98 @@
</ul>
</div>
+<a name="N10031"></a><a name="Assumptions+Made+in+This+Tutorial"></a>
+<h4>Assumptions Made in This Tutorial</h4>
+<div style="margin-left: 0 ; border: 2px">
+<p>The following tutorial assumes that you are working on a Windows machine.
But, with a little common sense, it is easy to run through the tutorial on a
Unix machine. For example, when the tutorial tells you to run the file
beehiveUser.cmd, Unix users should run the file beehiveUser.sh.</p>
+</div>
</div>
-<a name="N10032"></a><a name="step1"></a>
-<h3>Step 1: Begin the Controls Tutorial</h3>
-<div style="margin-left: 0 ; border: 2px">
-<a name="N10038"></a><a
name="Note+on+the+current+state+of+the+Controls+tutorial"></a>
-<h4>Note on the current state of the Controls tutorial</h4>
+<a name="N1003C"></a><a name="step1"></a>
+<h3>Step 1: Begin the Page Flow Tutorial</h3>
<div style="margin-left: 0 ; border: 2px">
-<p>The Control Tutorial is a work in progress. Please email comments to Steve
Hanson at <span class="codefrag">steveh at bea.com</span>.</p>
-</div>
-<a name="N10045"></a><a name="Download+and+Install+JDK5"></a>
-<h4>Download and Install JDK5</h4>
+<a name="N10042"></a><a name="To+Download+and+Install+J2SE5"></a>
+<h4>To Download and Install J2SE5</h4>
<div style="margin-left: 0 ; border: 2px">
-<p>If you do not have JDK5 installed on your machine, visit <a target="_blank"
href="http://java.sun.com/j2se/1.5.0/download.jsp";>http://java.sun.com/j2se/1.5.0/download.jsp</a>
and download the latest version of JDK5.</p>
-<p>
- <!--[tbd: better instructions]-->
-
-</p>
+<p>If you do not have J2SE5 installed, visit <a target="_blank"
href="http://java.sun.com/j2se/1.5.0/download.jsp";>http://java.sun.com/j2se/1.5.0/download.jsp</a>.
+ </p>
+<p>Download and install the latest version of J2SE5.</p>
</div>
-<a name="N10058"></a><a
name="Download+and+Install+SVN+%28Subversion+Source+Control%29"></a>
-<h4>Download and Install SVN (Subversion Source Control)</h4>
+<a name="N10053"></a><a name="To+Install+ANT+1.6.2"></a>
+<h4>To Install ANT 1.6.2</h4>
<div style="margin-left: 0 ; border: 2px">
-<p>Visit <a target="_blank"
href="http://subversion.tigris.org";>http://subversion.tigris.org</a> and
install the SVN source control system.<!--[tbd]-->
+<p>If you do not have Ant 1.6.2 installed, visit <a target="_blank"
href="http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/ant/apache-ant-1.6.2-bin.zip";>http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/ant/apache-ant-1.6.2-bin.zip</a>.
</p>
+<p>Download the ZIP file and unzip it on your machine.</p>
</div>
-<a name="N10068"></a><a name="Download+and+Install+Beehive"></a>
-<h4>Download and Install Beehive</h4>
+<a name="N10064"></a><a name="To+Download+and+Install+Tomcat+5"></a>
+<h4>To Download and Install Tomcat 5</h4>
<div style="margin-left: 0 ; border: 2px">
-<p>
- Create a directory called <span
class="codefrag">beehive-src</span> on your C: drive. Confirm that the the
following directory structure exists: <span
class="codefrag">C:/beehive-src</span>. This directory will store the Beehive
source and all of your Beehive projects. </p>
-<p>Open a command shell.</p>
-<p>At the command prompt, enter: <span class="codefrag">cd beehive-src</span>
-
-</p>
-<p>At the command prompt, enter: <span class="codefrag">svn checkout
http://svn.apache.org/repos/asf/incubator/beehive/trunk/</span>
-
-</p>
-<p>Wait a few minutes while the Beehive source is downloaded to your local
machine.</p>
-<p>At the command prompt, enter: <span class="codefrag">exit</span>
-
+<p>If you do not have Tomcat 5 installed, visit <a target="_blank"
href="http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/tomcat/jakarta-tomcat-5.0.25.zip";>http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/tomcat/jakarta-tomcat-5.0.25.zip</a>
</p>
+<p>Download the ZIP file and unzip it on your machine.</p>
</div>
-<a name="N10090"></a><a name="Install+ANT+"></a>
-<h4>Install ANT </h4>
+<a name="N10074"></a><a
name="To+Download+and+Install+a+Beehive+Binary+Distribution"></a>
+<h4>To Download and Install a Beehive Binary Distribution</h4>
<div style="margin-left: 0 ; border: 2px">
-<p>Create a directory named <span class="codefrag">installed</span>at <span
class="codefrag">C:/beehive-src/trunk/installed</span>.</p>
-<p>Unzip the file <span
class="codefrag">C:/beehive-src/trunk/external/ant/apache-ant-1.6.2-bin.zip</span>
into <span class="codefrag">C:/beehive-src/Beehive/installed</span>.</p>
-<p>After the file has unzipped, confirm that the following directory structure
exists: <span
class="codefrag">C:/beehive-src/trunk/installed/apache-ant-1.6.2</span>.</p>
-</div>
-<a name="N100AF"></a><a name="Run+the+"></a>
-<h4>Run the bootstrap Target</h4>
-<div style="margin-left: 0 ; border: 2px">
-<p>At the command prompt, enter: <span class="codefrag">set
JAVA_HOME=C:\jdk1.5.0</span>
-
-</p>
-<p>At the command prompt, enter: <span class="codefrag">set
BEEHIVE_HOME=C:\beehive-src\trunk</span>
-
-</p>
-<p>At the command prompt, enter: <span class="codefrag">cd
C:\beehive-src\trunk</span>
-
-</p>
-<p>At the command prompt, enter: <span class="codefrag">beehiveEnv.cmd</span>
-
-</p>
-<p>At the command prompt, enter: <span class="codefrag">ant bootstrap</span>
-
-</p>
+<p>Visit [todo: distribution download link] and download the latest binary
distribution of Beehive.</p>
+<p>Unzip the distribution file on your machine</p>
</div>
-<a name="N100D7"></a><a name="Compile+Beehive"></a>
-<h4>Compile Beehive</h4>
+<a name="N10081"></a><a name="To+Set+up+the+Development+Environment"></a>
+<h4>To Set up the Development Environment</h4>
<div style="margin-left: 0 ; border: 2px">
-<p>At the command prompt, enter: <span class="codefrag">ant deploy</span>
+<p>Open the directory where you installed the Beehive distribution. Open the
file <span class="codefrag">beehiveUser.cmd</span> in a text editor. Edit
<span class="codefrag">beehiveUser.cmd</span> to fit your local environment.
The following environmental variables must be set to the appropriate paths on
your machine: <span class="codefrag">BEEHIVE_HOME</span>, <span
class="codefrag">JAVA_HOME</span>, <span class="codefrag">ANT_HOME</span>, and
<span class="codefrag">CATALINA_HOME</span>. The following example shows how
to edit <span class="codefrag">beehiveUser.cmd</span> for a typical
environment.</p>
+<pre class="code">REM the root of Beehive distribution
+set BEEHIVE_HOME=C:\beehive-alpha
+
+REM location of a JDK
+set JAVA_HOME=C:\jdk1.5.0
+
+REM location of Ant
+set ANT_HOME=C:\apache-ant-1.6.2
+
+REM location of Tomcat
+set CATALINA_HOME=C:\jakarta-tomcat-5.0.25</pre>
+<p>When you finished editing <span class="codefrag">beehiveUser.cmd</span>,
save and close the file.</p>
+<p>Open a command shell.</p>
+<p>cd to the directory where <span class="codefrag">beehiveUser.cmd</span>
resides (= the directory where you installed the Beehive distribution).</p>
+<p>At the command prompt, enter: <span class="codefrag">beehiveUser.cmd</span>
</p>
-<p>Leave this command shell open so you can use it throughout the tutorial.</p>
+<p>Leave the command shell open to use throughout the tutorial</p>
</div>
</div>
-<a name="N100E8"></a><a name="step_2"></a>
+<a name="N100BE"></a><a name="step_2"></a>
<h3>Step 2: Create Control Implementation and Interface Files</h3>
<div style="margin-left: 0 ; border: 2px">
-<a name="N100EE"></a><a name="Introduction"></a>
+<a name="N100C4"></a><a name="Introduction"></a>
<h4>Introduction</h4>
<div style="margin-left: 0 ; border: 2px">
-<p>[tbd]</p>
+<p>A Beehive Control consists of two files: an interface file (with the JAVA
file extension) and an implementation file (with the JCS file extension). The
interface file is the public face of your control. It lists all of the methods
which can be invoked by users. The implementation file contains the
implementation code for the methods listed in the interface file.</p>
+</div>
+<a name="N100CE"></a><a name="To+Create+a+Control+Application+Folder"></a>
+<h4>To Create a Control Application Folder</h4>
+<div style="margin-left: 0 ; border: 2px">
+<p>In the directory <span class="codefrag">CATALINA_HOME/webapps/</span>,
create a directory called <span class="codefrag">control_tutorial</span>.</p>
</div>
-<a name="N100F8"></a><a name="To+Create+a+Control%27s+Implementation+File"></a>
-<h4>To Create a Control's Implementation File</h4>
+<a name="N100DE"></a><a
name="To+Add+Beehive+Runtime+JARs+to+Your+Application."></a>
+<h4>To Add Beehive Runtime JARs to Your Application.</h4>
+<div style="margin-left: 0 ; border: 2px">
+<p>In this step you will assemble the runtime resources for your Control.
Most of these files are included in the WEB-INF directory. It includes JAR
files with the JSP tag handler classes, the Controls runtime JAR, etc.
<!--[tbd: for a complete list see...]--></p>
+<p>Using the command shell opened in the previous step, at the command prompt,
enter: </p>
+<pre class="code">ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml
deploy.beehive.webapp.runtime
-Dwebapp.dir=%CATALINA_HOME%\webapps\control_tutorial</pre>
+</div>
+<a name="N100F1"></a><a
name="To+Create+the+Control%27s+Implementation+File"></a>
+<h4>To Create the Control's Implementation File</h4>
<div style="margin-left: 0 ; border: 2px">
<p>In this step you will create the implementation file for your Beehive
Control. This is a JAVA file, that contains the bulk of your Control's working
code.</p>
-<p>In the directory <span
class="codefrag">C:/beehive-src/trunk/installed/jakarta-tomcat-5.0.25/webapps</span>,
create a directory called <span class="codefrag">control_tutorial</span>.</p>
-<p>In the directory <span
class="codefrag">C:/beehive-src/trunk/installed/jakarta-tomcat-5.0.25/webapps/control_tutorial</span>,
create a directory called <span class="codefrag">hellocontrol</span>.</p>
-<p>In the directory <span
class="codefrag">C:/beehive-src/trunk/installed/jakarta-tomcat-5.0.25/webapps/control_tutorial/hellocontrol</span>,
create a file called <span class="codefrag">HelloImpl.jcs</span>.</p>
+<p>In the directory <span
class="codefrag">CATALINA_HOME/webapps/control_tutorial/WEB-INF</span>, create
a directory called <span class="codefrag">src</span>.</p>
+<p>In the directory <span
class="codefrag">CATALINA_HOME/webapps/control_tutorial/WEB-INF/src</span>,
create a directory called <span class="codefrag">hellocontrol</span>.</p>
+<p>In the directory <span
class="codefrag">CATALINA_HOME/webapps/control_tutorial/WEB-INF/src/hellocontrol</span>,
create a file called <span class="codefrag">HelloImpl.jcs</span>.</p>
<p>In a text editor (or your IDE of choice), open the file HelloImpl.jcs.</p>
<p>Edit HelloImpl.jcs so it appears as follows.</p>
-<pre class="code">
-package hellocontrol;
+<pre class="code">package hellocontrol;
import org.apache.beehive.controls.api.bean.*;
@@ -442,18 +443,17 @@
{
return "Hello, World!";
}
-}
- </pre>
+}</pre>
+<p>Save and close <span class="codefrag">HelloImpl.jcs</span>.</p>
</div>
-<a name="N10128"></a><a name="To+Create+the+Control%27s+Interface+File"></a>
+<a name="N10127"></a><a name="To+Create+the+Control%27s+Interface+File"></a>
<h4>To Create the Control's Interface File</h4>
<div style="margin-left: 0 ; border: 2px">
<p>The interface file is a JAVA file, that defines the public face of your
control. <!--[tbd]-->
</p>
-<p>In the directory <span
class="codefrag">C:/beehive-src/trunk/installed/jakarta-tomcat-5.0.25/webapps/control_tutorial</span>,
create a file named <span class="codefrag">Hello.java</span>.</p>
+<p>In the directory <span
class="codefrag">CATALINA_HOME/webapps/control_tutorial/WEB-INF/src/hellocontrol</span>,
create a file named <span class="codefrag">Hello.java</span>.</p>
<p>Edit Hello.java so it looks like the following.</p>
-<pre class="code">
-package hellocontrol;
+<pre class="code">package hellocontrol;
import org.apache.beehive.controls.api.bean.ControlInterface;
@@ -461,30 +461,19 @@
public interface Hello
{
public String hello();
-}
- </pre>
-</div>
-<a name="N10145"></a><a name="To+Create+the+WEB-INF+directory"></a>
-<h4>To Create the WEB-INF directory</h4>
-<div style="margin-left: 0 ; border: 2px">
-<p>At the command prompt, enter: <span class="codefrag">ant -f
C:\beehive-src\trunk\netui\ant\webappTemplate.xml
-Dwebapp.dist.dir=C:\beehive-src\trunk\installed\jakarta-tomcat-5.0.25\webapps\control_tutorial</span>
-
-</p>
+}</pre>
</div>
-<a name="N10152"></a><a name="Edit+a+JSP+Page+to+Test+the+Control"></a>
-<h4>Edit a JSP Page to Test the Control</h4>
+<a name="N10144"></a><a name="To+Create+a+JSP+Page+to+Test+the+Control"></a>
+<h4>To Create a JSP Page to Test the Control</h4>
<div style="margin-left: 0 ; border: 2px">
<p>To test your Beehive Control, you need to call the control from some other
resource, such as a JAVA application, JSP page, or Page Flow web application.
In this step you will call the
control from a JSP page.
</p>
-<p>In the directory <span
class="codefrag">C:/beehive-src/trunk/installed/jakarta-tomcat-5.0.25/webapps/control_tutorial</span>,
edit the file named <span class="codefrag">index.jsp</span>.
+<p>In the directory <span
class="codefrag">CATALINA_HOME/webapps/control_tutorial/WEB-INF/src/hellocontrol</span>,
edit the file named <span class="codefrag">hello.jsp</span>.
</p>
<p>Edit index.jsp so it appears as follows.</p>
-<pre class="code">
-<%@ page language="java" contentType="text/html;charset=UTF-8"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0";
prefix="netui-data"%>
+<pre class="code"><%@ page language="java"
contentType="text/html;charset=UTF-8"%>
<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0";
prefix="netui"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0";
prefix="netui-template"%>
<netui:html>
<head>
<title>Web Application Page</title>
@@ -496,33 +485,44 @@
<%= helloBean.hello() %>
</p>
</netui:body>
-</netui:html>
- </pre>
+</netui:html></pre>
</div>
-<a name="N1016D"></a><a name="Compile+the+Control"></a>
-<h4>Compile the Control</h4>
+<a name="N1015F"></a><a name="To+Compile+the+Page+Flow"></a>
+<h4>To Compile the Page Flow</h4>
<div style="margin-left: 0 ; border: 2px">
-<p>At the command prompt, enter: <span class="codefrag">ant -f
C:\beehive-src\trunk\test\ant\buildWebapp.xml build.webapp
-Dwebapp.dir=C:\beehive-src\trunk\installed\jakarta-tomcat-5.0.25\webapps\control_tutorial</span>
-
-</p>
+<p>You are now ready to compile the Page Flow.</p>
+<p>At the command prompt, enter:</p>
+<pre class="code">ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml build.webapp
-Dwebapp.dir=%CATALINA_HOME%\webapps\control_tutorial</pre>
</div>
-<a name="N1017A"></a><a name="To+Start+the+Tomcat+Server"></a>
+<a name="N10171"></a><a name="To+Start+the+Tomcat+Server"></a>
<h4>To Start the Tomcat Server</h4>
<div style="margin-left: 0 ; border: 2px">
-<p>At the command prompt, enter: <span
class="codefrag">C:\beehive-src\trunk\installed\jakarta-tomcat-5.0.25\bin\startup.bat</span>
-
-</p>
+<p>At the command prompt, enter:</p>
+<pre class="code">%CATALINA_HOME%\bin\startup.bat</pre>
</div>
-<a name="N10187"></a><a name="To+Test+the+Control"></a>
+<a name="N10180"></a><a name="To+Test+the+Control"></a>
<h4>To Test the Control</h4>
<div style="margin-left: 0 ; border: 2px">
-<p>Open a web browser and enter the following in the address bar: <span
class="codefrag">http://localhost:8080/control_tutorial/index.jsp</span>
+<p>Open a web browser and enter the following in the address bar: <span
class="codefrag">http://localhost:8080/control_tutorial/hello.jsp</span>
</p>
<p>You will be directed to the index.jsp page.</p>
<p>Note the message on the page: "Hello, World!"</p>
<p>This message is provided by the Hello control.</p>
</div>
+<a name="N10196"></a><a name="To+Shutdown+the+Tomcat+Server"></a>
+<h4>To Shutdown the Tomcat Server</h4>
+<div style="margin-left: 0 ; border: 2px">
+<p>At the command prompt, enter:
+ </p>
+<pre class="code">%CATALINA_HOME%\bin\shutdown.bat</pre>
+</div>
+</div>
+
+<a name="N101A6"></a><a
name="Step+3%3A+Add+a+Parameterized+Method+to+the+Control"></a>
+<h3>Step 3: Add a Parameterized Method to the Control</h3>
+<div style="margin-left: 0 ; border: 2px">
+<p>[TODO: This step is coming soon.]</p>
</div>
<!--<section id="step_3">
<title>Step 3: Navigation</title>
Modified: incubator/beehive/site/build/site/pageflow/tutorial_pageflow.html
==============================================================================
--- incubator/beehive/site/build/site/pageflow/tutorial_pageflow.html
(original)
+++ incubator/beehive/site/build/site/pageflow/tutorial_pageflow.html Mon Nov
1 13:50:04 2004
@@ -262,7 +262,7 @@
<a href="#step1">Step 1: Begin the Page Flow Tutorial</a>
<ul class="minitoc">
<li>
-<a href="#Download+and+Install+J2SE5">Download and Install J2SE5</a>
+<a href="#To+Download+and+Install+J2SE5">To Download and Install J2SE5</a>
</li>
<li>
<a href="#To+Install+ANT+1.6.2">To Install ANT 1.6.2</a>
@@ -415,8 +415,8 @@
<a name="N10039"></a><a name="step1"></a>
<h3>Step 1: Begin the Page Flow Tutorial</h3>
<div style="margin-left: 0 ; border: 2px">
-<a name="N1003F"></a><a name="Download+and+Install+J2SE5"></a>
-<h4>Download and Install J2SE5</h4>
+<a name="N1003F"></a><a name="To+Download+and+Install+J2SE5"></a>
+<h4>To Download and Install J2SE5</h4>
<div style="margin-left: 0 ; border: 2px">
<p>If you do not have J2SE5 installed, visit <a target="_blank"
href="http://java.sun.com/j2se/1.5.0/download.jsp";>http://java.sun.com/j2se/1.5.0/download.jsp</a>.
</p>
Modified:
incubator/beehive/site/src/documentation/content/xdocs/controls/tutorial_controls.xml
==============================================================================
---
incubator/beehive/site/src/documentation/content/xdocs/controls/tutorial_controls.xml
(original)
+++
incubator/beehive/site/src/documentation/content/xdocs/controls/tutorial_controls.xml
Mon Nov 1 13:50:04 2004
@@ -19,80 +19,82 @@
<li>How to create custom metadata annotations</li>
</ul>
</section>
- </section>
- <section id="step1">
- <title>Step 1: Begin the Controls Tutorial</title>
<section>
- <title>Note on the current state of the Controls
tutorial</title>
- <p>The Control Tutorial is a work in progress. Please email
comments to Steve Hanson at <code>steveh at bea.com</code>.</p>
+ <title>Assumptions Made in This Tutorial</title>
+ <p>The following tutorial assumes that you are working on a
Windows machine. But, with a little common sense, it is easy to run through
the tutorial on a Unix machine. For example, when the tutorial tells you to
run the file beehiveUser.cmd, Unix users should run the file beehiveUser.sh.</p>
</section>
+ </section>
+ <section id="step1">
+ <title>Step 1: Begin the Page Flow Tutorial</title>
<section>
- <title>Download and Install JDK5</title>
- <p>If you do not have JDK5 installed on your machine, visit
<fork
href="http://java.sun.com/j2se/1.5.0/download.jsp";>http://java.sun.com/j2se/1.5.0/download.jsp</fork>
and download the latest version of JDK5.</p>
- <p>
- <!--[tbd: better instructions]-->
+ <title>To Download and Install J2SE5</title>
+ <p>If you do not have J2SE5 installed, visit <fork
href="http://java.sun.com/j2se/1.5.0/download.jsp";>http://java.sun.com/j2se/1.5.0/download.jsp</fork>.
</p>
+ <p>Download and install the latest version of J2SE5.</p>
</section>
<section>
- <title>Download and Install SVN (Subversion Source
Control)</title>
- <p>Visit <fork
href="http://subversion.tigris.org";>http://subversion.tigris.org</fork> and
install the SVN source control system.<!--[tbd]-->
+ <title>To Install ANT 1.6.2</title>
+ <p>If you do not have Ant 1.6.2 installed, visit <fork
href="http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/ant/apache-ant-1.6.2-bin.zip";>http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/ant/apache-ant-1.6.2-bin.zip</fork>.
</p>
+ <p>Download the ZIP file and unzip it on your machine.</p>
</section>
<section>
- <title>Download and Install Beehive</title>
- <p>
- Create a directory called
<code>beehive-src</code> on your C: drive. Confirm that the the following
directory structure exists: <code>C:/beehive-src</code>. This directory will
store the Beehive source and all of your Beehive projects.
</p>
- <p>Open a command shell.</p>
- <p>At the command prompt, enter: <code>cd beehive-src</code>
- </p>
- <p>At the command prompt, enter: <code>svn checkout
http://svn.apache.org/repos/asf/incubator/beehive/trunk/</code>
- </p>
- <p>Wait a few minutes while the Beehive source is downloaded
to your local machine.</p>
- <p>At the command prompt, enter: <code>exit</code>
- </p>
+ <title>To Download and Install Tomcat 5</title>
+ <p>If you do not have Tomcat 5 installed, visit <fork
href="http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/tomcat/jakarta-tomcat-5.0.25.zip";>http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/tomcat/jakarta-tomcat-5.0.25.zip</fork></p>
+ <p>Download the ZIP file and unzip it on your machine.</p>
</section>
<section>
- <title>Install ANT </title>
- <p>Create a directory named <code>installed</code>at
<code>C:/beehive-src/trunk/installed</code>.</p>
- <p>Unzip the file
<code>C:/beehive-src/trunk/external/ant/apache-ant-1.6.2-bin.zip</code> into
<code>C:/beehive-src/Beehive/installed</code>.</p>
- <p>After the file has unzipped, confirm that the following
directory structure exists:
<code>C:/beehive-src/trunk/installed/apache-ant-1.6.2</code>.</p>
+ <title>To Download and Install a Beehive Binary
Distribution</title>
+ <p>Visit [todo: distribution download link] and download the
latest binary distribution of Beehive.</p>
+ <p>Unzip the distribution file on your machine</p>
</section>
<section>
- <title>Run the <code>bootstrap</code> Target</title>
- <p>At the command prompt, enter: <code>set
JAVA_HOME=C:\jdk1.5.0</code>
- </p>
- <p>At the command prompt, enter: <code>set
BEEHIVE_HOME=C:\beehive-src\trunk</code>
- </p>
- <p>At the command prompt, enter: <code>cd
C:\beehive-src\trunk</code>
- </p>
- <p>At the command prompt, enter: <code>beehiveEnv.cmd</code>
- </p>
- <p>At the command prompt, enter: <code>ant bootstrap</code>
- </p>
- </section>
- <section>
- <title>Compile Beehive</title>
- <p>At the command prompt, enter: <code>ant deploy</code>
+ <title>To Set up the Development Environment</title>
+ <p>Open the directory where you installed the Beehive
distribution. Open the file <code>beehiveUser.cmd</code> in a text editor.
Edit <code>beehiveUser.cmd</code> to fit your local environment. The following
environmental variables must be set to the appropriate paths on your machine:
<code>BEEHIVE_HOME</code>, <code>JAVA_HOME</code>, <code>ANT_HOME</code>, and
<code>CATALINA_HOME</code>. The following example shows how to edit
<code>beehiveUser.cmd</code> for a typical environment.</p>
+<source>REM the root of Beehive distribution
+set BEEHIVE_HOME=C:\beehive-alpha
+
+REM location of a JDK
+set JAVA_HOME=C:\jdk1.5.0
+
+REM location of Ant
+set ANT_HOME=C:\apache-ant-1.6.2
+
+REM location of Tomcat
+set CATALINA_HOME=C:\jakarta-tomcat-5.0.25</source>
+ <p>When you finished editing <code>beehiveUser.cmd</code>,
save and close the file.</p>
+ <p>Open a command shell.</p>
+ <p>cd to the directory where <code>beehiveUser.cmd</code>
resides (= the directory where you installed the Beehive distribution).</p>
+ <p>At the command prompt, enter: <code>beehiveUser.cmd</code>
</p>
- <p>Leave this command shell open so you can use it throughout
the tutorial.</p>
+ <p>Leave the command shell open to use throughout the
tutorial</p>
</section>
</section>
<section id="step_2">
<title>Step 2: Create Control Implementation and Interface
Files</title>
<section>
<title>Introduction</title>
- <p>[tbd]</p>
+ <p>A Beehive Control consists of two files: an interface file
(with the JAVA file extension) and an implementation file (with the JCS file
extension). The interface file is the public face of your control. It lists
all of the methods which can be invoked by users. The implementation file
contains the implementation code for the methods listed in the interface
file.</p>
+ </section>
+ <section>
+ <title>To Create a Control Application Folder</title>
+ <p>In the directory <code>CATALINA_HOME/webapps/</code>,
create a directory called <code>control_tutorial</code>.</p>
</section>
<section>
- <title>To Create a Control's Implementation File</title>
+ <title>To Add Beehive Runtime JARs to Your Application.</title>
+ <p>In this step you will assemble the runtime resources for
your Control. Most of these files are included in the WEB-INF directory. It
includes JAR files with the JSP tag handler classes, the Controls runtime JAR,
etc. <!--[tbd: for a complete list see...]--></p>
+ <p>Using the command shell opened in the previous step, at the
command prompt, enter: </p>
+ <source>ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml
deploy.beehive.webapp.runtime
-Dwebapp.dir=%CATALINA_HOME%\webapps\control_tutorial</source>
+ </section>
+ <section>
+ <title>To Create the Control's Implementation File</title>
<p>In this step you will create the implementation file for
your Beehive Control. This is a JAVA file, that contains the bulk of your
Control's working code.</p>
- <p>In the directory
<code>C:/beehive-src/trunk/installed/jakarta-tomcat-5.0.25/webapps</code>,
create a directory called <code>control_tutorial</code>.</p>
- <p>In the directory
<code>C:/beehive-src/trunk/installed/jakarta-tomcat-5.0.25/webapps/control_tutorial</code>,
create a directory called <code>hellocontrol</code>.</p>
- <p>In the directory
<code>C:/beehive-src/trunk/installed/jakarta-tomcat-5.0.25/webapps/control_tutorial/hellocontrol</code>,
create a file called <code>HelloImpl.jcs</code>.</p>
+ <p>In the directory
<code>CATALINA_HOME/webapps/control_tutorial/WEB-INF</code>, create a directory
called <code>src</code>.</p>
+ <p>In the directory
<code>CATALINA_HOME/webapps/control_tutorial/WEB-INF/src</code>, create a
directory called <code>hellocontrol</code>.</p>
+ <p>In the directory
<code>CATALINA_HOME/webapps/control_tutorial/WEB-INF/src/hellocontrol</code>,
create a file called <code>HelloImpl.jcs</code>.</p>
<p>In a text editor (or your IDE of choice), open the file
HelloImpl.jcs.</p>
<p>Edit HelloImpl.jcs so it appears as follows.</p>
- <source><![CDATA[
-package hellocontrol;
+ <source><![CDATA[package hellocontrol;
import org.apache.beehive.controls.api.bean.*;
@@ -103,17 +105,16 @@
{
return "Hello, World!";
}
-}
- ]]></source>
+}]]></source>
+ <p>Save and close <code>HelloImpl.jcs</code>.</p>
</section>
<section>
<title>To Create the Control's Interface File</title>
<p>The interface file is a JAVA file, that defines the public
face of your control. <!--[tbd]-->
</p>
- <p>In the directory
<code>C:/beehive-src/trunk/installed/jakarta-tomcat-5.0.25/webapps/control_tutorial</code>,
create a file named <code>Hello.java</code>.</p>
+ <p>In the directory
<code>CATALINA_HOME/webapps/control_tutorial/WEB-INF/src/hellocontrol</code>,
create a file named <code>Hello.java</code>.</p>
<p>Edit Hello.java so it looks like the following.</p>
- <source><![CDATA[
-package hellocontrol;
+ <source><![CDATA[package hellocontrol;
import org.apache.beehive.controls.api.bean.ControlInterface;
@@ -121,27 +122,18 @@
public interface Hello
{
public String hello();
-}
- ]]></source>
- </section>
- <section>
- <title>To Create the WEB-INF directory</title>
- <p>At the command prompt, enter: <code>ant -f
C:\beehive-src\trunk\netui\ant\webappTemplate.xml
-Dwebapp.dist.dir=C:\beehive-src\trunk\installed\jakarta-tomcat-5.0.25\webapps\control_tutorial</code>
- </p>
- </section>
+}]]></source>
+ </section>
<section>
- <title>Edit a JSP Page to Test the Control</title>
+ <title>To Create a JSP Page to Test the Control</title>
<p>To test your Beehive Control, you need to call the control
from some other resource, such as a JAVA application, JSP page, or Page Flow
web application. In this step you will call the
control from a JSP page.
</p>
- <p>In the directory
<code>C:/beehive-src/trunk/installed/jakarta-tomcat-5.0.25/webapps/control_tutorial</code>,
edit the file named <code>index.jsp</code>.
+ <p>In the directory
<code>CATALINA_HOME/webapps/control_tutorial/WEB-INF/src/hellocontrol</code>,
edit the file named <code>hello.jsp</code>.
</p>
<p>Edit index.jsp so it appears as follows.</p>
- <source><![CDATA[
-<%@ page language="java" contentType="text/html;charset=UTF-8"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0";
prefix="netui-data"%>
+ <source><![CDATA[<%@ page language="java"
contentType="text/html;charset=UTF-8"%>
<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0"; prefix="netui"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0";
prefix="netui-template"%>
<netui:html>
<head>
<title>Web Application Page</title>
@@ -153,28 +145,38 @@
<%= helloBean.hello() %>
</p>
</netui:body>
-</netui:html>
- ]]></source>
+</netui:html>]]></source>
</section>
<section>
- <title>Compile the Control</title>
- <p>At the command prompt, enter: <code>ant -f
C:\beehive-src\trunk\test\ant\buildWebapp.xml build.webapp
-Dwebapp.dir=C:\beehive-src\trunk\installed\jakarta-tomcat-5.0.25\webapps\control_tutorial</code>
- </p>
+ <title>To Compile the Page Flow</title>
+ <p>You are now ready to compile the Page Flow.</p>
+ <p>At the command prompt, enter:</p>
+ <source>ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml build.webapp
-Dwebapp.dir=%CATALINA_HOME%\webapps\control_tutorial</source>
</section>
<section>
<title>To Start the Tomcat Server</title>
- <p>At the command prompt, enter:
<code>C:\beehive-src\trunk\installed\jakarta-tomcat-5.0.25\bin\startup.bat</code>
- </p>
+ <p>At the command prompt, enter:</p>
+ <source>%CATALINA_HOME%\bin\startup.bat</source>
</section>
<section>
<title>To Test the Control</title>
- <p>Open a web browser and enter the following in the address
bar: <code>http://localhost:8080/control_tutorial/index.jsp</code>
+ <p>Open a web browser and enter the following in the address
bar: <code>http://localhost:8080/control_tutorial/hello.jsp</code>
</p>
<p>You will be directed to the index.jsp page.</p>
<p>Note the message on the page: "Hello, World!"</p>
<p>This message is provided by the Hello control.</p>
</section>
+ <section>
+ <title>To Shutdown the Tomcat Server</title>
+ <p>At the command prompt, enter:
+ </p>
+ <source>%CATALINA_HOME%\bin\shutdown.bat</source>
+ </section>
</section>
+ <section>
+ <title>Step 3: Add a Parameterized Method to the
Control</title>
+ <p>[TODO: This step is coming soon.]</p>
+ </section>
<!--<section id="step_3">
<title>Step 3: Navigation</title>
<section>
