Here is a little tutorial to demonstrate how powerful is jForms, the Jelix form system.

First, let's create our application. After donwloading a jelix archive, extract it to your <jelix folder> of choice. Navigate to <jelix folder>/lib/jelix-scripts/ directory and type in a console:

  ./jelix --myapp createapp

Don't forget to change rights on <jelix folder>/temp/myapp/. This will allow your web server to create files in this directory. (see installation manual).

An application skeleton is created. Your local tree structure shall look like:

• myapp/
  • modules/
    • myapp/
      • classes/
      • controllers/
      • default.classic.php
    • dao/
    • forms/
    • locales/
    • templates/
    • zones/
  • plugins/
  • responses/
  • var/
  • www/
• lib/ (jelix libraries)
• temp/

myapp/ directory contains all files of your application. Note that there is another myapp/ folder in myapp/modules/ : by default createapp command creates a module with the same name of your application. This will be the main module of your application.

Then, copy the content of lib/jelix-www/ into myapp/www/jelix (or can declare an alias in apache, if preferred).

Now we're going to create a form. The only thing to do, is to create one xml file in the forms/ directory. We call it contact.form.xml. Here is its content:

 <?xml version="1.0" encoding="utf-8"?>
 <forms xmlns="http://jelix.org/ns/forms/1.0">
 
   <menulist ref="title">
      <label>Title</label>
      <item value="mr">Mr</item>
      <item value="mrs">Mrs</item>
   </menulist>
 
   <input ref="firstname" required="true">
      <label>First name</label>
   </input>
 
   <input ref="lastname" required="true">
      <label>Last name</label>
   </input>
 
   <input ref="email" required="true" type="email">
      <label>Email</label>
   </input>
 
   <submit ref="submit">
     <label>Contact us</label>
   </submit>
  </forms>

You can see that it is a declarative format. So it is easy to read and edit.

Now we're going to display the form. First you modify the default controller, default.classic.php:

 class defaultCtrl extends jController {
 
    function index() {
        $view = $this->getResponse('html');
        $view->title = "jForms example";
        $view->bodyTpl = 'myapp~main';
 
        $f = jForms::create("myapp~contact");
        $view->tpl->assign('form', $f );
 
        return $view;
    }
 }

At the first line, we retrieve an HTML view (a jHtmlResponse object) with the getResponse() method. Then we set the title of the page ($view→title). In the bodyTpl, we indicate the template to use for the main content of the page (the content of the body tag of a html page; the html header is generated automatically by the view). The given string is called a selector in Jelix. A selector specifies a resource in a module. Its syntax is “moduleName~resourceName”. So here, we says that the template will be the templates/main.tpl file in the myapp module.

Next, in the $f variable, we put an instance of the contact form. jforms creates dynamically a class from datas which are in the contact.form.xml and the “create” method creates an instance of this class. Note that this class inherits from the jFormsBase class.

Then we pass the $f variable to an instance of a template engine (jTpl which works like smarty) stored in $view→body.

At the end, we return the $view object and Jelix will end the job : the view will generate the page with the given template file, main.tpl.

Now let's create this template in myapp/templates/ directory :

 <h2>jForm example</h2>
 <p>Please fill out this form.</p>
 {formfull $form, "myapp~default:save", array(),'','','post'}

We use the template plugin formfull, which accepts as arguments a jFormsBase object, and the selector of the action where to submit datas.

At this step, you can execute the action, http://localhost/jelix/myapp/www/ (or http://localhost/jelix/myapp/www/index.php?module=myapp&action=default:index, this is the same thing because this action is the default one of the application), and you see the result :

When testing this form, you can see that a check is done on fields before the submit : some javascript code are generated automatically. Here is the generated html code :

 <form action="/jelix/myapp/www/index.php" method="post" id="jform1" onsubmit="return jForms.verifyForm(this)">
 <div>
      <input type="hidden" name="module" value="myapp"/>
      <input type="hidden" name="action" value="default:save"/>
 </div>
 <script type="text/javascript">
 //<![CDATA[
 jForms.tForm = new jFormsForm('jform1');
 jForms.tForm.setErrorDecorator(new jFormsErrorDecoratorAlert());
 jForms.tForm.setHelpDecorator(new jFormsHelpDecoratorAlert());
 jForms.tControl = new jFormsControl('title', 'Title', 'string');
 jForms.tControl.required = true;
 jForms.tControl.errRequired='La saisie de "Title" est obligatoire';
 jForms.tControl.errInvalid ='La saisie de "Title" est invalide';
 // (snip other javascript code...)
 //]]>
 </script>
 <table class="jforms-table" border="0">
 <tr>
    <th scope="row">  <label class="jforms-label jforms-required" for="jform1_title">Title</label> </th>
    <td> <select name="title" id="jform1_title" size="1">
              <option value="mr">Mr</option>
              <option value="mrs">Mrs</option>
         </select></td>
 </tr>
 <tr>
     <th scope="row"> <label class="jforms-label jforms-required" for="jform1_firstname">First name</label> </th>
     <td><input type="text" name="firstname" id="jform1_firstname" value=""/></td>
 </tr>
 <tr>
     <th scope="row"><label class="jforms-label jforms-required" for="jform1_lastname">Last name</label></th>
     <td><input type="text" name="lastname" id="jform1_lastname" value=""/></td>
 </tr>
 <tr>
    <th scope="row"><label class="jforms-label jforms-required" for="jform1_email">Email</label></th>
    <td><input type="text" name="email" id="jform1_email" value=""/></td>
 </tr>
 </table>
 
 <div class="jforms-submit-buttons">
    <input type="submit" name="submit" id="jform1_submit" class="jforms-submit" value="Contact us"/>
 </div>
 </form>

