The first mask

If you don't know what a mask is, please read the basic concepts section before continuing here.

Building a widget, the "build" method

In the previous section we saw how to create an empty mask but now we want to learn how to display things inside our mask.

The first important concept is that P4A does not require you (the programmer) to write HTML code, P4A works with a widgets system, bundled with the default P4A package and ready to work. An example? The P4A_Button, which actually reflect the behavior off the HTML button within the P4A logic.

To instance every (except a few we'll see later) P4A object (P4A_Object) you won't use the classical new class construct, you'll use the build method instead. The build method will instance the object and store it inside P4A internal structure and, most of all, inside the object that called the build.

An example to clarify it all

// The build method needs 2 params
// 1 - the class to instance
// 2 - the name you want to use for the variable inside the parent object
$this->build('p4a_button','my_button');
$this->my_button->setLabel('Test value');

Note that every P4A object can build other objects inside itself:

$this->my_button->build('p4a_button','my_second_button');
$this->my_button->my_second_button->setLabel('Test value 2');

Always remember that P4A is stateful, every built object will be available also when the page will be reloaded of whatever.

Placing a widget within a mask, the "display" method

Now that we know how to instance a widget we've to find out how to display it on our web page, we've a few zone where we can put the widget:

• menu (usually used for the main application menu, it's fixed at the top of the screen)
• top (usually used for toolbars, it's fixed at the top of the screen, right below the menu zone)
• main (the center area of the screen, scrollable)
• sidebar_left (a sidebar on the left of the screen)
• sidebar_right (a sidebar on the right of the screen)

If you want to place a widget in one of the zones above simply use this code:

$this->display("main", $widget); // first param is the template zone

Within a zone you can display only one widget. If this is not enough and you need many widgets (usual for main zone) you can display a layout manager (P4A_Frame, P4A_Fieldset etc.) see the next chapter to find out how to do that.

Create complex layouts: frames, canvas, sheets and fieldsets

P4A gives you some different layout managers, that will allow you to anchor widgets and fields on your masks with different features and rules:

• P4A_Frame: it's the default and the most used layout manager in P4A, highly recommended for your daily usage. It's rendered as a tableless flow of fields/widgets, usually one on every row, but you can use anchorLeft and anchorRight methods to display more widgets on a single row (floating left or right).
• P4A_Fieldset: it's a P4A_Frame rendered inside an HTML fieldset tag. It's useful when you've to group some fields in your mask. It usually has a title, you can set it with the setLabel method.
• P4A_Canvas: it's an absolute position layout manager, every widget is placed with absolute coordinates starting from the top/left edge of the canvas itself.
• P4A_Sheet: it's rendered as an HTML table, every widget is placed inside a cell of the table. It has features like rowspan and colspan.

Using a P4A_Frame

$this->build("p4a_frame", "frame")
	->setWidth(600) // set the width of the frame
	->anchor($field1) // anchor a field on the left
	->anchor($field2) // creates a new row and anchor a field on the left
	->anchorLeft($field3) // anchor a field next to the previous one
	->anchor($field4) // creates a new row and anchor a field on the left
	->anchorCenter($field5) // creates a new row and anchor a field at the center
	->newRow() // creates a new row
	->anchorRight($field6) // anchor a fields on the right of the row
	;

Using a P4A_Fieldset

$this->build("p4a_fieldset", "fieldset")
	->setWidth(600) // set the width of the fieldset
	->setLabel("This is a fieldset") // set the fieldset's title (HTML leged tag)
	->anchor($field1) // anchor a field on the left
	->anchor($field2) // creates a new row and anchor a field on the left
	->anchorLeft($field3) // anchor a field next to the previous one
	->anchor($field4) // creates a new row and anchor a field on the left
	->anchorCenter($field5) // creates a new row and anchor a field at the center
	->newRow() // creates a new row
	->anchorRight($field6) // anchor a fields on the right of the row
	;

Using a P4A_Canvas

$this->build("p4a_canvas", "canvas")
	->defineGrid(10, 10, 'px') // optional (these are the default values): defines the grid for object snapping
	->setOffset(50, 50) // shift every widget position by 50px both in horizontal and vertical position
	->anchor($field1, 10, 10) // anchor a field at 50 (offset top) + (10*10) px from the top/left of the canvas
	;

Using a P4A_Sheet

$this->build("p4a_sheet", "sheet", 2, 3) // instance a P4A_Sheet with 2 rows and 3 columns
	->anchor($field1, 1, 1) // anchor a field on the first column of the first row
	->anchor($field2, 1, 2) // anchor a field on the second column of the first row
	->anchor($field3, 1, 3) // anchor a field on the third column of the first row
	->anchor($field4, 2, 1, 1, 3) // anchor a field on the second row, with rowspan = 1 and colspan = 3
	;

Using tab panes

Tab_Pane is a useful widget when you have a lot of fields or widgets and you need to group them.

First we need to instance the Tab_Pane as you'd do for any other widget:

$t = $this->build("p4a_tab_pane", "tab_pane");

We can set some properties if we want:

$t->setWidth(800); // setting width to 800px

We can add all the pages we need:

$t->pages->build("p4a_frame", "page1")
	->setLabel("Page 1");
$t->pages->build("p4a_frame", "page2")
	->setLabel("Page 2");
// etc...

Note: In the example above we used P4A_Frames for the pages but you can use every layout manager you want (frames, canvas, sheets).

Now we can anchor all the fields/widgets we need on every page of the Tab_Pane:

$t->pages->page1
	->anchor($field_you_want)
	->anchor($widget_you_want);

Last thing, we need to anchor the Tab_Pane itself to a P4A_Frame (usual if working with P4A_Base_Mask):

$frame->anchor($t);

or you may want to display the Tab_Pane in a mask's template zone:

$this->display("main", $t);

That's it, now it's your turn to start playing with this component and learn how to use it the best way for your purposes.