Widgets

The Axelor Development Kit web application provides some built-in widgets. These widgets are used to represent data in form view.

All the widgets represents a domain object field and can override all the properties (min, max, required, readonly etc.) of underlying fields.

Following widgets have been implemented:

String

The string widget represents the string data type. It’s used for simple string fields.

<field name="string"/>

Email

This widget can be used for string fields to enter email address.

<field name="email" widget="email" />

The input value will be validated to ensure user provides valid email id.

Url

This widget can be used for string fields to enter url value.

<field name="website" widget="url" />

Phone

This widget can be used for string fields to enter phone values.

<field name="phone" widget="phone" />

Password

This widget can be used for string fields to enter password values.

<field name="password" widget="password" />

Number

The number widget is used for integer and decimal data fields.

Number widget has specials attributes :

  • min : lowest bound of the value

  • max : upper bound of the value

  • x-scale : scale of the decimal value (total number of digits in decimal part).

  • x-precision : precision of the decimal value (total number of digits).

<field name="integer" widget="Integer"/>
<field name="decimal" widget="Decimal" x-scale="2" x-precision="18"/>

DateTime

The datetime widgets is used for date and datetime fields.

<field name="date" widget="date" />
<field name="time" widget="time" />
<field name="dateTime" widget="date-time" />

Two more widgets relative-time and duration can be used with DateTime and Integer fields respectively.

  • relative-time - shows relative time from now

  • duration - shows numeric value in seconds as time duration

The duration widget can have following extra attributes:

  • x-big=true - if expected duration is more than 100 hours

  • x-seconds=true - show seconds

Boolean

The boolean widget is used for boolean data fields.

<field name="confirmed" widget="boolean" /> <!-- title on top -->
<field name="confirmed" widget="boolean" css="inline-checkbox" /> <!-- title on right -->
if field type is boolean, no need to specify widget="boolean"

Additionally, following variants of boolean widgets are provides:

  • toggle - a two state toggle button (true is down, up otherwise)

  • boolean-select - a combo box with yes/no selection

  • boolean-radio - a group of two radio boxes with yes/no text

  • boolean-switch - a switch like sliding widget for boolean fields

The yes/no text can be configured with x-true-text and x-false-text attributes:

<field name="some" widget="boolean-select" x-true-text="Yes" x-false-text="No" />
<field name="some" widget="boolean-radio" x-true-text="On" x-false-text="Off" />
<field name="some" widget="boolean-switch" />

Text

The text widget is used for multiline or large string data fields.

The height attribute define the number of rows takes by the widget.

<field name="notes" widget="Text"/>

Help

This widget is used to show static help information in form view.

<help css="alert-info">
<![CDATA[
Some help text goes here....
]]>
</help>

Static

This widget is similar to help widget but doesn’t apply any specific style

<static>
<![CDATA[
Some static text goes here....
]]>
</static>

ManyToOne

The widget is used for many-to-one fields.

<field name="contact" /> <!-- assuming it's m2o field -->
<field name="some" x-type="many-to-one"
  x-target="com.axelor.contact.db.Contact"
  x-target-name="fullName" /> <!-- dummy m2o field -->

The viewer and editor for this field refers to the linked record.

<field name="contact">
  <viewer>
  <![CDATA[
  <strong>{{fullName}}</strong>
  ]]>
  </viewer>
  <editor>
    <field name="firstName" />
    <field name="lastName" />
  </editor>
</field>

OneToOne

The widget is used for one-to-one fields. This is same many-to-one widget.

OneToMany

The widget is used for one-to-many fields.

<panel-related field="orderItems" /> <!-- assuming it's o2m field -->
<panel-related field="some" x-type="one-to-many"
  x-target="com.axelor.sale.db.OrderItem" /> <!-- dummy o2m field -->

The default widget uses a grid widget to show linked records. You can specify field names to show in the list:

<panel-related field="orderItems">
  <field name="product" />
  <field name="quantity" />
  <field name="price" />
</panel-related>

You can also display the values as repeated viewer or editor using normal field widget:

<field name="addresses" colSpan="12" css="address-list">
  <viewer><![CDATA[
  <address>
  {{record.street}} {{record.area}}<br>
  {{record.city}}, {{record.state}} - {{record.zip}}<br>
  {{record.country.name}}
  </address>
  ]]></viewer>
  <editor x-show-titles="false">
    <field name="street" colSpan="12"/>
    <field name="area" colSpan="12"/>
    <field name="city" colSpan="4"/>
    <field name="state" colSpan="4"/>
    <field name="zip" colSpan="4"/>
    <field name="country" colSpan="12" />
  </editor>
</field>

When using viewer with one-to-many fields, values should be referenced with record.<fieldName>.

ManyToMany

The widget is used for many-to-many fields. This is same widget as one-to-many but one additional icon to select existing records.

Binary

The binary widget is file upload widget used with binary fields.

<field name="content" widget="binary" />

Image

The image widget is used with binary fields that stores image data or many-to-one fields referencing com.axelor.meta.db.MetaFile records.

<field name="picture" widget="image" />
<field name="metaFile" widget="image" />