Note that some CSS classes facilitate the designing of the form. formfull plugin generate the form in an HTML table, but of course you can change this, by using other plugins, which allow you to control how to generate html. Let's change that in the main.tpl file.

 <h2>jForm example</h2>
 {form $form, "myapp~default:save", array(),'','','post'}
  <fieldset>
     <legend>Please fill out this form:</legend>
     <dl>
      {formcontrols}
         <dt> {ctrl_label}</dt>
         <dd> {ctrl_control} </dd>
      {/formcontrols}
      </dl>
   </fieldset>
   <div> {formsubmit} </div>
 {/form}

We use here the form plugin instead of formfull. Its arguments are same. formcontrols plugin do a loop over the fields declared in the contact.form.xml (except submit and reset controls), and you can display the label and the field with ctrl_label and ctrl_control. formsubmit displays all submit controls.

Here is the result of this template :

Now we're going to create the save method indicated in the arguments of the form plugin. We add this methods in default.classic.php.

    function save() {
        $view = $this->getResponse('html');
        $view->title = "jForms example : end";
 
        $f = jForms::fill("myapp~contact");
        if(!$f || !$f->check()) {
            $rep = $this->getResponse('redirect');
            $rep->action="myapp~default:index";
            return $rep;
        }
 
        $view->bodyTpl = 'myapp~contact_ok';
        $view->body->assign('form', $f );
        return $view;
    }

To get the instance of the form, and by the same time to fill it with submitted datas, we use the fill method. Then we test if this instance doesn't exist (!$f) or if there are bad datas (!$f→check()). If this is the case, we made a redirection to the first action and then the form will be displayed again with error messages: this is automatic ! However, we should change the index method. Replace $f = jForms::create(“myapp~contact”); by

    $f = jForms::get("myapp~contact");
    if(!$f)
       $f = jForms::create("myapp~contact");

So here, we try to get an existing instance of the form, and if not, we create a new instance.

In save method, after the test, this is the opportunity to execute business code (not shown in this tutorial). For example:

    $alldatas = $f->getDatas();
    $firstname = $f->getData('firstname');
    // etc.

And at the end of the process, we could display submitted datas and says thank you. Here is the contact_ok.tpl file:

 <h2>jForm example</h2>
 
  <fieldset>
     <legend>Datas you have submited.</legend>
     <dl>
      {formcontrols $form, array('title','lastname','firstname','email')}
         <dt> {ctrl_label}</dt>
         <dd> {ctrl_value} </dd>
      {/formcontrols}
      </dl>
   </fieldset>
 
  <p>We will contact us. Thank you !</p>

We use again the formcontrols plugin, but in a standalone manner (so not with a form plugin). We indicate as arguments the jFormsBase object ($form), and the list of controls to display (it is optional).

That's all ! We saw how it is easy with jForms :

• to create a form
• to show a form
• to retrieve submitted datas
• to validate submitted datas (this is done automatically !)
• to show the form again with errors

Notice that jForms has many other features, which allow you :

• to create your own form “builder”, so plugins could displays the form, not in HTML, but in other format like Xforms, XUL, or in HTML+ajax etc.
• to specify your own error messages
• to manage how error messages are displayed
• to display helps and tooltip
• to fill menulist, listbox etc automatically, from a jDao object (the ORM layer of Jelix)
• to store automatically datas with a jDao object
• to create quickly a CRUD controller, by using the jControllerDaoCrud controller (only indicate a jforms file, a jdao file, and that's all !)
• and many other controls are availabled: <textarea>, <listbox>, <checkbox>, <checkboxes>, <radiobuttons>, <reset>, <secret>, <secret>+<confirmation>, <upload>
• some others will be available soon: <htmleditor> <hidden>…