Creating Contact Page

We have created a default page Home.page using the PRADO command line tool. The page is relatively static because it does not containt dynamic content. In this section, we will create an interactive page named Contact.

The purpose of the Contact page is to collect feedback from Web users of our blog system. To achieve this goal, we plan to present users a feedback form to fill with. In this form, we will require users to provide their name, email address and feedback content. After the form is filled and submitted, an email containing the feedback will be sent to the site administrator.

To create the Contact page, we need two files under the pages directory: the page template file Contact.page and the page class file Contact.php.

Info: A page must have either a template file (extension .page) or a class file, or both:

  • A template-only page is usually a page with static content, like the homepage we already created;
  • A class-only page produces content purely based on the execution of the class methods;
  • A page with both template and class combines the advantage of both: it uses template to easily organize the page layout and it uses class to contain necessary logic producing dynamic content.

Creating Page Template

We first create the template file for the Contact page.

We use template to organize the presentational layout of the feedback form. In the template, we use textboxes to collect user's name, email and feedback. And we use validators to ensure that the user provides all these information before submitting the feedback form. The whole template is as follows, 

<html>
<head><title>My Blog - Contact</title></head>
<body>
<h1>Contact</h1>
<p>Please fill out the following form to let me know your feedback on my blog. Thanks!</p>

<com:TForm>

<span>Your Name:</span>
<com:TRequiredFieldValidator ControlToValidate="Name"
    ErrorMessage="Please provide your name."
    Display="Dynamic" />
<br/>
<com:TTextBox ID="Name" />

<br/>
<span>Your Email:</span>
<com:TRequiredFieldValidator ControlToValidate="Email"
    ErrorMessage="Please provide your email address."
    Display="Dynamic" />
<com:TEmailAddressValidator ControlToValidate="Email"
    ErrorMessage="You entered an invalid email address."
    Display="Dynamic" />
<br/>
<com:TTextBox ID="Email" />

<br/>
<span>Feedback:</span>
<com:TRequiredFieldValidator ControlToValidate="Feedback"
    ErrorMessage="Please provide your feedback."
    Display="Dynamic" />
<br/>
<com:TTextBox ID="Feedback"
    TextMode="MultiLine"
    Rows="10"
    Columns="40" />

<br/>
<com:TButton Text="Submit" OnClick="submitButtonClicked" />

</com:TForm>

</body>
</html>

As we can see that the template looks very similar to a normal HTML page. The main difference is that the template contains a few <com:> tags. Each <com:> tag refers to a control whose properties are being initialized with name-value pairs in the tag. For example, the <com:TButton> refers to the TButton control which displays a button that users can click on to submit the feedback form. For complete template syntax, please refer to the Quickstart Tutorial.

Info: PRADO provides a control for every type of HTML input. For example, TTextBox displays a text input field, TDropDownList displays a combobox. Each control is a component that may be accessed in code as an object with configurable properties.

Besides TTextBox controls, the template also uses many validator controls which ensure user's inputs satisfy specific validation rules. For example, to ensure a legitimate email address is provided, we use two validators to validate the "email" text box, as shown in the following: 

<span>Your Email:</span>
<com:TRequiredFieldValidator
    ControlToValidate="Email"
    ErrorMessage="Please provide your email address."
    Display="Dynamic" />
<com:TEmailAddressValidator
    ControlToValidate="Email"
    ErrorMessage="You entered an invalid email address."
    Display="Dynamic" />
<br/>
<com:TTextBox ID="Email" />
<br/>

Below we summarize the controls that are used in the page template:

  • TForm displays an HTML form. Any input control must be enclosed within it. And most importantly, at most one TForm may appear in a page.
  • TTextBox displays a text box to collect user text input.
  • TRequiredFieldValidator ensures that the associated text box is not empty when the feedback is submitted.
  • TEmailAddressValidator ensures that the textbox contains a valid email address when the feedback is submitted.
Tip: Writing templates with plain text editors could be tedious and not intuitive for designers. To ease this situation, PRADO has included in the releases an Adobe Dreamweaver extension that supports auto-completing PRADO tags (e.g. including control names, property names, event names, etc.) in Dreamweaver.

Creating Page Class

We now create the page class Contact.php. The reason we need a page class is because we need to respond to the feedback that the user submits.

Notice in the template we have the following line. The template essentially states that when a user clicks on the button, it should call the submitButtonClicked() method. Here OnClick is the name of the user click event, and the method must be defined in the page class. 

<com:TButton Text="Submit" OnClick="submitButtonClicked" />

We thus write down the page class as follows: 

<?php
class Contact extends TPage
{
    /**
     * Event handler for the OnClick event of the submit button.
     * @param TButton the button triggering the event
     * @param TEventParameter event parameter (null here)
     */
    public function submitButtonClicked($sender, $param)
    {
        if ($this->IsValid)  // check if input validation is successful
        {
            // obtain the user name, email, feedback from the textboxes
            $name = $this->Name->Text;
            $email = $this->Email->Text;
            $feedback = $this->Feedback->Text;

            // send an email to administrator with the above information
            $this->mailFeedback($name, $email, $feedback);
        }
    }

    protected function mailFeedback($name, $email, $feedback)
    {
        // implementation of sending the feedback email
    }
}

The above code is largely self-explanatory. In fact, we just show the event-driven programming scheme. In the event handler submitButtonClicked(), we retrieve the user's input. For example, $this->Name->Text returns the Text property value of the Name control which is the textbox collecting user's name information.

Info: Page class name must be the same as the file name. This is also a requirement for writing any PRADO component class.

Testing

Our newly created Contact can be tested via the URL http://hostname/blog/index.php?page=Contact. If we click on the submit button without entering any information, we will see error messages appearing next to the corresponding textboxes. If we enter all required information, the method mailFeedback() will be invoked.

A further enhancement to this page is to show some confirmation message on the page after the user submits feedback. And possibly, the browser may be redirected to another page if the submission is successful. We will leave these tasks to our readers.

Info: Each validator represents a validation rule. A single input control can be associated with one or multiple validators. Validators perform validation on both client side and server side. On the client side, namely the browser, validation is done using javascript; on the server side, validation is done using PHP code. Client-side validation can be turned off, while server-side validation cannot. This ensures user inputs are always checked by the specified validation rules.