documentation/manual/en/tutorials/quickstart-create-form.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="learning.quickstart.create-form">
   4     <title>Create A Form</title>
   5
   6     <para>
   7         For our guestbook to be useful, we need a form for submitting new entries.
   8     </para>
   9
  10     <para>
  11         Our first order of business is to create the actual form class. To create the empty form
  12         class, execute:
  13     </para>
  14
  15     <programlisting language="shell"><![CDATA[
  16 % zf create form Guestbook
  17 Creating a form at application/forms/Guestbook.php
  18 Updating project profile '.zfproject.xml'
  19 ]]></programlisting>
  20
  21     <para>
  22         This will create the directory <filename>application/forms/</filename> with the classfile
  23         <filename>Guestbook.php</filename>. Open that file and update it so it reads as follows:
  24     </para>
  25
  26     <programlisting language="php"><![CDATA[
  27 // application/forms/Guestbook.php
  28
  29 class Application_Form_Guestbook extends Zend_Form
  30 {
  31     public function init()
  32     {
  33         // Set the method for the display form to POST
  34         $this->setMethod('post');
  35
  36         // Add an email element
  37         $this->addElement('text', 'email', array(
  38             'label'      => 'Your email address:',
  39             'required'   => true,
  40             'filters'    => array('StringTrim'),
  41             'validators' => array(
  42                 'EmailAddress',
  43             )
  44         ));
  45
  46         // Add the comment element
  47         $this->addElement('textarea', 'comment', array(
  48             'label'      => 'Please Comment:',
  49             'required'   => true,
  50             'validators' => array(
  51                 array('validator' => 'StringLength', 'options' => array(0, 20))
  52                 )
  53         ));
  54
  55         // Add a captcha
  56         $this->addElement('captcha', 'captcha', array(
  57             'label'      => 'Please enter the 5 letters displayed below:',
  58             'required'   => true,
  59             'captcha'    => array(
  60                 'captcha' => 'Figlet',
  61                 'wordLen' => 5,
  62                 'timeout' => 300
  63             )
  64         ));
  65
  66         // Add the submit button
  67         $this->addElement('submit', 'submit', array(
  68             'ignore'   => true,
  69             'label'    => 'Sign Guestbook',
  70         ));
  71
  72         // And finally add some CSRF protection
  73         $this->addElement('hash', 'csrf', array(
  74             'ignore' => true,
  75         ));
  76     }
  77 }
  78 ]]></programlisting>
  79
  80     <para>
  81         The above form defines five elements: an email address field, a comment field, a
  82         <acronym>CAPTCHA</acronym> for preventing spam submissions, a submit button, and a
  83         <acronym>CSRF</acronym> protection token.
  84     </para>
  85
  86     <para>
  87         Next, we will add a <methodname>signAction()</methodname> to our
  88         <classname>GuestbookController</classname> which will process the form upon submission. To
  89         create the action and related view script, execute the following:
  90     </para>
  91
  92     <programlisting language="shell"><![CDATA[
  93 % zf create action sign Guestbook
  94 Creating an action named sign inside controller
  95     at application/controllers/GuestbookController.php
  96 Updating project profile '.zfproject.xml'
  97 Creating a view script for the sign action method
  98     at application/views/scripts/guestbook/sign.phtml
  99 Updating project profile '.zfproject.xml'
 100 ]]></programlisting>
 101
 102     <para>
 103         As you can see from the output, this will create a <methodname>signAction()</methodname>
 104         method in our controller, as well as the appropriate view script.
 105     </para>
 106
 107     <para>
 108         Let's add some logic into our guestbook controller's sign action. We need to first check if
 109         we're getting a <acronym>POST</acronym> or a <acronym>GET</acronym> request; in the latter
 110         case, we'll simply display the form. However, if we get a <acronym>POST</acronym> request,
 111         we'll want to validate the posted data against our form, and, if valid, create a new entry
 112         and save it. The logic might look like this:
 113     </para>
 114
 115     <programlisting language="php"><![CDATA[
 116 // application/controllers/GuestbookController.php
 117
 118 class GuestbookController extends Zend_Controller_Action
 119 {
 120     // snipping indexAction()...
 121
 122     public function signAction()
 123     {
 124         $request = $this->getRequest();
 125         $form    = new Application_Form_Guestbook();
 126
 127         if ($this->getRequest()->isPost()) {
 128             if ($form->isValid($request->getPost())) {
 129                 $comment = new Application_Model_Guestbook($form->getValues());
 130                 $mapper  = new Application_Model_GuestbookMapper();
 131                 $mapper->save($comment);
 132                 return $this->_helper->redirector('index');
 133             }
 134         }
 135
 136         $this->view->form = $form;
 137     }
 138 }
 139 ]]></programlisting>
 140
 141     <para>
 142         Of course, we also need to edit the view script; edit
 143         <filename>application/views/scripts/guestbook/sign.phtml</filename> to read:
 144     </para>
 145
 146     <programlisting language="php"><![CDATA[
 147 <!-- application/views/scripts/guestbook/sign.phtml -->
 148
 149 Please use the form below to sign our guestbook!
 150
 151 <?php
 152 $this->form->setAction($this->url());
 153 echo $this->form;
 154 ]]></programlisting>
 155
 156     <note>
 157         <title>Better Looking Forms</title>
 158
 159         <para>
 160             No one will be waxing poetic about the beauty of this form anytime soon. No matter -
 161             form appearance is fully customizable! See the <link
 162                 linkend="zend.form.decorators">decorators section in the reference guide</link>
 163             for details.
 164         </para>
 165
 166         <para>
 167             Additionally, you may be interested in <link
 168                 linkend="learning.form.decorators.intro">our tutorial on form decorators</link>.
 169         </para>
 170     </note>
 171
 172     <note>
 173         <title>Checkpoint</title>
 174
 175         <para>
 176             Now browse to "http://localhost/guestbook/sign". You should see the following in your
 177             browser:
 178         </para>
 179
 180         <para>
 181             <inlinegraphic width="421" scale="100" align="center" valign="middle"
 182                 fileref="figures/learning.quickstart.create-form.png" format="PNG" />
 183         </para>
 184     </note>
 185 </sect1>