tornado2x webframework

Menu
What is tornado2x?
News
Installation
Getting Started
Documentation
Download!
Getting Help
What is tornado2x?

tornado2x is a webframework in php based on the widely know model view controller (mvc) pattern. it has a model2x design approach and renders its presentation layer by xsl transformation. right now it is in an early stage of development and should be considered alpha code. tornado2x is distributed under the terms of the GPL.

some of the features:

  • model view controller pattern (action classes, form classes, xslt for presentation)
  • application skeleton for rapid development
  • automated object and database resultset to xml transformation (serialization)
  • storage objects to keep implementation details hidden from business logic
  • io processor mechanism to hide actual sql queries from implementation
  • extensive use of configuration files and descriptors (application, sql queries, actions...) for maximum flexibility
  • tornado2x comes with its own classloader to find and create instances of your actions
  • extensive use of reflection on objects during runtime

and many more...

things to do:

  • plugin architecture for different xslt (and view) inplementations
  • dynamic form objects
  • creation of xml code when returning to input (for forms)
  • abstraction of dealing with storage objects
  • improvements of dealing with non-generic sql queries in the processor
  • overall code improvements
  • and lots more... ;)



News

- 2003-06-22 Like the code? Want to join? Please contact me.
- 2003-06-22 First alpha code is released!



Installation

tornado2x requires a PHP version with xslt support enabled!

- Extract the tarball to the document root or a webserver directory

- Create a directory "logs". Create a file "tornado2x.log". Make the directory and the file writable to the user who runs the webserver.

- Adjust the file "index.php" (adjust web.inc.php in version newer than 0.1). Please assign the absolute path where tornado2x resides. Set an individual SID for your system that names this instance of tornado2x.

- Make sure the PEAR Classes "DB" and "XML_Tree" are available to the system. If not, download them manually and store them in a directory and adjust the file "index.php" (require_once).

- Create a mysql database "tornado2x". Use file "tornado2x.mysql.sql" to setup the database. Please adjust the file "web.inc.php".



Getting Started

This getting started guide requires some good knowledge of how webapplication frameworks like for instance jakarta struts work. After a successful installation and configuration of tornado2x let's start coding our first action.

Step 1: First of all you need to define the action in the mapping.inc.php file. You'll find it in the classes folder of your webapplication. Then you need to add a new element of the actionArray like this:

		$actionArray["gettingstarted"]["actionClass"]                      = "GettingStartedAction";
		$actionArray["gettingstarted"]["actionClassFile"]                  = "gettingstartedaction.class.php";
		$actionArray["gettingstarted"]["input"]                            = "gettingstarted";
		$actionArray["gettingstarted"]["forward"]                          = "success";
		$actionArray["gettingstarted"]["xsl"]                       	  = "myspecial.xsl";
		$actionArray["gettingstarted"]["form"]                       	  = "GettingStartedForm";
		$actionArray["gettingstarted"]["formClassFile"]                    = "gettingstartedform.class.php";
		

The actionClass element defines the exact classname of your action class inplementation that needs to be in the classes/actions folder. This is where all your actions will be.

The actionClassFile element tells the classloader the exact filename that it needs to load and instantiate.

The input element holds the view that the user will be returned to if neccessary and required (errors...). This element is optional.

The forward element holds the view that the user will be forwarded after executing your action.

The dispatch element is used when you need to display what your action object generated. It is set to true. No view name needs to be defined.

The xsl element is an optional element to define a special xsl file for displaying the view (located in the views folder).

The form element holds the classname of your form that corresponds with the fields of your html form in the input view. This is only used when you have a html form that needs to be processed.

The formClassFile elements tells the classloader the exact filename that it needs to load and instantiate. Again this is not needed if you don't have a html form.

Step 2: Then you need to create the files. Create a class named GettingStartedAction (gettingstartedaction.class.php) in the classes/actions folder. You also need to create a class GettingStartedForm (gettingstartedform.class.php) in the classes/forms folder. Create a view gettingstarted (gettingstarted.xml) and success (success.xml) in the views folder. Create the XSL stylesheet myspecial.xsl and put it in the views folder.

XML Files should look like this:

			<?xml version="1.0"?>
			<content view="gettingstarted">
				...
			</content>
		

