Location: PHPKode > projects > PHP Ajax Forms Framework > pajff/docs/HowToUse.txt
PAjFF

<c> 2006 by Atanas Markov hide@address.com

Using the framework will not be document well soon. I hope this little document will help you 
understand it. You can see how to use it in the sample application where I'll try to write examples
of event handlers.

The directory structure of a project is:

/				-	Contains the main application file
pajff			-	the pajff framework itself
java			- 	javascript definitions for the pages. not tested yet
forms			-	form definition files
handlers		-   handler definition files

Every application is based on forms and form events. Every form is saved in its own session in a 
database. You can go from one form to another, but in the end you can go to the first one and have 
it the same as in the very beginning as if you have called windows in a desktop application. 

So how it works? You define form types and event handlers for their events. The application has to 
create a main application class to create a form and call it. Everything else is up to the framework.
:)
Sessions not used for more than 3 hrs are deleted automatically.

1. Application main file

Application main file should be placed in the main project directory. It must contain a valid 
application class and include "pajff/pajff_joomla.php" at the end. It must define the following 
variables too as joomla is called using index2.php and the framework itself can't get the correct 
name of the component:
	$pajffappname	- the name of the script without ANY paths or extension. 
	        $pajffappname="try";
	$pajffdebuginfo - if set to 1 the framework writes event messages sent by debugMessage() at the
					bottom of the page.
					
<?php
/*
	Application main file structure
*/

$pajffappname="......."; //application name
$pajffcharset="cp1251"; //application charset- short name. May not be set.
$pajffcharsetlong="windows-1251"; //application charset- long name. May not be set.
$pajffdebuginfo=1; //if not set- no debug messages are shown

//more code here if needed

class pajffmainapp{
	public $title="Ìîäóë çà ôèíàíñîâ êîíòðîë";
	public $appname="fczaiavka";
	public function runApp(){
		$appform= new pajff_form('....'); //initialize the main form here
		if ($appform) {
			return $appform->drawForm();
		} else {
			return "No main form";
		}
	}
}

include "pajff/pajff_joomla.php"; //start the framework itself

?>

2. Form definition files

They are placed in the "forms" folder. Each of them is called formtype.php where "formtype" is the 
name of the form type. They must define formtypeForm($session) function where $session is the 
session contatining form data and return a string containing form HTML with no <form> tags in it.

<?php
function tryForm($session){
	$result = "a form
	<input type=\"text\" name=\"try\" value=\"".
	$session->sessionform->try 
	//a previosly defined variable. may be passed by other form handlers...
	."\">
	<input type=\"submit\" id=\"okbtn\" name=\"okbtn\" value=\"TRY VALUE\"
	onclick=\"".
	pajffFormEventReg('ok',$session) 
	//An event where you get all the form data in an array($event->params)
	."\" 
	>";
	
	return $result;
}

?>

3. Event hanler files

Placed in the "handlers" folder. The same naming convention as form files, but they define functions
 called formtypeevent($session,$event). they may return pajff_eventresponse or pajff_form objects 
 or even text. In the example we return a form and tell it the variable printme is the value of a 
 form object called try- the text edit from the previous example.

<?php
function tryok($session,$event){
	//form try event ok. 
	$result= new pajff_form('',null,$session->parentID());
	$result->printme= $event->params['try'];
	return $result;
}
?>

to return to the previous form use sth like this:
function docrowcancel($session,$event){
	$session->sessionform->closeForm();
	$result= new pajff_form('',null,$session->parentID());
	return $result;
}

4. Framework functions

Here is a simple description of functions and classes defined in the framework

4.1 Defining forms

class pajff_form{
	public $session; //use it to access the form session
	public function __construct($formtype="",$parent=null,$id=null);
	public function closeForm();
}

$form= new pajff_form('',null,$session->parentID()); 
//recreate the previous form that called this one

$form= new pajff_form('try');
//a new form of type try with no parent session. e.g. the main form of the application


$form= new pajff_form('try',$session);
//a new form of type try with a parent that is $session.

use closeForm() to tell the form to destroy its session when you have finished using it. After 
calling the function you can use the form. closeForm() tells the form to clear the session at form 
object destruction!

4.2 Sessions

You can use sessions without forms, but I'll describe session relation with forms.

$session->var= ...
//assign a session var. 

useful vars:
$session->sessionform - the form of the session. in events you can use it to access the form
session->formtype	  - the type of the form.

4.3 Event handler definition

Used to simplify the generation of a html element event

pajffSimpleEventReg($event,$session,$eventcontainer,$eventvalue, $passform= false)

	$event - the name of the event
	
	$session - the session to send the event to
	
	$eventcontainer - if passed- the html element to get the value from. if empty then $eventvalue 
					is used. you may use it for form element validation on the fly
			<input type=\"text\" id=\"docnum\" name=\"docnum\" value=\"$document->docnum\" 
                size=\"10\" maxlength=\"10\" $disablededit onchange=\"".
			pajffSimpleEventReg('docnumchange',$session,'docnum','',false)
            ."\">
            
            ...
            
			function zaiavkadocnumchange($session,$event){
				$otherdoccount= countdocsnot($session->document->id,$event->params)
				if ($otherdoccount > 0){
					$text="&lt; Document number used! &gt;";
				}
				$result=new eventresponse('docnummes',$text); //a warning message in a div
				return $result;
			}
			
			Since 0.0.2 you may return an array of responses... to be documented soon, but the
			idea is that you can validate a whole form and send many validation messages at once 
			and a whole form with them :). maybe the form has to be sent first, because the rest
			is to be put in divs in it. 
            
     $eventvalue - a constant value to pass. e.g. a link in a list saying you have pressed element X
	 $passform - if set pass form values as if it was submitted in $event->moreparams
     
pajffFormEventReg($event,$session)

	$event - event name
	
	$session - the session for the event

	On such events form values are passed through $event->params. See the examples about handler 
	definition.

4.4 Misc

debugMessage($message)- send a debug message to the pajff debuger. If $pajffdebuginfo is set it 
will be displayed at the bottom of the component page.

pajffPath() - the path where pajff is placed

$pajffmainsession -  a global variable for the main application session

$pajffdebug - if set xajax is called in debug mode

Thanks to the XAJAX team. I hope this framework will show the power of their project. 
Return current item: PHP Ajax Forms Framework