Introduction

Zoop as a framework provides both lower level and more advanced functionality. Forms is one of the more advanced functions within Zoop. It is built on top of the gui, guicontrol and db components and provides a bridge between them.

For the 1.2 Release of Zoop, Forms was redone to provide both better efficiency and an easier interface for the programmer.

Forms integrates the database with the gui offering a very nice answer to database driven forms, searching, and lists.

Extending Hello World using Forms2

We are going to pickup right where the database section left off. Make sure you have your database and table setup properly.

We are now going to create a few page functions with the intention of

1. Listing the user records in the database.
2. Editing the user records in the database.
3. Creating a new user record in the database.
4. Deleting a user record from the database.

We are also going to validate our user inputted data to ensure that proper information is received... Oh and we aren't going to touch html or sql for any of this.

Step 1: Listing the user records in the database.

Create a new page function called pageListUsers and put the following into it. I created a new zone (zone_users) to put it in, but you could put it in any zone you want.

function pageListUsers($inPath)
{
   global $gui;
   $form = new form2("users", "list");
   $form->setParam("zone", $this->zonename);
   $form->setTitle("Viewing Users");
   $form->setParam("listlink", "EditUser");
   $form->setFieldParam(array("password", "info"), "listshow", false);
   $form->setFieldParam(
	array("first_name", "username", "last_name"), 
	"clickable", true);
   $form->setFieldIndex("activated", array(1 => "y", 0 => ""));
   $form->setParam("deleteColumn", true);
   $form->setParam("deletelink", "DeleteUser");
 
   $form->guiAssign();
 
   $gui->generate("forms/form2.tpl", "blank.tpl", "mainmenu.tpl", "Users");
}

First the screenshot of the output then a discussion on what's going on here.

[???We need to get a screenshot, and put it here???]

What you are seeing in that screen shot is acutally only the relevant part of that page... The $gui->generate function includes the menu's, headers, css & js as well.

Now lets break down what we did.

We start out by instantiating our form object... and pass along the table and the type of form we want generated... a list in this case.

$form = new form2("users", "list");

We then tell the object which zone we will be linking things to(creating urls), in this case, $this->zonename.

$form->setParam("zone", $this->zonename);

The next line sets the title of the list, as seen in the screenshot.

$form->setTitle("Viewing Users");

Next we tell forms2 where to link the clickable fields to.. In this case we want them to goto the pageEditUser function in this same zone.

$form->setParam("listlink", "EditUser");

And now which Fields are shown in the list (by default all, so we turn a few to false).

$form->setFieldParam(array("password", "info"), "listshow", false);

The function setFieldParam can take either an array of fields or a single field as the first value.

We want to tell the object which fields are clickable. If we didn't do this the primary_key field would be clickable by default.

$form->setFieldParam(
	array("first_name", "username", "last_name"), 
	"clickable", true);

$form->setFieldIndex("activated", array(1 => "y", 0 => ""));

We tell it we want a delete column and which function to link it to.

$form->setParam("deleteColumn", true);
$form->setParam("deletelink", "DeleteUser");

Lastly we assign and display it (display is done using the generate function).

$form->guiAssign();
$gui->generate(
	"forms/form2.tpl", "blank.tpl", "mainmenu.tpl", "Users");

And to show you what is in the relevant template file, here is the form2.tpl file:

{forms2 form=$form}

Step2: Editing the user records in the database &
Step3: Creating a new user record in the database.

We are doing to do these steps together, because they are the exact same function.

We are going to create two functions, a page function and a post function.. We will call them EditUser, since that is what we setup the list to link to.

function pageEditUser($inPath)
{
  global $gui;
  $id = $inPath[1];
  $form = new form2("users", "record", $id);
  $form->setTitle("Editing Contact:" . $form->getValue("username"));
  $form->setValidationOptions("email_address", 
			array("type" => "email"));
  $form->required(array("email_address", "username"));
  $form->setFieldParam(array("password"), "formshow", false);
  $form->setHTMLoption('activated', 'type', 'checkbox');
  $form->setHTMLoption('info', 'type', 'textarea');
  $form->guiAssign();
 
  $this->session("form", $form);
  $gui->generate(
	"forms/form2.tpl", "blank.tpl", "mainmenu.tpl", "Users");
}
 
function postEditUser($inPath)
{
  $form = $this->session("form");
  $POST = getRawPost();
 
  $form->saveRecord($POST);
  zoneRedirect("/ListUsers");
}

Here I am going to show you two screenshots. The first come from going to [???some unknown link???]. The second [???some other uknown link???]. Which explains the difference between editing and creating a record using forms. The code is the exact same and knows how to handle a "new" record.

So lets break down what we did.

First we grab the passed $id from the path

$id = $inPath[1];

Next we instantiate the form object just like before, except this time of type "record" and pass in an id.

$form = new form2("users", "record", $id);

Title is the same as before, so after that we setup some validation for the fields. First make sure email is a validily formatted email address.

$form->setValidationOptions("email_address", 
			array("type" => "email"));

The validation type can be any validation found in the validator component of zoop.

And make sure email and username are inputted.

$form->required(array("email_address", "username"));

For whatever reason, we don't want to be able to view or edit the passwords, so we tell forms not to place that field in the form.

$form->setFieldParam(array("password"), "formshow", false);

For ease of use, we want to use a checkbox for the activated field, and a text area for info field.

$form->setHTMLoption('activated', 'type', 'checkbox');
$form->setHTMLoption('info', 'type', 'textarea');

The HTML type can be any valid guicontrol.

guiAssign as before then we want to store the form in the session. An easy way of doing that is with the zone session function. This needs to happen so the post function can pickup where we leave off.

$this->session("form", $form);

Generate as before... Onto the post function.

Here we start by retrieving the form object from the session.

$form = $this->session("form");

Next we get the post using getRawPost. We could use any of the post functions, but this one serves our purposes for an example.

$POST = getRawPost();

We tell the form object to save it's data

$form->saveRecord($POST);

And redirect to back to the list.

zoneRedirect("/ListUsers");

Step4: Deleting a user record from the database

This is the easiest step, not that any were hard. Remember back in step 1 we told the form object what to link the delete link to.. Lets create that function.

function pageDeleteUser($inPath)
{
   $id = $inPath[1];
   $form = &new form2("users");
   $form->deleteRecord($id);
 
   zoneRedirect("/ListUsers");
}