Quick links: Content - sections - sub sections
EN FR

The format described is supported since Jelix v1.0. Preceding versions such as betas may not support some missing tags or attributes.

Main structure

jForms file format is an XML document with <form> tag as root.


<?xml version="1.0" encoding="utf-8"?>
<form xmlns="http://jelix.org/ns/forms/1.0">

</form>

Under root tag, you'll declare tags referencing all of your form controls (also know as form fields). Controls parsing, checking and display will follow the order of appearance of tags in this document.

**Note: namespace of this format is http://jelix.org/ns/forms/1.0**

Common control properties

Identifier

Each form control must have an identifier (= a name). You'll use ref attribute to set it. This Id will also correspond to a form variable whose value will reflect the user input. You'll likely use that variable in your submit action.

Example:


  <input ref="name">
  </input>

Note : In Jelix, there are methods to ease the use of DAO with forms, for automatoc form-filling or data-saving. For this purpose, it is a good habit to use the same Id for DAO properties and associated forms controls.

Label

Most of form control must have a label declared through <label> element:


  <input ref="name">
    <label>Your name</label>
  </input>

You have the option of using a locale attribute instead of an hard-coded string :


  <input ref="name">
    <label locale="mymodule~forms.input.name"/>
  </input>

Messages

You can declare an optional help message using an <help> tag: it will be displayed beside your control. Either write your message text in the tag content or define locale attribute.


  <input ref="birthdate" type="date">
    <label locale="mymodule~forms.input.birthdate"/>
    <help>Input your birthdate respecting this pattern yyyy-mm-dd</help>
  </input>

or

  <input ref="birthdate" type="date">
    <label locale="mymodule~forms.input.birthdate"/>
    <help locale="mymodule~forms.input.birthdate.help"/>
  </input>

In your HTML forms a question mark will be displayed at the right of the field and a click on it will show your help message.

You could also declare an hint message which will be displayed as a tooltip on mouse hovering. This message is declared with an <hint> tag. See <help> tag for its content.

Error Messages

When user input is invalid on a field or just missing on a required field, Jelix displays pre-defined error messages. You can redefine those pre-defined messages with an <alert> tag. This tag must have a type attribute telling if it is an invalid message or a required message. As for helper messages, you can use either a locale or an hard-coded message.


  <input ref="birthdate" type="date">
    <label locale="mymodule~forms.input.birthdate"/>
    <alert type="required" locale="mymodule~forms.input.birthdate.error.required"/>
    <alert type="invalid ">Your input does not match a date pattern like yyyy-mm-dd</alert>
  </input>

Required controls

If some controls are required in your form just add them a required attribute with value true.

<submit>, <checkbox> and <output> controls do not support it.

Readonly controls

On rare occasions, it can be helpfull to make a control readonly. Set a readonly attribute with value true on your control.

<submit> and <output> controls do not support it.

Input fields

Text input

To declare an input field, use <input> tag. Set its ref attribute, and optionally <label>, <hint>, <alert>, <help> tags as well as readonly and required attributes. It supports also the following attributes: type, defaultvalue, size, minlength and maxlength.

defaultvalue indicates a default value displayed when form is empty. You can use "now" if your input represents a date. default value will be the current date.

size defines field length in terms of number of chars.

maxlength and minlength declare a constraint on the input value: input value length shall be over minlength and under maxlength. Those attributes are only valid with type="string".

type defines which data format a user input shall match. On submit, a client-side javascript checking will be done, and also a server-side checking (case of javascript deactivated) with a call of check() method on the form object.

