Hello world example

Short Terminology

Before we start i like to address some terminology used inside the P4A framework:

• Mask: This is the display of our application, you can see it as the master container that holds all objects, handles actions and interact with the database. You can create as many mask as you would like, link them together, call widgets from other masks, ec, ec..

• Layout managers (or containers): These hold (anchor) the objects (widgets) and arrange them following a layout. P4A has 4 layout managers: Frame, Fieldset, Canvas and Sheet.

• Widgets: These are the basic building components like a button, field, menu, ec..

• Helpers: These are useful shortcuts to speed up tedious programming operations and they are also precious in adding new functionalities to the core p4a objects.

Keep in mind that any layout manager can hold other layout managers. This is also true for widgets, every widget can hold other widgets.

Basic folder structure

I assume that you installed P4A in your document root, so you have a folder like /<my_docroot>/p4a. Inside the p4a folder we see following folder structure:

• ./applications
• ./docs
• ./icons
• ./libraries
• ./p4a
• ./themes

Later on, these folders will be explained more in detail, but now we want to create our 'hello world' application. So let's create a folder hello_world under the application folder.

Now we have a directory that will hold our application, but we need to add a objects folder that will contain our application logic (classes or if you see it very simple, masks)

so at the end we have this very simple structure:

• /<my_docroot>/p4a/applications/hello_world ** ./objects

That's all for the structure, now let's add some code!

Create the application loader

First off all, we need a entry point for our application. Create a index.php file under the hello_world folder and add following code:

// Remember, this is the minimal that is necessary to start an P4A application
require_once dirname(__FILE__) . '/../../p4a.php'; //path to P4A framework

define("P4A_EXTENDED_ERRORS", true); //set this property to true for debugging/development, false for production.
// telling p4a to gather the 'hello_world' application
$hello_world = p4a::singleton('hello_world');
 
// start the application
$hello_world->main();

Now P4A knows witch class it must have to start the main() function from. Remember that all classes placed in the objects folder are loaded by P4A.

Create the application class

This class will extend the P4A class and act as a coordinator for the whole application. All objects you define in this class will be available in all underlying classes (let's say masks). In this example the object will open just our first mask, but you can define menus, DB's, ec. in here to use in your entire application. Create the file hello_world.php under the objects folder and add this code:

// we extend the base class from P4A so that everything defined in this class 
// will be available to all masks.

class hello_world extends P4A //extend the P4A class
{
    public function __construct() //add the constructor
    {
    	parent::__construct();

    	// This is the basic thing this class should do, opening a mask.
        $this->openMask("hello_world_firstmask");// opens the first mask of our application
    }
}

Make sure that the filename always equals the class name inside! This is a common mistake beginners make, especially when they copy code!

Create the first mask class

This class will be our first mask. To create a mask you just have to extend the P4A_Mask class. This class will contains all objects to display. Create the file hello_world_firstmask.php under the objects folder and add this code:

class hello_world_firstmask extends P4A_Mask // extend the mask class
{
	public function __construct()
	{
		parent::__construct();
		
		$this->setTitle("Hello World!"); //Set the title of your page
		
		//ok let's build a basic text field
		$this->build("p4a_field", "txt_field1")
			->setLabel("Text Field 1");
			
		//We add also a button to display some text into the text field
		$this->build("p4a_button", "btn_sayhello") //build the button
			->setLabel("Say hello!") //set his label
			->implement("onclick", $this,"_btn_sayhello_onclick"); //add action to the button
			
		//We want the items to show up on the mask, but we must use a layout manager to do that
		$this->build("p4a_frame", "frm_main") //were using a frame as layout manager
			->anchor($this->txt_field1) //anchor the text field
			->anchor($this->btn_sayhello); //anchor the button below the text field
			
		//Now we can display the widgets on the display
		$this->display("main", $this->frm_main); //Display the items on the main part
	}
	
	//We add a function to handle our onclick event...
	public function _btn_sayhello_onclick()
	{
		//...and adding some text to the text field
		$this->txt_field1->setNewValue("This is my first P4A application!");
	}
}

Starting the application

Now you can open your browser en goto http:///p4a/applications/hello_world If everything go well you should see now a text field and a button, so go ahead and click it!

This was only a (very) basic tutorial on how to create a P4A application. To see the full potential, just read further in the manual or use the forum.