RocketSled Tutorial 3: FormML

Author: David Grinton thegrinch@workingsoftware.com.au

Table of Contents

• Introduction
• The AddPastry class
• RSML for the AddPastry handler
• Our first FormML

Introduction

Welcome to RocketSled Tutorial 3.

This tutorial follows on from RocketSled Tutorial 2, and covers the use of Form Markup Language to create a basic form with validation.

The AddPastry class

First create a new Handler for the form in WEBROOT/yourdir/packages/my/add_pastry.class.php with the following code:

<?php
   class AddPastry extends Handler
   {
      public function AddPastry()
      {
         $name = 'AddPastry';
         $description = 'Add new pastries here';
         $this->Handler($name, $description);
      }
 
      public function display()
      {
         $disp = Display::current();
 
         $form = Form::load('my.NewPastry');
         $disp->addForm($form);
         $disp->addView('page_content','my.AddPastry');
 
         $disp->displaySiteTemplate();
      }
 
      public function performHandlerTasks()
      {
         if(Application::formPosted())
         {
            $form = Form::load('my.NewPastry');
 
            $form->validate();
         }
      }
   }
?>

Note the lines $form = Form::load('my.NewPastry'); and $disp->addForm($form);

Also note that we have now added some code to the performHandlerTasks() method. This method is called by the Application class before the display() method is called - in this way the data posted from the form can be validated before the form is displayed again.

In the performHandlerTasks() the Application::formPosted() method is used to determine if any form has been posted (this is done by checking GET/POST variables as well as commandline arguments and values set with setValue()). Here we have simply loaded and validated the form and ignored the result, but the validate() method returns a true or false value which can then be acted on to perform further actions.

The validate() method can be called with an optional argument - the name of a field to validate. If the argument is not supplied it will validate all fields.

RSML for the AddPastry handler

Next we need an RSML document to go with the new handler class, create WEBROOT/yourdir/packages/my/add_pastry.rsml.php with the following code:

<fragment>
   <h2>Add Pastry</h2>
   <view-form name="NewPastryDetails"/>
</fragment>

Our first FormML

The <view-form> tag in the RSML document refers to a form NewPastryDetails which we must next create with a form ML document. Add a file new_pastry.frm.php in WEBROOT/yourdir/packages/my/ with the following code:

<form name="NewPastryDetails" handler="AddPastry">
   <form-error name="newPastryName">MESSAGE<br/></form-error>
   <label id="newPastryDetailsNewPastryNameLabel" for="newPastryName">
       Pastry name:
   </label>
   <text-line name="newPastryName">
      <validation type="REQUIRED">
         <error-message>Please enter the pastry name.</error-message>
      </validation>
   </text-line>
   <submit name="addPastry" value="Add"/>
</form>

We have now defined the NewPastryDetails form, and specified that it will be handled by the AddPastry class when submitted.

In the form ML document, the <form-error> tag defines a section which will only be displayed if the validate() method of the form has been called and the "name" item on the form did not pass its validation rule (if any).

The <label> tag simply displays a label to accompany the following <text-line> element.

The <text-line> element is similar to a traditional html text input, but notice the <validation> section within it, which in this case simply specifies that the "name" <text-line> must be filled in (this is used when validate() is called on the form). Read more about FormML validation here.

Last is the <submit> element which is analogous to the <submit> tag on a traditional html form.

Note that you can also use standard html tags in form ML documents, for example a label could contain an <img> tag.

The new handler and form can be viewed at WEBROOT/yourdir/index.php?h=AddPastry (but the form will do nothing when submitted except validate and display a validation error if appropriate).