Below a list of type values and theirs constraints :

  • "string": string. Any char allowed. (default type).
  • "boolean": only two values accepted, "true" or "false".
  • "decimal": a number with or without comma.
  • "integer": an integer.
  • "hexadecimal": an hexadecimal number (digits 0-9 and letters a-f).
  • "datetime", "date", "time": respectively a date and time, a date, a time. And their patterns are "yyyy-mm-dd hh:mm:ss", "yyyy-mm-dd", "hh:mm:ss".
  • "localedatetime", "localedate", "localetime": respectively a date and time, a date, a time, but in the locale user format. For example, for a french site, date should match "dd/mm/yyyy", and for an english site "mm/dd/yyyy".
  • "url": user input must be a valid URL.
  • "email": user input must be a valid email.
  • "ipv4": an IP v4 address.
  • "ipv6": an IP v6 address.

A simple example :


  <input ref="email" type="email">
     <label locale="mymodule~myform.email.label" />
     <hint>Email shoud be valid</hint>
  </input>

Multiline input

To declare a multiline input field, use <textarea> tag. Set its ref attribute, a <label> element, and optionally <hint>, <alert>, <help> tags as well as readonly and required attributes. it supports also the following attributes: defaultvalue, rows, cols, minlength et maxlength.

defaultvalue indicates a default value displayed when form is empty. rows and cols defines respectively field width and height (as HTML textarea).

An example :


  <textarea ref="message">
     <label locale="mymodule~myform.message.label" />
     <hint>Write your message</hint>
  </textarea>

maxlength and minlength declare a constraint on the input value: input value length shall be over minlength and under maxlength.

Password

If you want your user to input a password or any values that should be kept hidden on input, use <secret> tag. Set its ref attribute, and optionally <label>, <hint>, <alert>, <help> tags as well as readonly and required attributes.


  <secret ref="password">
     <label>Your password</label>
     <hint>Write the password you received on registering</hint>
  </secret>

You can use size attribute to indicate field size.

It is often usefull to ask your user to confirm its password entry. jForms does it automatically. You just have to add <confirm> tag as child of <secret>, and the HTML form generated will have two input fields. <confirm> tag must contain either its hard-coded label, or a locale attribute pointing to it.


  <secret ref="newpassword">
     <label>New Password</label>
     <hint>Write a new password</hint>
     <confirm>Confirm your new password</confirm>
  </secret>

Your html form will likely be:


   <label for="newpassword">New password</label>
        <input type="password" id="newpassword" name="newpassword" title="Write a new password"/>

   <label for="newpassword_confirm">Confirm your new password</label>
        <input type="password" id="newpassword_confirm" name="newpassword_confirm"/>

Checkbox (one and only)

To display a checkbox, declare a <checkbox> tag. Set its ref attribute, its <label> element, and optionally <hint>, <alert>, <help> tags as well as readonly and required attributes.


  <checkbox ref="remember">
     <label>Remember me</label>
     <help>Check this box to log in automatically next time</help>
  </checkbox>

Default values for a checkbox are 0 if it was checked, or 1 on the contrary.

You can override those default values. Just add valueoncheck and valueonuncheck attributes (those equal respectively to 1 and 0 by default, if you follow). Example :


  <checkbox ref="remember" valueoncheck="Y" valueonuncheck="N">
     <label>Remember me</label>
     <help>Check this box to log in automatically next time</help>
  </checkbox>

Keep in mind that when you'll display a pre-filled form, your checkbox will be checked or not, on a comparison between its initial value and valueoncheck or valueonuncheck.

Checkboxes list

You could have to display a series of checkboxes to reflect multiple choices. For example, you want your user to select a list of articles to search or buy. Use <checkboxes> tag (with a terminal S).

Set its ref attribute, its <label> element, and optionally <hint>, <alert>, <help> tags as well as readonly and required attributes.

You'll then declare its values and their associated labels. Check further section on datasource also but here is an example:


   <checkboxes ref="food">
      <label>Check the food items you want to buy:</label>
      <item value="54">sugar</item>
      <item value="27">steack</item>
      <item value="32">orange juice</item>
  </checkboxes>

With the control above, jForms will display a list of three checkboxes, labelled "sugar", "steack" and "orange juice". On submit, the value for "food" form variable will be a PHP array. This array will contain the values of all items checked. If user has checked "steack", you'll receive array(27). If "sugar" is also checked, you'll receive array(54, 27).

