File: Introduction_to_p4a_2

********************************************************************
*******************************   p4a_Application:   ***************
********************************************************************


	Most important class of the framework.

	1. This class acts as a container of all classes.
	2. This class has the primary event handler that is called when some action occurs in the client-side representation of the application.
	3. This class defines the aspect of the entire application due it has the 'setTheme' method.
	4 .THIS CLASS HAS TO BE DERIVATED IN ORDER TO CONSTRUCT OUR REAL APPLICATION. That is, our application object extends p4a_Application.

	Methods:
		*******	onStart:

This is an empty method called in the constructor of the Application object.
The sense is clear: to permit initialize our own objects (overloading this method) in the extended application object.
In the Example One I overload this method:

				
				class MyApp extends p4a_Application
				{
						...
						...

				function onStart()
				{
					$this->topmenu = new TopMenu( "topmenu", $this);
						...
						...
				}

		******	setTheme:
This method permits to isolate the aspect of the application	and to focus our attention in the functionality.

Moreover, this mean that we can define a number non limited of themes.

						...
						...
					$_myapp = new MyApp('My P4A Application');
					$_myapp->setTheme('bluetheme');

'bluetheme' is a css file that contains all the css classes needed to draw the p4a objects.

This file has to reside in p4a/themes/bluetheme/ and optionally it can have an 'img' subfolder.

		******	addControl:
				With this method we agregate controls to the application
				and we give it the responsability of drawing.
One time we have called this method passing the object to add in its arguments, we can't access to this object using the variable passed to the application: We must refer to this object using the ‘controls_collection' matrix of the application.

				This is:

				$mybutton = new p4a_PlainButton("My Plain Button", 150, 60);
				$mybutton->setLabel("My Changed Plain Button");

				Then we introduce it in the application:

				$_myapp->addControl( $mybutton, 'button1', $cx, $cy);

If now we want to add an image inside the button, we can't do this:
			
				$mybutton->setImage('icon.ico', 50); //WRONG!!

				We must do:

				$myapp->controls_collection['button1']->setImage(...);

		******	flush:

The most important method at all. This method construct the HTML and Javascript code of the application attending to the actual status of all objects in the application.

Normally this method, in the application object, only has to be called the first time the application is instantiated. After this,	and responding to particular events of the user, only the 'flush' method of these particulars objects are called.

The first time, when the application is instantiated the method is called without arguments. Like all objects in P4A framework, when this objects has to be redisplayed responding to an event, 'flush' method has to be called with argument 1 -flush(1)-. This is 	because the answer is sended to an iframe in the web page, and the JavaScript code has to refer to the html objects of the parent.

The argument indicates to the 'flush' method that it must add the 'parent.' string in all the javascript sentences.


				

'Index.php' script, the first time, the application is created.

					...
					$_myapp = new MyApp('My P4A Application');
					...
					$_SESSION['Application'] = $_myapp;
					$_SESSION['Application']->flush();  //without arg.
					...

The flush method has only an 'echo' instruction with a large	string with all the HTML and JavaScript code.

				Answering to an event:

					...
					...
			$answer .= $_app->controls_collection['panel01']->flush(1);
					...
					...

		*******	event_handler:

This is the collector of all events that occurs in the client-side	of the application (internet explorer).

This is an empty method that has to be overloaded to process the user action.

				'p4a_events' script:
							...
							...
					foreach( $_GET as $k => $v)
						$event[$k] = $v;

					$p4a = & $_SESSION['Application'];
	
					echo $p4a->event_handler( $event);

							...
							...
The 'event_handler' method returns (has to) an unique string that contains the result of all the 'flush(1)' methods of the objects.
This method receives an array containing the code of the event and optional arguments relative to the particular event.

				In the Example One I do:
					function event_handler( $_event)
					{
						switch( substr($_event['event'], 0, 7))
						{
							...
							...
						}
						return $answer;
					}

*************************************************************************
********************** p4a_BarMenu: *************************************
*************************************************************************
This class draws a typical top menu with a number ilimited of 'main' options.
Each option can send an event to the server-side and can remain selected. So, the p4a_barmenu has an status represented by the option actually selected.

	$mymenu = new p4a_BarMenu();

	//We can add options
	$mymenu->setMainOption( 'option1', 'Option One Label', 'event_option1');
	$mymenu->setMainOption( 'option2', 'Option Two Label', 'event_option2');

	'option1' is the code-name of the option, then we can refer to it, for example, to selecting it before including the menu in the application object

	$mymenu->setSelected( 'option1');
	
	'event_option2' is the code of the event. Like all the p4a events, we have to give it some knowed code in order to capturing the action when it is fired.

	//Event handler of the application
	
	function event_handler( $_event)
	{
		switch( $_event['event'])
		{
			case 'event_option2':
				$this->controls_collection['mymenu']->setSelected('option2');
				...
	...
	...

*************************************************************************
**************************  p4a_ListView: *******************************
*************************************************************************
The power of this class (like the p4a_Form class) resides in its union with the DataSource object. This class displays a number of predefined rows of a table and captures the next events:

	column events: It can be used to re-order the content of the list by the column clicked.
	row events: If can be used, for example, to filter and positioning some p4a_Form..
	next event: To show the next group of rows, depending of the maximum number of rows we have set to the list.
	previous event:...

Some Methods:

		************ setSource:

Introduces the DataSource object in the list and gives the control	of this last object to the list.
			In the Example I do:

						...
						...

			$ds = new p4a_DataSource("p4aex_db", "p4aex_us", "", "tableexample");

			$list = new p4a_ListView("160");
			$list->setSource( $ds);


		********** setNumRows: 

Set the maximum number of rows to display at the same time. The default is P4A_NUM_RECORDS_MULTIOCURRENCY.

		*********** setColumn: 

Indicates which of all columns that exists in DataSource has to be displayed and with which label.

		************ setDscn: 

Sometimes a field in a table is a foreign key and we don't want to represent this code but its description or name in the master table, this method allows this, passing it the table referenced, the 'description' field and the key field.

			In the Example I do:
							...
							...
			$list->setColumn( "field3", "Field Three (click for change order)");
$list->setDscn( "field3", "Field Three Description", "tablereferenced", "description", "field3");
							...
							...

		********** setFilter: 

We can filter the data we want to display in the client-side passing to this method the sql "where" part that has to be added to the DataSource.

		********** SetOrder:

Changes the order of the list displayed. The argument is like "field2 ASC' or 'field1 ASC, field2 DESC'.

		************ setonClickColumn,
		setonClickRow,
		setonClickNext,
		setonClickPrev: 
Methods to set the code-name of the event and optionally the
label associated to the control of this event. If one of this events are not set, the control won't be displayed and it won't be available to the user.

			for example:
							...
							...
				$list->setonClickRow( "panel01_row");
				$list->setonClickNext( "panel01_lnext", "Next rows");
							...
			then, in the event handler I can capture both events:


				case "panel01_lnext":
					$_app->controls_collection['panel01']->next();
					$answer .=$_app->controls_collection['panel01']->flush(1);
					break;

************************************************************************
*************************************************************************
******************** p4a_Form: ****************************************
***********************************************************************
This is an advanced form that not only can send data to the server, also it can be used to navigate along the registers of a table. Also it has an status management that permits to change the displayed aspect according to this status.
Theses status are:

P4A_FORMSTATUS_EDITION: the default status, the next, prev, insert, update and delete events are available (if it has been set)

P4A_FORMSTATUS_INSERTING: the insert event has been fired and the form is waiting to the user intro. Only the update and cancel events are available.

P4A_FORMSTATUS_FILTERED: the form has been filtered and, by the way, the next and previous events are not available. This status is compatible with _EDITION status.
 
Methods:

	********  setStatus:

Changes the status of the form, modifying the aspect displayed in the explorer.
		There are some combinations of status that are incompatibles:

1 . The Form can't be P4A_FORMSTATUS_FILTERED at the same time it is	P4A_FORMSTATUS_INSERTING, because the inserted data depends only of the user, of course.
2. the Form can't be P4A_FORMSTATUS_INSERTING at the same time it is	in P4A_FORMSTATUS_EDITION.

	*******  setFilter:

Like p4a_ListView, this method lock the form and disables the next and prev controls/events. By the way, also changes the status to P4A_FORMSTATUS_FILTERED.

	********** setSource:

Introduces the p4a_DataSource control in the form, associating the form with a source of data that can be a data base. The use of this method is the same like in p4a_ListView control.

	********* setField:

		Indicates which of all columns that exists in DataSource has to
		be displayed and/or maintained and with which label.
This field can be a Combo with a set of possibilities. This option is useful to fields that are foreign keys, then the user don't have to know the code of the	option that wants to select, only the name/description located in the master (main)
		table of the option.

		In the Example one I do:

					...
			$form->setField( "field2", "Field Two", "text", 30);
					...
			$form->setField( "field3", "Field Three", "text", 15, 1, "tablereferenced", "description", "field3");
					...
					...
the form is associated with a table 'tableexample' and the 'field3' is a foreign key to 'tablereferenced', which has the 'field3' as the primary key and the field 'description' as the name of the key.

	****** setNumCols:

Fixes the number of columns to contruct the form in the explorer, the minimum is one.

	************ setonClickNext,
	setonClickPrevious,
	setonClickDelete,
	setonClickUpdate,
	setonClickInsert,
	setonClickUnlock,
	setonClickCancel:
All these methods are used to set the corresponding events, note that is these are	not set, the user won't be able to fire it.

		For exmaple I do:
					...
					...
			$form->setonClickNext( "panel01_next", "Next");
			$form->setonClickPrevious( "panel01_prev", "Previous");
					...
					...
		then I can capture it in the event_handler method:

					...
					...
			case "panel01_next":
				$_app->controls_collection['myform01']->next();
				$answer .= $_app->controls_collection['myfrom01']->flush(1);
				break;
					...
					...