ZForm User Manual
<<< Previous		Next >>>

Hello World Example

In this first example, we need two files: Hello.pm and hello.cgi. Hello.pm defines the form and the validation procedures associated with the form. hello.cgi defines the application logic.

The Perl Code

Form definition: Hello.pm

package Hello;
use base ZForm;

sub setup {
    my $self = shift();

    # Define the form
    my $fields = [
                  {'rm' => {
                       'type' => 'hidden',
                       'attr' => {
                           'default' => 'say_hello'}}},

                  {'name' => {
                       'type' => 'textfield',
                       'label' => 'Your name',
                       'attr' => {
                           'size' => '30'}}},
                  ];

    $self->form_def($fields);
}

1;

Application logic: hello.cgi

#!/usr/bin/perl

use lib '.';
use strict;
use warnings;
use CGI;
use Hello;

# Create a new cgi object
my $q = new CGI;

# Create an instance of our form and attach the cgi object
my $f = new Hello(cgi => $q);

# Placeholder for output
my $output = '';

if(defined($q->param('rm')) && $q->param('rm') eq 'say_hello') {
    # User clicked submit, so validate the form
    if($f->validate()) {
        # It validated! Say hello!
        $output = say_hello($q->param('name'));
    } else {
        # Didn't validate, so display the form with errors
        $output = $f->display();
    }
} else {
    # The user has not yet clicked submit, so display the empty form
    $output = $f->display();
}

# Display the output
print($q->header, $output);

sub say_hello {
    my $name = $f->values()->{'name'};
    my $output = $q->start_html("Hello $name");
    $output .= "<h1> Hello, $name </h1>";
    $output .= $q->end_html;

    return $output;
}

Wow! That sure is a lot of code just to to say hello to somebody! Frankly, if you are using ZForm on a project this simple, you may not want to use ZForm. ZForm is intended for larger projects.

Trying it out

Place these files someplace on your web server where CGI scripts can be executed.

Try submitting the form with no input. Notice how the "required field" error shows up to the right of the name field. If you look back to Hello.pm, you will notice that we never said anything about this being a required field. If you want a field to not be required, add "required => 'no'" in the field hash. We will discuss this more in the validation section.

Analysis of the code

Form Definition: Hello.pm

package Hello;
use base ZForm;

This names our packages and uses the ZForm class as our base class.

sub setup {
    my $self = shift();

    # Define the form
    my $fields = [

The fields in a form are defined as an array of hashes. The hashes hold the attributes and validation code for each field.

                  {'rm' => {
                       'type' => 'hidden',
                       'attr' => {
                           'default' => 'say_hello'}}},

This defines a hidden variable named action. The value of this hidden variable is 'say_hello'

The type is hidden. This is used to call the CGI.pm method called 'hidden' which generates the HTML for a hidden field. The attr value is passed to the hidden function. In other words, the function call to CGI.pm will look like:

$cgi->hidden(%attr);

                  {'name' => {
                       'type' => 'textfield',
                       'label' => 'Your name',
                       'attr' => {
                           'size' => '30'}}},
                  ];

This defines a text field with the name of... 'name'

As before, the CGI.pm function call will look like:

$cgi->textfield(%attr);

The label attribute defines the label that will be displayed to the left of the input field

    $self->form_def($fields);

Once the fields are defined, you must tell ZForm about these fields.

}

1;

All perl modules must end with the "1;" line.

Application Logic: hello.cgi

#!/usr/bin/perl

use lib '.';
use strict;
use warnings;
use CGI;
use Hello;

The usual stuff... make sure that we look for perl modules in our directory, use strict and warning, CGI, and our custom ZForm, Hello

# Create a new cgi object
my $q = new CGI;

# Create an instance of our form and attach the cgi object
my $f = new Hello(cgi => $q);

This creates a CGI object and a Hello object. All ZForm objects need a CGI object passed to the constructor.

# Placeholder for output
my $output = '';

Output from the ZForm object will be placed into a scalar as opposed to being displayed immediately. This makes it easy to output something completely different should an error occur later on

if(defined($q->param('rm')) && $q->param('rm') eq 'say_hello') {

Check to see if the user clicked the submit button. This looks at the hidden variable defined in Hello.pm called action. It needs to be both defined and equal to "say_hello" for us to proceed with processing the form

    # User clicked submit, so validate the form
    if($f->validate()) {
        # It validated! Say hello!
        $output = say_hello($q->param());

To validate the form, we use the validate() method. It returns true if the form validated

    } else {
        # Didn't validate, so display the form with errors
        $output = $f->display();
    }

If validate() returns false, we just redisplay the form. The form will be redisplayed with errors.

} else {
    # The user has not yet clicked submit, so display the empty form
    $output = $f->display();
}

In this case, the submit button was not clicked. Just display the blank form.

# Display the output
print($q->header, $output);

This is the part that actually displays some HTML.

sub say_hello {
    my $name = $f->values()->{'name'};
    my $output = $q->start_html("Hello $name");
    $output .= "<h1> Hello, $name </h1>";
    $output .= $q->end_html;

    return $output;
}

The say_hello() function displays the message should the form validate.