(See Using the form in a controller)

Radio buttons

Radio buttons are never standalone, there must be at mininum 2 of them. To declare a set of radio buttons, use the tag <radiobuttons>.

Set its ref attribute, a <label> element, and optionally <hint>, <alert>, <help> tags as well as readonly and required attributes. As for other list controls, you must delcare a list of possible values and associated labels. Check also further section on datasource.

Example :


   <radiobuttons ref="color">
      <label>What is your preferred color:</label>
      <item value="r">Red</item>
      <item value="b">Blue</item>
      <item value="g">Green</item>
      <item value="y">Yellow</item>
  </radiobuttons>

jForms will display a set of 4 radio buttons and the selected value will be stored in a "color" form variable.

To display a menu list use the tag <menulist> (<select size="1"> in HTML). A menu list allows only one choice. Set its ref attribute, a<label> element, and optionally <hint>, <alert>, <help> tags as well as readonly and required attributes. As for other list controls, you must declare a list of possible values and associated labels. Check also further section on datasource.

Example :


   <menulist ref="country">
      <label>your country is:</label>
      <item value="FR">France</item>
      <item value="US">USA</item>
      <item value="GB">Great Britain</item>
      <item value="ES">Spain</item>
  </menulist>

The selected value will be stored in a "country" form variable.

List box

Listbox (equivalent to <select> in HTML), should be declared with tag <listbox>. Set its ref attribute, a <label> element, and optionally <hint>, <alert>, <help> tags as well as readonly and required attributes. As for other list controls, you must declare a list of possible values and associated labels. Check also further section on datasource.


   <listbox ref="section">
      <label>Vote for the best doc. section:</label>
      <item value="1">Daos</item>
      <item value="2">Forms</item>
      <item value="3">Urls</item>
  </listbox>

You can also add a size attribute. It sets the number of list box items to display (hence the list box height). its default value is 4.

Listbox is one-choice only in its default behaviour. However you can set multiple="true" attribute to enable muti-items selection (in an HTML form, user has to hold Ctrl-key and click to select more than one element). In that situation, "section" form variable of the example above will be assigned to a PHP array of selected values instead of a single one.

File Upload

If you want user to upload a file to your server, use the tag <upload> (equivalent to <input type="file"> in HTML). Set its ref attribute, a <label> element, and optionally <hint>, <alert>, <help> tags as well as readonly and required attributes.

This control supports two specific attributes to control file type and size. Respectively mimetype (its value has to be one or more mimetype) and maxsize (size in octets).


  <upload ref="photo" mimetype="image/jpeg;image/png" maxsize="20000">
    <label>Your photo</label>
  </upload>

Upon receiving file, jForms will check its type and its size. You'll see later that you can choose where to save it. "photo" form variable will have the filename as value.

Submit button

In a form, you'll most of time need one or more submit buttons to validate user inputs and send form data to your server. Submit buttons are declared with tag <submit>. Set its ref attribute, a <label> element, and optionally <hint>, <alert>, <help> tags (but not readonly nor required attributes).


  <submit ref="submit">
    <label>Ok</label>
  </submit>

Its form variable will not be useful except if you have more than one submit, like the common case of "preview" and "save" action. To define more than one sub mit, just use item tags as in other multi-values controls. Check also further section on datasource.

Example:


  <submit ref="action">
    <label>Choose your action</label>
    <item value="preview">Preview</item>
    <item value="save">Save</item>
  </submit>

"action" form variable will equal "preview" or "save" on submit. your HTML form will display 2 buttons labelled respectively "Preview" and "Save".

Reset button

To display a reset button, use <reset> tag.


  <reset ref="init">
    <label>Reset</label>
  </reset>

Output values

