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:

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

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

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

   </fieldset>

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

  {/form}

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.

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' and 'firstname' controls only:

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

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

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

   </fieldset>

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

  {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}

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.

  {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}

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

To know more about how to customize the display of controls in HTML, see the dedicated page.

Beware that if a password control defines a confirm field (<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 and a suffix _confirm.

See example below:

  {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}

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' :

   <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>

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

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:

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

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

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

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