jon 01/05/09 20:39:50
Modified: docs getting-started-tdk.html getting-started.html
xdocs getting-started-tdk.xml getting-started.xml
Log:
documentation patches thanks to:
Kurt Schrader <[EMAIL PROTECTED]>
Revision Changes Path
1.4 +327 -63 jakarta-turbine/docs/getting-started-tdk.html
Index: getting-started-tdk.html
===================================================================
RCS file: /home/cvs/jakarta-turbine/docs/getting-started-tdk.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- getting-started-tdk.html 2001/05/08 01:08:08 1.3
+++ getting-started-tdk.html 2001/05/10 03:39:49 1.4
@@ -11,10 +11,10 @@
<head>
<meta http-equiv="Content-Type" content="text/html;
charset=iso-8859-1"/>
- <meta name="author"
value="Turbine Documentation Team">
- <meta name="email" value="[EMAIL PROTECTED]">
+ <meta name="author" value="Kurt
Schrader">
+ <meta name="email" value="[EMAIL PROTECTED]">
- <title>Turbine - Turbine Getting Started</title>
+ <title>Turbine - Turbine Development Kit Getting Started</title>
</head>
<body bgcolor="#ffffff" text="#000000" link="#525D76">
@@ -146,61 +146,57 @@
<table
border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
- <a name="The really big picture:"><strong>The really big
picture:</strong></a>
+ <a name="Introduction"><strong>Introduction</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
-As you are developing your new Turbine application, you will
-be working mainly in three our four areas:
+The Turbine Development Kit allows you to begin developing on/evaluating
+Turbine and its diverse set of components almost immediately. It includes
+almost everything needed to begin Turbine development. Installing it
+should be the first step in your evaluation of Turbine.
</p>
- <dl>
- <dd>
- 1. design and create your object model
- </dd>
- <dd>
- 2. create ApplicationTools (tools used in conjunction with
- the pull service)
- </dd>
- <dd>
- 3. create templates that use the ApplicationTools
- </dd>
- <dd>
- (1.5 in some cases you may be creating services that sit
- roughly between the object model and the
- ApplicationTools.
- </dd>
-</dl>
<p>
-Item 1 is the Model in the Model-View-Controller design
-pattern. In Turbine, this is a combination of the
-project-schema.xml file you will create to define your
-object model, and the various files Torque will create from
-your project-schema.xml.
+Much of this getting started guide has been put together using information
+found elsewhere on the website. It should not be seen as a replacement for
+reading the plethora of information available about Turbine, as new users seem
+to always do. It simply attempts to get a first time user up and running with
+the TDK quickly and with a general knowledge of how it works. As usual, please
+be sure that you have scoured the entire website for information before asking
+questions on the mailing list. Also, it is suggested that you read this entire
+page before attemping to install the TDK.
</p>
- <p>
-Item 2, roughly speaking, is a bridge between your object
-model and the templates. If you are in a large shop, this
-is where the programmers will create an API for the web
-designers. If you are in a small shop, you still want to
-use the Pull model because it will make it much easier to
-modify your web application down the road.
+ </blockquote>
+ </td></tr>
+ </table>
+ <table border="0" cellspacing="0"
cellpadding="2" width="100%">
+ <tr><td bgcolor="#525D76">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Prerequisites to using the TDK"><strong>Prerequisites to using
the TDK</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+Before using the TDK, you are going to need to have a Java Software
+Development Kit supporting Java version 1.2 or later installed on your machine.
+Sun's Java SDK can be downloaded from their website located
+<a href="http://java.sun.com/j2se/1.3/";>here.</a>
</p>
<p>
-Item 3 is the View. This is where you build the user
-interface for your web application. In Turbine these are
-typically Velocity templates.
+In order to do anything interesting with the TDK, you are also going to need a
+database that is compatable with the JDBC standard. The TDK currently comes
+with drivers for MySQL and Postgres. Other drivers can be downloaded from the
+vendor's websites located here:
</p>
<p>
-The Turbine servlet is the Controller. Item 1.5 is how
-you extend the functionality of the controller in very
-flexible ways.
+<li><a
href="http://technet.oracle.com/software/tech/java/sqlj_jdbc/software_index.htm";>Oracle
JDBC Drivers</a>.</li>
+<li><a href="http://instantdb.enhydra.org/";>InstantDB JDBC Drivers</a>.</li>
</p>
<p>
-You can use JSP instead of Velocity, in which case item 2
-will consist of JSP tag libraries, and item 3 will be JSP
-templates that use those tag libraries.
+Simply download this driver to a directory right now where you can remember
+where it is. We will make use of it later.
</p>
</blockquote>
</td></tr>
@@ -208,42 +204,310 @@
<table border="0" cellspacing="0"
cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
- <a name="Getting to know the TDK:"><strong>Getting to know the
TDK:</strong></a>
+ <a name="Downloading and Installing the TDK"><strong>Downloading and
Installing the TDK</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
-Download the latest TDK and install it.
+Unpack the TDK distribution into a directory of your choosing. On Windows, use
+WinZip to unpack the files and on Unix, something like:
</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+
+tar -xvzf tdk1-1a14.tar.gz
+
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
<p>
-Login with username 'turbine' and password 'turbine'
+should to the trick. This is all that you have to do to install the TDK, but
+now a sample app needs to be created in order to see what it can do.
</p>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table border="0" cellspacing="0"
cellpadding="2" width="100%">
+ <tr><td bgcolor="#525D76">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Creating your first Turbine application"><strong>Creating your
first Turbine application</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+Now that you have Turbine installed on your machine, you need to create a
+sample application in order to begin using it. This is done in the following
+manner:
+</p>
+ <p>
+1. Open up the file "build.properties" in the root TDK directory. Change the
+property "target.package" to the name of the package that you would like your
+java files to live in and the property "target.directory" to the directory that
+you would like your classes to be created in. These two values are usually a
+mirror of one another. Finally, change the property "turbine.app.name" to the
+name of the application that you would like to create. Usually this is the same
+as the identifier specified at the end of your target.package.
+</p>
+ <p>
+2. Set the JAVA_HOME environment value for your system. On *nix/BSD using the
+Bash shell, this can be done with:
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+
+export JAVA_HOME="/PATH/TO/JDK/"
+
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+3. Run the newapp script located in the root directory of the TDK installation.
+This script should be run with the name of your turbine app appended to it. For
+example:
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+
+./newapp.sh NEWAPP
+
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
<p>
-Insert a couple entries into the sample application, edit
-them, delete them. Play with Flux by adding a couple users,
-groups, roles, and permissions. These two examples are
-fairly basic web applications, but they contain all the
-ingredients of more complex applications.
+from your root TDK directory. This will create many of the files necessary for
+running your turbine app.
</p>
<p>
-Item 1: look at WEB-INF/build/project/*-schema.xml and at
-WEB-INF/src/java/org/mycompany/newapp/om/*Peer.java and at
-WEB-INF/src/sql/*
-These are the Model part of the picture.
+4. Once this initial set of classes has been created, you will need to go into
+the directory "/TDKROOT/webapps/APPNAME/WEB-INF/build/project" in order to edit
+your "APPNAME.properties" file. In this file you will need to specify things
+such as the type of database you are using and its connection info. This
+information is used to create the database you will be using and the classes
+used to access it. At this time you should also copy your JDBC drivers
+(renaming .zip files to .jar files, if necessary) into the
+"webapps/APPNAME/WEB-INF/lib" directory if you are using a database other than
+MySQL or Postgres. These files will be important when creating the database
+tables in the next step.
</p>
<p>
-Item 2: look at ...<br />
-TODO: need a pull version of the sample application so we
-can have an ApplicationTool to look at.
+5. Go to the directory "/TDKROOT/webapps/APPNAME/WEB-INF/build" and run the
+command "./build.sh init" This command MUST BE RUN before attempting to use
+Turbine. It creates the database tables and OM classes for accessing them.
</p>
<p>
-Item 3: look at ./templates/screens/*.vm to see examples
-of Velocity templates.
+6. Your first Turbine app has now been created! go back to the root directory
+of your TDK installation and type in "./bin/startup.sh" This will start the
+Tomcat servlet engine and make your application available.
</p>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table border="0" cellspacing="0"
cellpadding="2" width="100%">
+ <tr><td bgcolor="#525D76">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Accessing your Turbine application"><strong>Accessing your
Turbine application</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+Now that you have your Turbine application created and running by following the
+instructions above, point your browser to
+http://SERVERNAME:8080/APPNAME/servlet/APPNAME where SERVERNAME is the hostname
+of the machine running Tomcat, and APPNAME is the name of the application you
+created.
+</p>
<p>
-Item 1.5: look at the javadoc for TurbineSecurity as an
-example of the service
+The initial login screen should appear and you should login with username
+'turbine' and password 'turbine' This will bring you to the initial "Turbine
+Data Manager" layout. From here you can insert/delete/edit entries in the
+default database or create and manage users using Flux, the built-in user
+management system for Turbine. These are the example turbine apps.
+</p>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table border="0" cellspacing="0"
cellpadding="2" width="100%">
+ <tr><td bgcolor="#525D76">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Editing the Example App"><strong>Editing the Example
App</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+Look at the example app that you now have on your screen. The view that you are
+seeing actually consists of 4 different parts (top, bottom, menu and index) that
+were assembled for you on the fly by Velocity. In order to see how this works,
+you have to edit the file "webapps/APPNAME/templates/layouts/Default.vm" This
+file defines how the default layout is shown on your screen. As you can see,
+it is written as a fragment of HTML that will eventually be integrated into your
+final page. Editing this file will affect the layout of your entire
+application.
+</p>
+ <p>
+Knowing now how the page is laid out, go to the directory
+"webapps/APPNAME/templates/navigations" to see the files that will be inserted
+into the layout template above. Edit the file "DefaultBottom.vm", save your
+changes back, and reload your page. By doing this you should see whatever
+changes you have made to the file appear at the bottom of your layout. This
+change will also occur in all of the other pages on your site. Change to a
+different page to confirm this.
+</p>
+ <p>
+Now go into the directory "webapps/APPNAME/templates/screens" The files in this
+directory are the ones that replace the "$screen_placeholder" variable in
+the original layout. Open up the file "Index.vm" and you will see that a
+variable is defined called "$headings" that holds the strings for each of the
+headings on the Index page and that a variable called "$entries" is used
+to show the dynamic data on the page. This variable comes from the Java class
+file that is associated with this .vm page, as explained in the next paragraph.
+The Index.vm page also includes a number of functions that begin with #, such as
+"#entryCell(...)" These functions are replaced with HTML fragments at runtime,
+as defined in the "webapps/APPNAME/templates/GlobalMacros.vm" file. Look at
+this file to get an idea of what each of these methods do.
+</p>
+ <p>
+In order to view the Java file that is associated with the Index.vm, go to the
+directory "webapps/APPNAME/WEB-INF/src/java/PACKAGE/modules/screens" A quick
+look in this directory should show you that each page with dynamic data in it
+has an associated class file in this directory. Open the file "Index.java" and
+look over its contents. As you can see, the "doBuildTemplate" method creates a
+variable called "entries" and associates the data that it pulls from the
+database in the "getEntries" method into it. In the case of the Index.vm page,
+this corresponds to all of the entries from our example database. The
+"context.put("entries", getEntries())" method places the data and the associated
+handle for it into our session context so that it can be accessed from our .vm
+pages. You would edit this file to change the behavior of a given page. More
+information on building sites with Velocity is available
+<a href="velocity-site.html">here.</a>
+</p>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table border="0" cellspacing="0"
cellpadding="2" width="100%">
+ <tr><td bgcolor="#525D76">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Action Events"><strong>Action Events</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+Now go back into your sample app in your web browser and insert an entry into
+the table. Look at the URL line in your browser. The end of it should contain
+"/action/SQL" This is the method that Turbine just used to insert your data
+into the database. The class file corresponding to it can be found in
+"webapps/APPNAME/WEB-INF/src/java/PACKAGE/modules/actions" and is called
+SQL.java. In fact, when you did your Insert of the data, Turbine called a
+method called "doInsert" inside of the SQL class in order to insert the data.
+A full explaination of how actions work is available
+<a href="action-event.html">here.</a>
+</p>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table border="0" cellspacing="0"
cellpadding="2" width="100%">
+ <tr><td bgcolor="#525D76">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Changing your schema"><strong>Changing your schema</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+Now that we know about actions, we should change our database to something more
+useful. In order to do this, move to the directory
+"webapps/APPNAME/WEB-INF/build/project" and open up the file "APPNAME-schema.xml".
+This file contains our database schema in XML. This file should be rather self
+explainatory. Within it you can create new tables and new fields within
+existing tables. Add some more rows to the example table and save the file
+back. Now go to the directory "webapps/APPNAME/WEB-INF/build" and run the command
+"./build.sh init" again. (WARNING: If this is done you will lose all of your
+data in the existing database, do not run if you have data in your database
+that you need.) This will update existing databases and their objects with
+new fields and create the databases defined in the .xml file, along with
+their associated java classes. The java classes that Turbine uses to access
+your database are located in the directory
+"webapps/APPNAME/WEB-INF/src/java/PACKAGE/om" Look at them to get an idea of
+how the object-model portion of Turbine operates. There should be one named
+after each of the tables that you defined above in your schema. These classes
+will be used to interact with the database while using Turbine.
+</p>
+ <p>
+After our schema has been updated we will need to go back and edit the .vm files
+that operate on it. Go back into "Index.vm" as described above and change the
+headings to those that match your new schema. If you have created another table
+that you would like to call from the Index, or have changed the name of your
+original table, edit your "Index.java" file to get the data from that Database
+instead of the default one by calling the OM object for it instead.
+</p>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table border="0" cellspacing="0"
cellpadding="2" width="100%">
+ <tr><td bgcolor="#525D76">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Conclusion"><strong>Conclusion</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+You now have your first Turbine application up and running. You can now begin
+changing the Java and vm files to begin building the real application that you
+have in mind. In order to recompile a Java file you change, run
+"webapps/APPNAME/WEB-INF/build.sh compile". This will recompile all of the Java
+files that have changed in your project. You may also wish to join the
+Turbine Users mailing list. Instructions for doing so can be found
+<a href="http://jakarta.apache.org/site/mail.html";>here.</a>
</p>
</blockquote>
</td></tr>
1.40 +3 -1 jakarta-turbine/docs/getting-started.html
Index: getting-started.html
===================================================================
RCS file: /home/cvs/jakarta-turbine/docs/getting-started.html,v
retrieving revision 1.39
retrieving revision 1.40
diff -u -r1.39 -r1.40
--- getting-started.html 2001/05/08 19:53:49 1.39
+++ getting-started.html 2001/05/10 03:39:49 1.40
@@ -165,7 +165,9 @@
Engine</a> which is preconfigured to run Turbine. The TDK also has
sample applications as well as scripts that allow you to quickly build
your own application. As time progresses, we will be including more and
-more helpful information in the TDK.
+more helpful information in the TDK. Please see the
+<a href="getting-started-tdk.html">Turbine Development Kit Getting Started
+Guide</a> for more information.
</p>
</blockquote>
</td></tr>
1.2 +236 -61 jakarta-turbine/xdocs/getting-started-tdk.xml
Index: getting-started-tdk.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine/xdocs/getting-started-tdk.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- getting-started-tdk.xml 2001/04/27 12:12:32 1.1
+++ getting-started-tdk.xml 2001/05/10 03:39:49 1.2
@@ -3,115 +3,290 @@
<document>
<properties>
- <title>Turbine Getting Started</title>
- <author email="[EMAIL PROTECTED]">Turbine Documentation Team</author>
+ <title>Turbine Development Kit Getting Started</title>
+ <author email="[EMAIL PROTECTED]">Kurt Schrader</author>
</properties>
<body>
+<section name="Introduction">
+<p>
+The Turbine Development Kit allows you to begin developing on/evaluating
+Turbine and its diverse set of components almost immediately. It includes
+almost everything needed to begin Turbine development. Installing it
+should be the first step in your evaluation of Turbine.
+</p>
-<section name="The really big picture:">
<p>
-As you are developing your new Turbine application, you will
-be working mainly in three our four areas:
+Much of this getting started guide has been put together using information
+found elsewhere on the website. It should not be seen as a replacement for
+reading the plethora of information available about Turbine, as new users seem
+to always do. It simply attempts to get a first time user up and running with
+the TDK quickly and with a general knowledge of how it works. As usual, please
+be sure that you have scoured the entire website for information before asking
+questions on the mailing list. Also, it is suggested that you read this entire
+page before attemping to install the TDK.
</p>
-<dl>
- <dd>
- 1. design and create your object model
- </dd>
- <dd>
- 2. create ApplicationTools (tools used in conjunction with
- the pull service)
- </dd>
- <dd>
- 3. create templates that use the ApplicationTools
- </dd>
- <dd>
- (1.5 in some cases you may be creating services that sit
- roughly between the object model and the
- ApplicationTools.
- </dd>
-</dl>
+</section>
+
+<section name="Prerequisites to using the TDK">
<p>
-Item 1 is the Model in the Model-View-Controller design
-pattern. In Turbine, this is a combination of the
-project-schema.xml file you will create to define your
-object model, and the various files Torque will create from
-your project-schema.xml.
+Before using the TDK, you are going to need to have a Java Software
+Development Kit supporting Java version 1.2 or later installed on your machine.
+Sun's Java SDK can be downloaded from their website located
+<a href="http://java.sun.com/j2se/1.3/";>here.</a>
</p>
<p>
-Item 2, roughly speaking, is a bridge between your object
-model and the templates. If you are in a large shop, this
-is where the programmers will create an API for the web
-designers. If you are in a small shop, you still want to
-use the Pull model because it will make it much easier to
-modify your web application down the road.
+In order to do anything interesting with the TDK, you are also going to need a
+database that is compatable with the JDBC standard. The TDK currently comes
+with drivers for MySQL and Postgres. Other drivers can be downloaded from the
+vendor's websites located here:
</p>
<p>
-Item 3 is the View. This is where you build the user
-interface for your web application. In Turbine these are
-typically Velocity templates.
+<li><a
href="http://technet.oracle.com/software/tech/java/sqlj_jdbc/software_index.htm";>Oracle
JDBC Drivers</a>.</li>
+<li><a href="http://instantdb.enhydra.org/";>InstantDB JDBC Drivers</a>.</li>
</p>
<p>
-The Turbine servlet is the Controller. Item 1.5 is how
-you extend the functionality of the controller in very
-flexible ways.
+Simply download this driver to a directory right now where you can remember
+where it is. We will make use of it later.
</p>
+</section>
+
+<section name="Downloading and Installing the TDK">
<p>
-You can use JSP instead of Velocity, in which case item 2
-will consist of JSP tag libraries, and item 3 will be JSP
-templates that use those tag libraries.
+Unpack the TDK distribution into a directory of your choosing. On Windows, use
+WinZip to unpack the files and on Unix, something like:
</p>
+
+<source><![CDATA[
+
+tar -xvzf tdk1-1a14.tar.gz
+
+]]></source>
+
+<p>
+should to the trick. This is all that you have to do to install the TDK, but
+now a sample app needs to be created in order to see what it can do.
+</p>
+
</section>
+<section name="Creating your first Turbine application">
+
+<p>
+Now that you have Turbine installed on your machine, you need to create a
+sample application in order to begin using it. This is done in the following
+manner:
+</p>
+
+<p>
+1. Open up the file "build.properties" in the root TDK directory. Change the
+property "target.package" to the name of the package that you would like your
+java files to live in and the property "target.directory" to the directory that
+you would like your classes to be created in. These two values are usually a
+mirror of one another. Finally, change the property "turbine.app.name" to the
+name of the application that you would like to create. Usually this is the same
+as the identifier specified at the end of your target.package.
+</p>
+
+<p>
+2. Set the JAVA_HOME environment value for your system. On *nix/BSD using the
+Bash shell, this can be done with:
+</p>
+<source><![CDATA[
-<section name="Getting to know the TDK:">
+export JAVA_HOME="/PATH/TO/JDK/"
+
+]]></source>
+
+
<p>
-Download the latest TDK and install it.
+3. Run the newapp script located in the root directory of the TDK installation.
+This script should be run with the name of your turbine app appended to it. For
+example:
</p>
+<source><![CDATA[
+
+./newapp.sh NEWAPP
+
+]]></source>
+
<p>
-Login with username 'turbine' and password 'turbine'
+from your root TDK directory. This will create many of the files necessary for
+running your turbine app.
</p>
<p>
-Insert a couple entries into the sample application, edit
-them, delete them. Play with Flux by adding a couple users,
-groups, roles, and permissions. These two examples are
-fairly basic web applications, but they contain all the
-ingredients of more complex applications.
+4. Once this initial set of classes has been created, you will need to go into
+the directory "/TDKROOT/webapps/APPNAME/WEB-INF/build/project" in order to edit
+your "APPNAME.properties" file. In this file you will need to specify things
+such as the type of database you are using and its connection info. This
+information is used to create the database you will be using and the classes
+used to access it. At this time you should also copy your JDBC drivers
+(renaming .zip files to .jar files, if necessary) into the
+"webapps/APPNAME/WEB-INF/lib" directory if you are using a database other than
+MySQL or Postgres. These files will be important when creating the database
+tables in the next step.
</p>
<p>
-Item 1: look at WEB-INF/build/project/*-schema.xml and at
-WEB-INF/src/java/org/mycompany/newapp/om/*Peer.java and at
-WEB-INF/src/sql/*
-These are the Model part of the picture.
+5. Go to the directory "/TDKROOT/webapps/APPNAME/WEB-INF/build" and run the
+command "./build.sh init" This command MUST BE RUN before attempting to use
+Turbine. It creates the database tables and OM classes for accessing them.
</p>
<p>
-Item 2: look at ...<br/>
-TODO: need a pull version of the sample application so we
-can have an ApplicationTool to look at.
+6. Your first Turbine app has now been created! go back to the root directory
+of your TDK installation and type in "./bin/startup.sh" This will start the
+Tomcat servlet engine and make your application available.
</p>
+</section>
+
+<section name="Accessing your Turbine application">
+
<p>
-Item 3: look at ./templates/screens/*.vm to see examples
-of Velocity templates.
+Now that you have your Turbine application created and running by following the
+instructions above, point your browser to
+http://SERVERNAME:8080/APPNAME/servlet/APPNAME where SERVERNAME is the hostname
+of the machine running Tomcat, and APPNAME is the name of the application you
+created.
</p>
<p>
-Item 1.5: look at the javadoc for TurbineSecurity as an
-example of the service
+The initial login screen should appear and you should login with username
+'turbine' and password 'turbine' This will bring you to the initial "Turbine
+Data Manager" layout. From here you can insert/delete/edit entries in the
+default database or create and manage users using Flux, the built-in user
+management system for Turbine. These are the example turbine apps.
</p>
+
</section>
+<section name="Editing the Example App">
+
+<p>
+Look at the example app that you now have on your screen. The view that you are
+seeing actually consists of 4 different parts (top, bottom, menu and index) that
+were assembled for you on the fly by Velocity. In order to see how this works,
+you have to edit the file "webapps/APPNAME/templates/layouts/Default.vm" This
+file defines how the default layout is shown on your screen. As you can see,
+it is written as a fragment of HTML that will eventually be integrated into your
+final page. Editing this file will affect the layout of your entire
+application.
+</p>
+
+<p>
+Knowing now how the page is laid out, go to the directory
+"webapps/APPNAME/templates/navigations" to see the files that will be inserted
+into the layout template above. Edit the file "DefaultBottom.vm", save your
+changes back, and reload your page. By doing this you should see whatever
+changes you have made to the file appear at the bottom of your layout. This
+change will also occur in all of the other pages on your site. Change to a
+different page to confirm this.
+</p>
+
+<p>
+Now go into the directory "webapps/APPNAME/templates/screens" The files in this
+directory are the ones that replace the "$screen_placeholder" variable in
+the original layout. Open up the file "Index.vm" and you will see that a
+variable is defined called "$headings" that holds the strings for each of the
+headings on the Index page and that a variable called "$entries" is used
+to show the dynamic data on the page. This variable comes from the Java class
+file that is associated with this .vm page, as explained in the next paragraph.
+The Index.vm page also includes a number of functions that begin with #, such as
+"#entryCell(...)" These functions are replaced with HTML fragments at runtime,
+as defined in the "webapps/APPNAME/templates/GlobalMacros.vm" file. Look at
+this file to get an idea of what each of these methods do.
+</p>
+
+<p>
+In order to view the Java file that is associated with the Index.vm, go to the
+directory "webapps/APPNAME/WEB-INF/src/java/PACKAGE/modules/screens" A quick
+look in this directory should show you that each page with dynamic data in it
+has an associated class file in this directory. Open the file "Index.java" and
+look over its contents. As you can see, the "doBuildTemplate" method creates a
+variable called "entries" and associates the data that it pulls from the
+database in the "getEntries" method into it. In the case of the Index.vm page,
+this corresponds to all of the entries from our example database. The
+"context.put("entries", getEntries())" method places the data and the associated
+handle for it into our session context so that it can be accessed from our .vm
+pages. You would edit this file to change the behavior of a given page. More
+information on building sites with Velocity is available
+<a href="velocity-site.html">here.</a>
+</p>
+
+</section>
+
+<section name="Action Events">
+
+<p>
+Now go back into your sample app in your web browser and insert an entry into
+the table. Look at the URL line in your browser. The end of it should contain
+"/action/SQL" This is the method that Turbine just used to insert your data
+into the database. The class file corresponding to it can be found in
+"webapps/APPNAME/WEB-INF/src/java/PACKAGE/modules/actions" and is called
+SQL.java. In fact, when you did your Insert of the data, Turbine called a
+method called "doInsert" inside of the SQL class in order to insert the data.
+A full explaination of how actions work is available
+<a href="action-event.html">here.</a>
+</p>
+
+</section>
+
+<section name="Changing your schema">
+
+<p>
+Now that we know about actions, we should change our database to something more
+useful. In order to do this, move to the directory
+"webapps/APPNAME/WEB-INF/build/project" and open up the file "APPNAME-schema.xml".
+This file contains our database schema in XML. This file should be rather self
+explainatory. Within it you can create new tables and new fields within
+existing tables. Add some more rows to the example table and save the file
+back. Now go to the directory "webapps/APPNAME/WEB-INF/build" and run the command
+"./build.sh init" again. (WARNING: If this is done you will lose all of your
+data in the existing database, do not run if you have data in your database
+that you need.) This will update existing databases and their objects with
+new fields and create the databases defined in the .xml file, along with
+their associated java classes. The java classes that Turbine uses to access
+your database are located in the directory
+"webapps/APPNAME/WEB-INF/src/java/PACKAGE/om" Look at them to get an idea of
+how the object-model portion of Turbine operates. There should be one named
+after each of the tables that you defined above in your schema. These classes
+will be used to interact with the database while using Turbine.
+</p>
+
+<p>
+After our schema has been updated we will need to go back and edit the .vm files
+that operate on it. Go back into "Index.vm" as described above and change the
+headings to those that match your new schema. If you have created another table
+that you would like to call from the Index, or have changed the name of your
+original table, edit your "Index.java" file to get the data from that Database
+instead of the default one by calling the OM object for it instead.
+</p>
+
+</section>
+
+<section name="Conclusion">
+
+<p>
+You now have your first Turbine application up and running. You can now begin
+changing the Java and vm files to begin building the real application that you
+have in mind. In order to recompile a Java file you change, run
+"webapps/APPNAME/WEB-INF/build.sh compile". This will recompile all of the Java
+files that have changed in your project. You may also wish to join the
+Turbine Users mailing list. Instructions for doing so can be found
+<a href="http://jakarta.apache.org/site/mail.html";>here.</a>
+</p>
+
+</section>
</body>
</document>
1.11 +3 -1 jakarta-turbine/xdocs/getting-started.xml
Index: getting-started.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine/xdocs/getting-started.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- getting-started.xml 2001/05/08 19:47:11 1.10
+++ getting-started.xml 2001/05/10 03:39:50 1.11
@@ -26,7 +26,9 @@
Engine</a> which is preconfigured to run Turbine. The TDK also has
sample applications as well as scripts that allow you to quickly build
your own application. As time progresses, we will be including more and
-more helpful information in the TDK.
+more helpful information in the TDK. Please see the
+<a href="getting-started-tdk.html">Turbine Development Kit Getting Started
+Guide</a> for more information.
</p>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