<output> tag allows simply to display a value. It will be readonly. This could serve when you want to edit a record without allowing every field to be editable. Set its ref attribute, a <label> element, and optionally <hint>, <alert>, <help> tags (but not readonly nor required attributes).


  <output ref="category">
    <label>Category</label>
  </output>

Data sources

menulist, listbox and radiobuttons and checkboxes controls each define more than one choice. you must indicate jForms how to collect values and labels of those choices.

jForms offers three ways to declare them:

  1. choices can be hard-coded in XML file (static data)
  2. choices can be retrieved through DAO.
  3. choices can be retrieved through a class.

Static choice

Choices are set through <item> tag. Choice value is declared with value attribute. Choice label is simply the content of <item> but you could either use a locale by setting locale attribute. When label is empty, jForms take choice value as label.


   <checkboxes ref="objects">
      <label>You have </label>
      <item value="house">A house</item>
      <item value="car" locale="mymodule~myform.item.car.label" />
      <item value="boat"/>
  </checkboxes>

Dynamic data through DAO

List choices can be filled through a DAO. To achieve this, you have to set 3 attributes:

  1. dao, its value must be a dao selector
  2. daomethod, its value select a dao method retrieving choices
  3. daolabelproperty, its value select a property to be used as label choices

Each value choice will be the primary key property of the selected DAO. However, you can use another DAO property by setting daovalueproperty attribute.

Example:


  <menulist ref="conf" dao="testapp~config" 
                       daomethod="findAll"
                       daolabelproperty="cvalue"
                       daovalueproperty="ckey">
      <label>Select which element to edit</label>
  </menulist>

Dynamic data through a class

If a DAO doesn't suit your needs, you can use a class. This class should inherit from the jIFormDatasource interface and stored in classes/ folder of a module. You'll declare this class with dsclass attribute.

Class example:


class listDatas implements jIFormsDatasource
{
  protected $formId = 0;

  protected $datas = array();

  function __construct($id)
  {
    $this->formId = $id;
    $this->datas = array(0 => 'test',
                         1 => 'test 2',
                         2 => 'Id = '. $id);
  }

  public function getDatas()
  {
    return ($this->datas);
  }

  public function getLabel($key)
  {
    if(isset($this->datas[$key]))
      return $this->datas[$key];
    else
      return null;
  }

}

in jForms XML file :


  <menulist ref="icone" dsclass="monmodule~listDatas">
        <label locale="elements.crud.label.icone" />
  </menulist>

Other data source

If neither DAO, class or static data are of use, see "Defining choices on a multiple choice control" in jForms usage.

If you do so, don't declare <item> tag nor dao*/dsclass attributes.

Preselecting values

On Controls displaying list of choices, you sometime want to select default values. Three ways to do so:

  1. add an attribute selected=true on selected item tags. Only listbox and checkboxes support more than one selected item.
  2. add an attribute selectedvalue on your control tag, and set it to the value of choice. This way, you can only declare one default value.
  3. add a <selectedvalues> tag and its child <value>. This way is preferred on checkboxes and listbox control when using a dao data source.

Examples :


  <radiobuttons ref="home">
      <label>You live in</label>
      <item value="pa" selected="true">Paris</item>
      <item value="sf">San Francisco</item>
      <item value="ld">London</item>
      <item value="be">Berlin</item>
      <item value="st">Stockholm</item>
      <item value="ma">Madrid</item>
  </radiobuttons>

  <menulist ref="conf" selectedvalue="foo.bar"
                       dao="testapp~config" 
                       daomethod="findAll"
                       daolabelproperty="cvalue"
                       daovalueproperty="ckey">
      <label>Select which element to edit</label>
  </menulist>

  <listbox ref="objects" required="true" multiple="true">
      <label>You have </label>
      <item value="house">A house</item>
      <item value="car">A car</item>
      <item value="boat">A boat</item>
      <item value="plate">A plate</item>
      <selectedvalues>
           <value>house</value>
           <value>boat</value>
      </selectedvalues>
  </listbox>