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 automatic form-filling or data-saving. For this purpose, it is a good practice to use the same Id for DAO properties and associated form controls.

Most of form controls 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 hardcoded 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>, <group>, <choice>, <hidden> and <output> controls do not support it.

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

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

You can modify this property with the PHP object of the form.

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.
• "html": it can contains html element. The HTML content will be filtered on the server side (javascript code is removed, some attributes and specific elements are removed etc.), to avoid security problems like CSS, XSS etc..

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: type, 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.

type attribute can contains only one value for the moment : "html". Like the <input type="html"> element, the content will be filtered to remove some attributes which could contain javascript, and some specific elements (<script> for example...). If you want wywsiwyg html editing see below.

To use an HTML editor in your form, you should use the <htmleditor> element.

  <htmleditor ref="description">
	<label>Describe the product</label>
  </htmleditor>

The default html builder of jforms uses Wymeditor. You can specify an other html editor by setting the engine attribute. You can also indicate a configuration file with the config attribute, and indicates a skin with the skin attribute.

To know more about configuring a wysiwyg html editor, see the dedicated section on htmleditor.

The element <date> and <datetime> facilitate the entry of a date as opposed to a simple <input>.

  <date ref="birthday">
	<label>Your birthday</label>
  </date>

The attribute ref is required, and you can use the attributes defaultvalue, readonly, required, and also the elements <label>, <hint>, <alert>, and <help>.

You can use some specific attributes : mindate, maxdate and datepicker. To know more about them, see the dedicated page.

About mindate and maxdate attributes, you can use an absolute date in the classical database format, like '2009-01-01', or a string which contains a format supported by the sprintf php function.

For instance, if we want a date of birth for persons aged 18 to 70 years old:

  <date ref="birth" mindate="-70 years" maxdate="-18 years">
	<label>date of birth</label>
  </date>

Other example, where we want a date between today and 2 month and one day old.

  <date ref="begin" mindate="now" maxdate="+2 months 1 day">
	<label>Begin of the event</label>
  </date>

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

By default, if there isn't an attribute required="true", the user doesn't need to make a choice. So you have automatically a first empty choice in the list. If you want to indicate a label for this empty choice, you could use <emptyitem>.

   <menulist ref="ville">
      <label>votre ville :</label>
      
   <menulist ref="country">
      <label>your country is:</label>
      <emptyitem>-- choose a country --</emptyitem>
      <item value="FR">France</item>
      <item value="US">USA</item>
      <item value="GB">Great Britain</item>
      <item value="ES">Spain</item>
  </menulist>

Of course, you can use a locale:

      <emptyitem locale="module~foo.bar"/>

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

Warning : with IE, the mimetype of jpg and jpeg files is image/pjpeg. Be sure to set mimetype="image/pjpeg" with image/jpeg if you want allow this file format.

  <upload ref="photo" mimetype="image/jpeg;image/pjpeg;image/png" 
    <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.

It can be useful to group some control, for presentation reasons or to facilitate the management of this controls with the jForms API. To do so, put all controls you want into a <group> element. This element should have a ref attribute, but can have also a readonly attribute to turn all child controls into readonly mode. Most of actions on the group control with the PHP API change properties of child controls.

  <group ref="a_group">
     <label>identity</label>
     <input ref="name"><label>Name</label></input>
     <input ref="lastname"><label>Last name</label></input>
  </group>

Some times, we want to have a choice between many options, and for each options, to specify additional informations. jForms provides a powerful control, <choice>. This element should contain some <item> elements, and this elements contains a <label> element, but also zero or more controls.

  <choice ref="status">
     <label>Bug status</label>
     <item value="new"> <label>New</label> </item>
     <item value="res"> 
         <label>Resolved</label>
         <menulist ref="resolution">
            <label>How</label>
            <item value="0">Fixed</item>
            <item value="1">Invalid</item>
            <item value="2">Won't fixed</item>
         </menulist>
     </item>
     <item value="dup">
         <label>duplicate</label>
         <input ref="dup_bug"><label>Bug number</label></input>
     </item>
   </choice>

When a user selects one of this item (represented by radio buttons in HTML), controls of others items are deactivated.

Each <item> element should have a value attribute.

The <choice> element accept <help>, <hint>, <alert>, as well as readonly and selectedvalue attributes. This last attribute can contain a value of one of the items. You can also put a selected="true" attribute on an <item> element to select it.

In some contexts, it is necessary to verify that the form is filled by a human, not by a spammer robot.

JForms provides the element <captcha> to include a field which will do this verification. For the moment, it is not an image like in some websites, but a simple text field in which the user should give a response to a simple question asked by jForms.

The use of the captcha element is very simple, an has no specific attributes.

 <captcha ref="antispam">
    <label>Vérification anti-spam</label>
 </captcha>

Questions and answers are stored in a locale file, in the module jelix. For example, for english questions, this is lib/jelix/core-modules/jelix/locales/en_EN/captcha.UTF-8.properties. This file contains a first locale, number, which contains the number of question. And it is followed by locales which contain the questions and the answers. You can redefine this file to add or modify questions/answers.

See the chapter on the redefinition of files.

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

If you want to include hidden fields into your form (which is equal to <input type="hidden"> in HTML), you should use the <hidden> element. It must have a ref attribute, and you can also use the defaultvalue attribute.

  <hidden ref="product_id" />

a choice is defined by an <item> tag. its value is declared with the value attribute. its label is simply the content of <item>. Alternatively you could use a locale by setting locale attribute. When label is empty, jForms takes the 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 use a <datasource> element with at least 3 attributes:

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

You can use also a profile attribute to indicate the jDb profile to use.

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

Example:

  <menulist ref="conf">
      <label>Select which element to edit</label>
      <datasource dao="testapp~config" method="findAll"
                  labelproperty="cvalue" valueproperty="ckey"/>
  </menulist>

Indicating a DAO method with arguments ¶

   <datasource dao="testapp~config" method="findAll" criteria="admin"
              labelproperty="cvalue" valueproperty="ckey"/>

  <menulist ref="catlist">
     ...
  </menulist>
 
  <menulist ref="conf">
      ...
      <datasource dao="testapp~config" method="findByCat" criteriafrom="catlist"
                  labelproperty="cvalue" valueproperty="ckey"/>
  </menulist>

Multiple values in attributes ¶

  <input ref="date">
     ...
  </input>
  <menulist ref="catlist">
     ...
  </menulist>
 
  <menulist ref="conf">
      <datasource dao="testapp~config" method="findByCatAndDate" criteriafrom="catlist,date"
                  labelproperty="cname,cvalue"  labelseparator=" = " valueproperty="ckey"/>
  </menulist>