Button

The button widget is used to show a clickable button on a form.

Button widget has specials attributes :

  • onClick : action to execute on click event

  • prompt : confirmation message before performing client action

  • link : If specified then the button is rendered as a link. Use empty value if you only need a link effect and perform actual action with onClick.

  • icon : button icon (an image or font-awesome icon)

  • iconHover : button icon on mouse hover (an image or font-awesome icon)

<button name="customBtn" title="Click Me!" onClick="actions"
  prompt="This is a confirmation message."
  icon="fa-check-square-o" />

The NavSelect widget is a breadcrumb like widget and can be used with selection fields.

RadioSelect

The RadioSelect widget can be used with selection fields. The field is rendered as radio selection list.

<field name="language" selection="language-selection" widget="RadioSelect" />

The radio list is rendered horizontally but can be change to vertical with x-direction="vertical" attribute.

CheckboxSelect

The CheckboxSelect is same as RadioSelect but uses checkbox list.

ImageSelect

The ImageSelect widget can be used with a selection field where selection values are either image urls or font icons.

MultiSelect

The MultiSelect widget can be used with a selection field to select multile values.

RefSelect

Sometimes we need to reference a record from different types. For example, in an Email, we may have to give reference to an Invoice or SaleOrder or even a Contact. The standard ManyToOne field can’t work here as it can only refer single type.

The RefSelect widget can be used in such cases. In order to use RefSelect, we require two fields in target object and a selection of types.

<entity ...>
  ...
  <string name="reference" /> (1)
  <integer name="referenceId" /> (2)
</entity>
1 - will store the reference object type name
2 - will store the reference record id

and a selection of types:

<selection name="my.reference.select">
  <option value="com.axelor.sale.db.Order">SaleOrder</option> (1)
  <option value="com.axelor.contact.db.Contact"
    data-domain="self.email LIKE '%gmail%'"
    data-grid="my-custom-grid-view">Contact</option> (2)
</selection>
1 - define selection option with fully qualified type name as value
2 - you can define extra attributes using data- prefix

and we can use the reference widget like this:

<form ...>
  ...
  <field name="reference" selection="my.reference.select" widget="RefSelect" />
</form>
Use data-grid or data-form attributes to specify different views

CodeEditor

The CodeEditor widget is a special widget for string data fields to use a code editor to input the source code text.

CodeEditor widget has two specials attributes :

  • x-code-syntax : syntax highlighting

  • x-code-theme : theme to style the editor.If not define use the default theme

<field name="script" widget="code-editor" x-code-syntax="xml"/>

HTML

The html editor widget is a special widget for string data fields to provide html text.

Html widget has a special attribute x-lite to use a compact and little version of the widget.

<field name="note" widget="html"/>

<!-- or use compact version of the widget -->
<field name="note" widget="html" x-lite="true"/>

Extra Attributes

In addition to the common properties, widgets supports following extra properties depending on the widget/type.

Attribute Description

x-bind

angular.js expression to bind to the field value

x-related

specify related field for ref-select widget

x-create

the names of required fields to be used for quick record creation from select widget

x-icon

specify an icon

x-icon-hover

specify an icon for hover state

x-icon-active

specify an icon for active state (used with toggle widget)

x-exclusive

whether the boolean field used inside the o2m repeat editor should be exclusive

x-show-icons

the name of icons to show on editor

x-can-copy

whether to allow copy of o2m/m2m field items

x-direction

layout direction (horizontal, vertical) of some widgets (e.g. radio-select)

x-code-syntax

syntax highlighting for the code editor widget

x-code-theme

color scheme for the code editor

x-lite

whether to use compact version of the widget (used with html widget)

x-labels

whether to show label in image-select widget

x-order

specify the order of suggest box list

x-limit

specify the maximum number of items in suggest box list

x-precision

precision of the decimal value (total number of digits)

x-scale

scale of the decimal value (total number of digits in decimal part)

x-true-text

the display value for "true" state of a boolean widget

x-false-text

specify the display value for "false" state of a boolean widget

Expressions

The form view widget’s states can be set using angular.js boolean expressions from the xml views.

These are:

  • showIf - show the widget

  • hideIf - hide the widget

  • requiredIf - mark the widget as required

  • readonlyIf - mark the widget as readonly

  • validIf - validate the field

The boolean expressions are evaluated against current form values. Following special variables can be used:

  • $moment(d) - a helper to convert date to moment.js object

  • $number(d) - a helper to convert text to number

  • $contains(list, item) - a helper to check whether list contains the item

  • $readonly() - whether the widget is readonly

  • $required() - whether the widget is required

  • $valid([name]) - whether the widget is valid

  • $invalid([name]) - whether the widget is invalid

  • $get(path) - get the value with dotted path

  • $popup() - whether the form is a popup

  • $context - current context

Examples :

<field name="createDate" readonlyIf="confirmed"/>

<field name="amount" validIf="$number(amount) &gt;= 100" />

<field name="password" validIf="password.length &gt; 5" />
<field name="confirmPassword" validIf="password === confirmPassword" />