display.gtw

~~LANG:FR@frman:jforms/affichage~~

To display a form and its data, you could call @@M@getAllData@@ on your form object and assign its returned array to a template. With it, you'll be able to generate your HTML form along with its data. if you want to display input errors, call @@M@getErrors@@ to retrieve them and again display them as you like in your template.

However there are some template plugins in Jelix, to prevent you from doing this long and sometimes boring task. They even do a lot more:
 
  * display each control field as described in your XML form,
  * display each control label in @@E@<label>@@ tag to improve ergonomy and accessibility,
  * display error messages,
  * display help messages,
  * generate javascript for client-side checking before posting data,
  * valid HTML generated and good support of accessibility,
  * ids and classes on elements to ease styling.


===== Full automatic form display with formfull =====

For you in a hurry, this template plugin will fully display your form. Its name:  @@formfull@@. With it, you won't control how each field, labels and submits are displayed. Still you can customize display of help and error messages (see further).

Here are its arguments, in the order:

   * your form object
   * a selector specifying the target action
   * optional:
      * an array containing extra url parameters (other than fields data)
      * the name of the builder ('html' or 'htmllight' for instance)
      * an array containing options for the builder

Example in your controller :

<code php>
    $form = jForms::get('myform');
    $tpl = new jTpl();
    $tpl->assign('form', $form);
</code>

And in your template :

<code html>
   <h1>My form</h1>
   <p>Fill this form :</p>

   {formfull $form, 'mymodule~default:save'}

</code>

Labels and control fields will be displayed in a table, and submit buttons in a div below.

Note: because of some limitations of the plugin formfull and the template engine, don't use the plugin inside a loop, where the variable passed to the plugin is generated by the loop (typically, in a foreach). In this case, JS and CSS files won't be loaded in the page. A solution is to indicate yourself all CSS and JS files needed by your form.

===== Customized display =====

There is not only @@formfull@@. Other plugins exist to control how your form is displayed and precisely in which markup your form controls are wrapped. 

The first one @@form@@ is the equivalent to @@formfull@@ except that its a block plugin. It means that it has an end tag and should contains other plugins and markup controlling the display of your form. Arguments for @@form@@ are : 

   * your form object
   * a selector specifying the target action
   * optional:
      * an array containing extra url parameters (other than fields data)
      * the name of the builder ('html' or 'htmllight' for instance)
      * an array containing options for the builder


Note: As for the formfull plugin, there are some limitations in the plugin form and the template engine, so don't use the plugin inside a loop, where the variable passed to the plugin is generated by the loop (typically, in a foreach). In this case, JS and CSS files won't be loaded in the page. A solution is to indicate yourself all CSS and JS files needed by your form.


==== Simple display ====

@@formcontrols@@ plugins loops on form controls (neither submits nor reset). It is a block plugin. Within it, @@ctrl_label@@ and @@ctrl_control@@ plugins will display respectively label and field of current control. To display submit buttons or reset, use @@formsubmit@@ and @@formreset@@.

Example :

<code html>
  {form $form, 'mymodule~default:save'}

   <fieldset><legend>Fill : </legend>

      {formcontrols}
         <p> {ctrl_label} : {ctrl_control} </p>
      {/formcontrols}

   </fieldset>

   <div> {formreset}{formsubmit} </div>

  {/form}
</code>

Note that form fields will be displayed in the order of their declaration in your XML file. Note also that template here is totally independent of form content and could be reused with more forms.


==== Advanced display ====

Some controls need to be displayed differently. To achieve this, you can use @@ifctrl@@ inside @@formcontrols@@. Its argument is a list of control names. The code below adds a class on 'name' control only: 

<code html>
  {form $form, 'mymodule~default:save'}

   <fieldset><legend>Your identtity : </legend>

      {formcontrols}            
         <p {ifctrl 'name'}class="help-needed"{/if}> {ctrl_label} : {ctrl_control} </p>
      {/formcontrols}

   </fieldset>
</code>


Or else, indicate a list of control names to @@formcontrols@@ plugin. It will loop only on those controls. 

<code html>
  {form $form, 'mymodule~default:save'}

   <fieldset><legend>Identity : </legend>

      {formcontrols array('lastname','firstname','address')}
         <p> {ctrl_label} : {ctrl_control} </p>
      {/formcontrols}

   </fieldset>
   <fieldset><legend>Other fields : </legend>

      {formcontrols}
         <p> {ctrl_label} : {ctrl_control} </p>
      {/formcontrols}

   </fieldset>

   <div> {formsubmit} </div>
  {/form}
</code>

Above, we display a series of controls in a first fieldset (lastname, firstname and address) and the others in a second fieldset: @@formcontrols@@ loops over controls not already displayed.

