I have completely rewritten the TDK getting started guide, as the old one
seemed rather useless to me. Patch is below.
Index: getting-started-tdk.xml
===================================================================
RCS file: /home/cvspublic/jakarta-turbine/xdocs/getting-started-tdk.xml,v
retrieving revision 1.1
diff -u -r1.1 getting-started-tdk.xml
--- getting-started-tdk.xml 2001/04/27 12:12:32 1.1
+++ getting-started-tdk.xml 2001/05/10 02:42:47
@@ -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>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
