Home » Documentation » From A to Zoop

Guicontrols

07 Mar 2008 justin

Introduction

One of Zoop's unique features is guicontrols. Zoop's Guicontrol component uses the gui component and the validation component to provide excellent form controls. Guicontrols add validation to html's form controls and extend them to contain more controls than found in standard html (while remaining standards compliant).

Since most every webapplication uses forms to collect data from the users, learning how to use guicontrols effectively can save the programmer time and resources. They also provide security features that would be difficult to implement otherwise. Using Guicontrols.

Let's add some guicontrols to our Hello World application.

Our first step is to make sure that the guicontrol component is being included.

Open includes.php and make sure that

$zoop->addComponent('guicontrol');

is in there.

We are going to continue to work with the email_zone we created in last section. Create a new directory inside template/default called email. Now create a file in that directory called send.tpl with the following contents.

{include file="head.tpl"}	
<body>
<h1>Sending an email</h1>
<form method="POST">
	<p>
	From: {guicontrol type='text' name='from'}<br>
	To: {guicontrol type='text' name='to'}<br>
	Subject: {guicontrol type='text' name='subject'}<br>
	Message:<br> {guicontrol type='textarea' name='message'}<br>
	<input type="submit">
</form>
</body>
</html>

Something noteworty is that the form tag is missing an action. When the form tag doesn't have an action, the browser submits the POST to the same url as the page the form appears on. Also notice that the method is POST. Guicontrols require form data submitted through a POST to work properly.

Now lets return to zone_email and edit it to display this template and recieve to post.

New Concept:

ZooP has a special way of handling requests that have a POST in them. Instead of running the pageDefault function as we used previously, ZooP will run the postDefault function. So given the same url, Zoop will execute one of two different functions depending on if the request contains a POST or not.

Our pageSend function should now look like

function pageSend($inPath)
{
	$this->guidisplay("send.tpl");
}

Note: notice here we didn't use the $gui object as we did in previous instances. Zoop has a shortcut function called $this->guidisplay which will automatically look in the directory with the same name as your zone.. in our case it will look in "templates/default/email/".

We will create a new function called postSend which will recieve the post from the form we created.

! Important !

In Zoop any request containing a post should be send to a post function.

Given the same url, if there isn't a post attached, zoop will run the page function if there is a post attached it will first try to run the post function using the page function as a fallback.

The postSend function should look like this:

postSend($inPath)
{
	$post = getRawPost();
	echo_r($post);
}

Lets visit the same page in the web browser as we did previously, http://hostname/app_dir/email/send . We should see something similar to the screenshot below.

It isn't necessarily stylized very attractively, but it is a function form. Lets fill it out and see what happens when we hit submit... The postSend function should have echo'ed exactally what we entered as we asked it to. Unfortunately you may have noticed that the person that filled this form out doesn't like to play by the rules. Had we been sending a real email from this data it could have been fatal.

Validation made easy with guiControls

Now comes the best part about guiControls and Zoop, integrated validation. Zoop supports many different validation formats and this is just a simple introduction into using them... More information is available by looking through the validation component of zoop or looking through the autogen documentation.

Since we can't send an email from or to a first name or pronoun, we should probably ask for an email address and make sure we recieve one.

Additionally people like their emails to have a subject, so while we are at it, lets require a subject that is at least 5 characters long and no longer than 25.

Lastly an email should have a message with it so lets require that too.

Lets edit our send.tpl file again and place the following content into it.

{include file="head.tpl"}	
<body>
<h1>Sending an email</h1>
 
<div id='errorsbx'></div>
 
<form method="POST">
	<p>
	<label for="controls[text][from][value]">From:</label>
	{guicontrol type='text'
			name='from'
			_validate_type='email'
			_validate_required='true'}<br>
 
	<label for="controls[text][to][value]">To:</label>
	{guicontrol type='text'
			name='to'
			_validate_type='email'
			_validate_required='true'}<br>
 
	<label for="controls[text][subject][value]">Subject:</label>
	{guicontrol type='text'
			name='subject'
			_validate_type='length'
			_validate_min=5
			_validate_max=25
			_validate_required='true'}<br>
 
	<label for="controls[text][message][value]">Message:</label>
	<br> {guicontrol type='textarea'
			name='message'
			_validate_required='true'}<br>
	<br>
	<input type="submit" onclick="return submitForm(form);">
</form>
</body>
</html>

There are quite a few changes from before, but they are simple ones... Lets talk about each one and the conventions used.

First of all we added label tags and assigned them to their corresponding control (or form element).

Next we added validation to each of the controls. Since smarty doesn't provide a method of passing an array, we devised our own. Essentially we are defining a validate array using the "_" character as a seperator. We also start the parameter name with an underscore ("_") so as to distinguish it from other parameters which just have "_" in their name.

validate requires "type" to be set, but all other parameters are optional (though specific types may require parameters themselves).

Lastly we added a javascript function call to the submit button and an empty div above the form with the id "errorsbx". This is for the javascript validation. Zoop also provides server side validation... Lets try this form again and show you what we mean.

Example 1: With Javascript Enabled.

Notice the javascript validation steps through the form and shows you each part that is wrong. If a label exists, it highlights and and prevents the form from going forward until every field validates.

Your thinking, so what anyone can disable javascript and then our validation is worthless.... Perhaps in other frameworks but not in Zoop. Here is that same page with javascript disabled.

Naturally it validates the entire form at once since we don't want a lot of server trips.

Did you notice the best part... We didn't have to change our postSend function to handle the validation. Zoop does all the validation behind the scenes so when we access the post in our postSend function it has already been validated. postSend will never run unless the guiControls all pass validation.

The form also remembers the values we entered so the users don't have to enter them again. One final try... with the correct format and ...

‹ Zone CreationupMail ›