de­page-forms: html5 forms made easy (Part I)

, by Frank Hel­lenkamp / Se­bas­t­ian Rein­hold

HTML forms: Easy and dif­fi­cult at the same time

HTML-Forms are sim­ple to write – but to do it in a good way and to make them com­fort­able to use is not an easy task. 

There are a few things you will have to do again and again: 

  • Write the HTML for the form it­self
  • Style the form in the right way
  • Val­i­date the data in the brows­er (op­tion­al)
  • Val­i­date the data on the serv­er (never op­tion­al - don't for­get!)
  • Ad­di­tion­al­ly make sure the user don't have to fight with the brows­er e.g. strange mes­sages about "re­send­ing" data on re­load­ing the page and using back- and for­ward-but­tons.

This is a part of the on­go­ing se­ries about de­page-forms

For­get about fight­ing!

Be­cause we did not want to fight any­more, we are in­tro­duc­ing today:  

de­page-forms – htm­l5-forms made easy! 

 

Doc­u­men­ta­tion

Fork us/Source-Code

de­page-forms is PHP li­brary for HTML form gen­er­a­tion with focus on us­abil­i­ty for de­vel­op­ers and users.  

 

It is part of the up­com­ing ver­sion of de­page-cms, but it also works as a stand­alone li­brary. By ab­stract­ing HTML, brows­er flaws (du­pli­cate form sub­mis­sions) and form val­i­da­tion, it pro­vides a com­fort­able way to ob­tain re­li­able and val­i­dat­ed data from users. 

 

We are (by far) not the first try­ing to solve these prob­lems. For PHP there are Zend-Forms and Phorms for ex­am­ple. But I think we found a rather unique ap­proach to solve these prob­lem. 

So, how does it work?

First we load the Li­brary and ini­tial­ize an in­stance of the html­forms-class. Al­most every ac­tion goes through the html­forms-class. Be­sides field­sets and steps (later more about this) we only talk to in­stances of the html­form di­rect­ly. 

<?php
require_once('path/to/htmlform.php');

$form = new depage\htmlform\htmlform('simpleForm');

After that, we add our in­puts and other form­fields to our form. 

 

You can do this by call­ing the '"add" + el­e­ment type' method. The first pa­ra­me­ter is the name of the el­e­ment. It has to be unique. The op­tion­al sec­ond pa­ra­me­ter is an array of var­i­ous el­e­ment set­tings. Every­thing in the set­tings-ar­ray is op­tion­al and has a sen­si­ble de­fault. 

 

E.g.: If you don't give a la­bel-pa­ra­me­ter html­forms will use the name of the input as label. You can also add a re­quired-pa­ra­me­ter, so you won't be able to fin­ish the form with­out fill­ing a re­quired-in­put. 

$form->addText('username', array(
	'label' => 'User name', 
	'required' => true,
));
$form->addEmail('email', array(
	'label' => 'Email address',
));

Next comes the pro­cess­ing — The process-method is es­sen­tial and the back­bone of the html­forms-class: 

  • It val­i­dates sub­mit­ted data if there is any.
  • It redi­rects to the suc­cess page if all the data is valid and all re­quired fields are filled in.
  • It stores the data in the ses­sion and redi­rects to the form to cir­cum­vent the form re­sub­mis­sion prob­lem. That means, that every form is sent with a POST-Re­quest and then redi­rect­ed to dis­play the form again through a GET-Re­quest. For more info: PRG-Pat­tern on Wikipedia

 

(Note: Make sure to call the process-method be­fore any out­put, so the form is able to redi­rect it­self.) 

$form->process();

Now after pro­cess­ing the form we know if the sub­mit­ted data is valid: 

  • If the data is valid, we can do what­ev­er we want with it. In this ex­am­ple we just dump it to the out­put. The sub­mit­ted data is saved in a ses­sion until the ses­sion is cleared (which we do here) or the ses­sion has timed out.
  • If the form is empty or the sub­mit­ted data is not valid we out­put the form with "echo" which will out­put the html-source for the form.
if ($form->validate()) {
    var_dump($form->getValues());

    $form->clearSession();
} else {
    echo ($form);
}

Live-Ex­am­ple

Here's the live-ex­am­ple: 

http://​docs.​depage.​net/​depage-forms/​documentation/​html/​simple_​8php-example.​html 

Next Steps

In the next posts about de­page-forms we will in­tro­duce some ex­tend­ed fea­tures like: