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.

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>

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.

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>

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.

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.

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>

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.

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

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.

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

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.

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.

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

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

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

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

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>

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>

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

Class example:

class listDatas implements jIFormDatasource
{
  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>

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.

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>