QForm
QForm is a user interface library built into QCubed. As much as everybody likes the code generation of QCubed, an equally important piece of QCubed is QForms. So what are QForms?
"QForm is an object-oriented, stateful, event-driven architecture for form rendering and handling."
Nice... but what does it mean?
Let’s explore QForms by creating a sample application: a page with a button. The page will display how many times the button has been clicked.
A QForm based page consists of 2 files. For our first application, these will be:
-
example.phpOur controller, contains the logic of our application. -
example.tpl.phpThe view, contains the presentation layer of our application.
So, to create a basic QForm application, we need to create those 2 files.
example.php
<?php
// Load the Qcubed framework
require('includes/configuration/prepend.inc.php');
class Example extends QForm {
protected function Form_Create() {}
}
Example1::Run('Example');example.tpl.php
<!doctype html>
<html>
<head>
<title>Our first QCubed sample</title>
</head>
<body>
<?php $this->RenderBegin(); ?>
 <?php $this->RenderEnd(); ?>
</body>
</html>Let's take a closer look at example.php line by line:
require('includes/configuration/prepend.inc.php');
This is the line which tells the PHP page to load the QCubed framework. We will need to include this in every page where we want to use QCubed.
class Example extends QForm { ... }
We are going to create a QForm based application, so we create a new class called “Example”. We derive it from QForm, the parent of all forms.
protected function Form_Create() { ... }
The function Form_Create() is called the first time our page is loaded. We will have to put our initialization code here. For now, it is empty.
Example::Run('Example');
This calls the parent class' (remember, it’s QForm) Run() method, causing the framework to run the page. This ends our review of the example.php page.
The other file, example.tpl.php, you can see that the file contains mostly HTML. The only dynamic, non-HTML pieces are the following:
<?php $this->RenderBegin(); ?>
<?php $this->RenderEnd(); ?>This is necessary to allow the QForm framework to manage state.
Now, if we would fire up our browser, and load the example.php page, this does not show us much, does it? Let's add some things ( only title is present to confirm that our script is living).
First, think of Example as your application. Your application holds several other objects and variables. For this application, we will add 3 things: a variable to hold state and 2 controls (a label and a button)
To do this, add the following to example.php:
...
class Example1 extends QForm {
protected $intNumberOfClicks;
protected $lblNumberOfClicks;
protected $btnButton;
protected function Form_Create() {
...This defines the items we will use in our application: an integer, a label and a button.
Next, we will assign some default values to it. As explained above, we need to do this in the Form_Create() method, as this is where the initialization of our form happens:
protected function Form_Create() {
$this->intNumberOfClicks = 0;
$this->lblNumberOfClicks = new QLabel($this);
$this->lblNumberOfClicks->Text = $this->intNumberOfClicks;
$this->btnButton = new QButton($this);
$this->btnButton->Text = "Click Me";
}We also want to display the button and the label. We do this by calling the Render() method of the objects we want to display in example.tpl.php:
...
<?php $this->RenderBegin(); ?>
<?php $this->lblNumberOfClicks->Render(); ?>
<br/><br/>
<?php $this->btnButton->Render(); ?>
<?php $this->RenderEnd(); ?>
...Fire up that browser, and load the page:
This already shows something, but does not really do anything. So let’s add some events and event handling logic to take care of the “doing stuff” part.
Now we have the “event-driven” part: when we click the button, we want the form variable $intNumberOfClicks to be incremented, and the display to be updated. What we need to do is to assign an event to $btnButton. So in the Form_Create(), we add:
...
$this->btnButton->Text = "Click Me";
$this->btnButton->AddAction(new QClickEvent(), new QServerAction('btnButton_Click'));
...This tells the application that we want to have a new QServerAction. The function that will be executed is btnButton_Click(). So we also need to create this function:
protected function btnButton_Click($strFormId, $strControlId, $strParameter) {
$this->intNumberOfClicks++;
$this->lblNumberOfClicks->Text = $this->intNumberOfClicks;
}Save and refresh the page. When you click the button, you should now see the counter increment.
So, let us review the definition we started with:
"QForm is an object-oriented, stateful, event-driven architecture for form rendering and handling."
- Object-oriented: We created our own object “example”, assigned other objects to it, and assigned them values and events. Note that the object model also applies to the data objects, which we will cover later.
-
Stateful: Notice that QCubed "remembers" the value of the
$intNumberOfClicks. We did not have to store it in a session or database ourselves. - Event-driven: Make objects listen to events (such as in our example a click event), and execute some code in response to the registered events.
-
Form rendering and handling: Notice that we did not have to code any
<form>or<input>tags. QCubed handles this for us.
To summarize, to create a QForms application you need to
- Create 2 files, one for your logic and one for your presentation.
- In your .php file, create a new class derived from QForm. Add the objects you need for your application to it, assign default values and actions to it, and create the functions to handle your actions.
- In your .tpl.php file, define the layout, call
RenderBegin()andRenderEnd(), and for each control you need to display, call theRender()function.