Apart from the content node you have total freedom. This also applies to the XSL stylesheet.

This is what the response looks like that tornado2x generates after executing an action:

			<?xml version="1.0"?>
			<response>

			...


			<errors>
				<error name="test" message="This is a test error!"></error>
				<error name="test2" message="This is a test error number 2!"></error>
			</errors>

			</response>
		

This is what the action class looks like. It must be a subclass of the ActionBase class.

			class GettingStartedAction extends ActionBase{

				/**
				*
				*
				*/
				function GettingStartedAction(){
				}
	
				/**
				*
				*
				*/
				function perform(){
				}	

			}
		

This is what the form class looks like. It needs to extend the ActionForm class.

		class GettingStartedForm extends ActionForm{

			var $myHTMLFormfield;
			
			/**
			*
			*
			*/
			function GettingStartedForm(){
			}
			
			/**
			*
			*/
			function getMyHTMLFormfield(){
				return $this->myHTMLFormfield;
			}
			
			/**
			*
			*/
			function setMyHTMLFormfield($value){
				$this->myHTMLFormfield = $value;
			}
		}	
		

Step 3: Now you need to code your action and form class implementations and write your xml and xsl.

Coding actions and forms in tornado2x is easy and fun. Starting with form classes, you will have to apply the coding conventions known from java bean classes. For every form field in your html form you need an attribute named exactly like the field name. Then you need to add the two accessor methods to your class to modify the attribute (getter/setter). That's about it. tornado2x will then automatically populate your form class.
Within your action object you are able to get an instance of the form object and retrieve the form values through the getter methods. This is what the code in your action class looks like:

		function perform(){
			$form = $this->getForm();
			$myHTMLFormfield = $form->getMyHTMLFormfield();
			
			...

		}
		

After finishing your business logic you need to tell tornado2x where to return to. That is defined in the mapping.inc.php.

		function perform(){
			...
			
			if (...){
				
				/**
				* something failed, return to input forward
				*/
				return $this->returnToInputForward();
				
			}
			
			/**
			* everything went fine, return to forward view
			*/
			return $this->returnToForward();
		}
		

IO and database communication is not supposed to be in the action class itself. So in the folder io there is a so called processor class which should inplement your io and database processing methods. so just create a method for every sql query you need and call it from the action. you can also use generic methods to retrieve sql resultsets. the resultset then can be automatically converted to xml. Where as the processor itself is not supposed to hold any sql queries itself. The sql queries are also in a configuration file (sqlqueries.inc.php). These are read by tornado2x and made available to the processor through a storage object.

		function perform(){

			$xml = $this->processor->resultToXML($this->processor->getSqlQuery("test"));

			return $this->returnToForward();
		}	
		

sqlqueries.inc.php:

		$sqlQueries 					 = array();
		$sqlQueries["test"]				= "SELECT * FROM tornado2x_codes";
		...
		

When having an action that wants to dispatch a view you can just create your xml and add it to the result of the action. Everything in the result will be available to your dispatch view as your response xml code for transformation.

		function perform(){

			$xml = $this->processor->resultToXML($this->processor->getSqlQuery("test"));
			$this->setResult($xml);
			
			....
			
			$xml2 = $this->processor->resultToXML($this->processor->getSqlQuery("test"));
			$this->setResult($xml2);
		
			return $this->returnToForward();
		}	
		

mapping.inc.php

		...
		$actionArray["test"]["dispatch"]                          = true;
		...
		

You should keep all specific information out of the actual inplementation. That's about all you need to know to get started! I am not going to talk about how XSLT works. Please check out the specs by W3C. Go check out the LoginAction and TestAction in the tornado2x application skeleton too.

Step 4: Have fun!



Documentation

Not available yet!



Download!

Current Version: 0.1
Go to sourceforge download page

Current Version in CVS: 0.2
Anonymous CVS Access:
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tornado2x login
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tornado2x co tornado2x



Getting Help

Check out the discussion forums:
tornado2x support forum

If you run into trouble and you can't find an answer anywhere else, please contact me.


SourceForge.net Logo

tornado2x and all the contents on this page are copyright 2003 Oliver Kiessler.
tornado2x is distributed under the terms of the GPL.