Note that @@ctrl_label@@ and @@ctrl_control@@ also function outside of @@formcontrols@@. In that case, you should indicate a control name.

<code html>
  {form $form, 'mymodule~default:save'}

   <fieldset><legend>Identity : </legend>

        <table>
          <tr><td>{ctrl_label 'lastname'}</td><td>{ctrl_control 'lastname'}</td> </tr>
          <tr><td>{ctrl_label 'firstname'}</td><td>{ctrl_control 'firstname'}</td></tr>
        </table>

   </fieldset>
   <fieldset><legend>Other fields : </legend>

      {formcontrols}
         <p> {ctrl_label} : {ctrl_control} </p>
      {/formcontrols}

   </fieldset>

   <div> {formsubmit} </div>
  {/form}
</code>

Lastname and firstname fields are displayed precisely in a table whereas other fields are displayed with @@formcontrols@@.

=== Custom attributes ===

You can add some html attributes on the HTML element generated with @@ctrl_control@@. To do it, add a second parameter to the @@ctrl_control@@ tag: it should be an array @@('attribute name'=>'attribute value')@@. Give @@L@""@@ as first parameter when @@ctrl_control@@ is used inside a @@formcontrols@@ loop.

==== Customizing display of password controls ====

Beware that if a password control defines a confirm field (@@E@<confirm>@@ tag in XML) you should control either the display of @@password@@ field **and** @@confirm@@ field. The confirm control name is a concatenation of password control name + @@_confirm@@.

See example below:

<code html>
  {form $form, 'mymodule~default:save'}
   <fieldset><legend>Account creation : </legend>
        <table>
          <tr><td>{ctrl_label 'login'}</td><td>{ctrl_control 'login'}</td> </tr>
          <tr><td>{ctrl_label 'password'}</td><td>{ctrl_control 'password'}</td></tr>
        </table>
   </fieldset>
   <fieldset><legend>Other infos : </legend>
      {formcontrols}
         <p> {ctrl_label} : {ctrl_control} </p>
      {/formcontrols}
   </fieldset>
   <div> {formsubmit} </div>
  {/form}
</code>

Confirm field will appear in the second fieldset and not near password field in the example above. To do so, just display 'password_confirm' in a row below 'password'  :

<code html>
   <table>
      <tr><td>{ctrl_label 'login'}</td><td>{ctrl_control 'login'}</td> </tr>
          <tr><td>{ctrl_label 'password'}</td><td>{ctrl_control 'password'}</td></tr>          <tr><td>{ctrl_label 'password_confirm'}</td><td>{ctrl_control 'password_confirm'}</td></tr>
   </table>
</code>

On the contrary, you should not take care of confirm field in @@formcontrols@@ loop.


==== Customizing display of submit buttons ====

As you may recall, @@formsubmit@@ template plugin displays a submit button declared in your form. But if one declares more than one submit button, @@formsubmit@@ will display only the first one. In that case, use  @@formsubmits@@ (note the ending **s**). This block template loops over submit buttons :

<code html>
    <ul>
    {formsubmits}
       <li>{formsubmit}</li>
    {/formsubmits}
    </ul>
</code>

Another way is to use @@formsubmit@@ multiple times indicating each submit name :

<code html>
<div> {formsubmit 'preview'} {formsubmit 'save'} </div>
</code>

**Beware** : @@{formsubmits}@@ loops over submit **controls**, not submit **items**! It is not possible to loop over submit items (see [[ticket:429|ticket #429]])


===== Generator choice =====

jForms template plugins relies on other plugins. Those are jForms plugins and generate effectively a form content (label and fields markup). These are called generators. Jelix 1.1 and 1.2 packages have two of them inside : @@L@htm@@ and @@L@htmllight@@. [[/plugins/jforms|See documentation to create your own]] if you need to display custom markup. If you need a generator supporting a javascript library as extjs, or an ajax form, or a XUL form... 

Jelix default generator is @@L@html@@. You can change this in your configuration file. Use @@V@defaultJformsBuild@@ variable and assign it your generator of choice :

<code ini>
[tplplugins] 
defaultJformsBuilder = myformbuilder
</code>

To achieve a fine-grained control, you can even choose a generator in @@{form}@@ ou @@{formfull}@@ (as fourth argument) :

<code html>
  {formfull $form, 'mymodule~default:save', array(), 'htmllight'}
</code>

Those plugins support a fifth parameter which is an array of options passed to the generator (//errorDecorator// and //method// for 'html' and htmllight').  

Note: You can of course create a new generator as inheriting from an existing one. That way, you can customize only some of the output or set an option directly in its constructor. ...


More about generators :

   * [[display/html-generator|"html" generator]]
   * [[display/htmllight-generator|"htmllight" generator]]




===== Mixing jForms and AJAX response =====

see [[/responseajax|ajax response documentation]].