Widgets

The Axelor Open Platform 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

The phone widget formats phone numbers. It renders the field as a phone number link in readonly mode, and as a phone number input with a country/region selector in edit mode.

The default country is locale aware and is based on user language. If user language doesn’t contain country code, a matching country is searched in user’s browser locales. In case of no country match in browser locales, there is some fallback behavior. For example, if user language is fr, and browser locales are fr, fr-CA, en, en-US, then country would be ca. if user language is ja, country would fallback to jp.

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

The following attributes are supported:

  • x-placeholder-number-type - country-dependent number type to use for the placeholder: FIXED_LINE (default) or MOBILE

  • x-initial-country - initial country selection by specifying its two-letter country code (defaults to user/browser locale)

  • x-preferred-countries - countries to appear at the top of the list (comma-separated list of two-letter country codes) (defaults to user/browser locales)

  • x-only-countries - in the country dropdown, only display the specified countries (comma-separated list of two-letter country codes)

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). It accepts an integer for a fix scale, or a field name for a dynamic evaluation.

  • 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"/>
<field name="decimal" widget="Decimal" x-scale="currency.decimalPlaces" x-precision="18"/>

Rating

The rating widget is used for integer/long/decimal data fields. It provides ability to collect measurable opinions/experiences/feedbacks/…​

Rating widget supports following attributes :

  • max: the number of icon to display. Default to 5.

  • x-rating-icon: Bootstrap icon to use. It also supports comma-separated list of icons. Default to star.

  • x-rating-color: color to use when checked. It also supports comma-separated list of colors.

  • x-rating-fill: whether the icon should use fill style when checked. Defaults to true.

  • x-rating-highlight-selected: whether to highlight only the selected icon. Defaults to false.

<field name="myRating" type="Integer" widget="Rating"/>
<field name="myRating" type="Integer" widget="Rating" x-rating-icon="heart"/>
<field name="myRating" type="Integer" widget="Rating" max="8" x-rating-icon="airplane"/>
<field name="myRating" type="Integer" widget="Rating" x-rating-icon="1-square,2-square,3-square,4-square,5-square"/>
<field name="myRating" type="Integer" widget="Rating" x-rating-icon="emoji-angry,emoji-frown,emoji-neutral,emoji-smile,emoji-laughing" x-rating-color="#d32f2f,#d32f2f,#ed6c02,#2e7d32,#2e7d32" x-rating-highlight-selected="true" x-rating-fill="false"/>

By default, star icon will be colored in yellow when checked and heart in pink. The record value of the first icon is 1, the last is the one defined in max attribute. By clicking on the last checked icon, it reset the value to 0.

Widget support partial rating on decimal fields but only for display purpose (for example, an average).

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 widget is used for boolean data fields.

<field name="confirmed" widget="boolean" />

BooleanSelect

The widget is used for boolean data fields. The field is rendered as a combo box with yes/no selection.

<field name="confirmed" widget="boolean-select" />

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

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

BooleanRadio

The widget is used for boolean data fields. The field is rendered as a group of two radio boxes with yes/no text.

<field name="confirmed" widget="boolean-radio" />

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

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

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

BooleanSwitch

The widget is used for boolean data fields. The field is rendered as a switching selector.

<field name="confirmed" widget="boolean-switch" />

Toggle

The widget is used for boolean data fields. The field is rendered as a two state toggle button.

<field name="confirmed" widget="toggle" />

By default, the toggle button icon is a square for unchecked state and square-fill for checked state. It can be configured with following attributes :

  • x-icon - specify an icon for unchecked state

  • x-icon-hover - specify an icon for hover state

  • x-icon-active - specify an icon for checked state

<field name="some" type="Boolean" widget="Toggle" x-icon="star" x-icon-active="star-fill"/>

InlineCheckbox

The widget is used for boolean data fields. The field is rendered as default boolean widget but with the title on right.

<field name="confirmed" widget="inline-checkbox" />

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.

MasterDetail

This widget is supported on one-to-many and many-to-many fields. It allows to show a form view below the grid view for the currently selected row.

Example:

<panel-related
  title="Items (MasterDetail)"
  readonlyIf="confirmed"
  field="items"
  form-view="order-line-form"
  grid-view="order-line-grid"
  onChange="com.axelor.sale.web.SaleOrderController:computeItems"
  widget="master-detail"
  summary-view="order-line-nested"
/>

Attribute:

  • summary-view - (optional) used to define the form view shown below the grid view. If not specified, the view specified by form-view attribute is used instead.

If grid is editable, summary form view stays readonly.

Expandable

This widget is supported on one-to-many fields and top-level grids. It allows to show an expandable form view below each row.

Example:

<panel-related
  title="Items (Expandable)"
  readonlyIf="confirmed"
  field="items"
  form-view="order-line-form"
  grid-view="order-line-grid"
  editable="true"
  onChange="com.axelor.sale.web.SaleOrderController:computeItems"
  widget="expandable"
  summary-view="order-line-nested"
  x-expand-all="items"
/>

Attributes:

  • summary-view - (optional) used to define the expandable form view. If not specified, the view specified by form-view attribute is used instead.

  • x-expand-all - (optional) to enable expand all feature, you have to specify a comma-separated list of nested expandable collection fields, if any. Supported on form field only, not on top-level grid.

TreeGrid

This widget is supported on one-to-many fields. It allows to show a tree-like structure in a grid view.

Example:

<panel-related
  title="Items (Tree)"
  readonlyIf="confirmed"
  field="items"
  form-view="order-line-form"
  grid-view="order-line-grid"
  editable="true"
  onChange="com.axelor.sale.web.SaleOrderController:computeItems"
  widget="tree-grid"
  x-tree-field="items"
  x-tree-limit="2"
  x-tree-field-title="Add new item"
>
  <field name="product" onChange="action-order-line-change-product"/>
  <field name="price" width="200" />
  <field name="quantity" width="150" />
</panel-related>

Attributes:

  • x-tree-field - used to define the nested o2m field.

  • x-tree-limit - (optional) used to specify limit to support nested tree structure.

  • x-tree-field-title - (optional) by default, it uses main title for sub-items heading (title will only display when item contains no-sub items).

  • x-expand-all - (optional) it’s enabled by default with tree-grid, it uses x-tree-field value as x-expand-all value. To disable it, we can set it to "false"

Only onChange action on root collection is performed. Actions defined on sub-items are not supported.

Binary

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

Binary widget has specials attributes:

  • x-accept: Specify the file types the file input should accept. Can be a filename extension or a MIME type (see MDN doc)

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

This widget can be used with many-to-one fields referencing com.axelor.meta.db.MetaFile records. It allows single click download and upload.

BinaryLink widget has specials attributes:

  • x-accept: Specify the file types the file input should accept. Can be a filename extension or a MIME type (see MDN doc)

<field name="metaFile" widget="binary-link" />

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.

Image widget has specials attributes:

  • x-accept: Specify the file types the file input should accept. Can be a filename extension or a MIME type (see MDN doc)

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

Drawing

The drawing widget is used to freely draw on a pop-up canvas. It uses binary fields that stores image data or many-to-one fields referencing com.axelor.meta.db.MetaFile records.

Drawing widget supports following attributes :

  • x-stroke-width: The stroke width. Default to 0.5.

  • x-stroke-color: The stroke color. Can be any color name. Default to black.

  • x-drawing-height: The drawing height in px. Default to 200.

  • x-drawing-width: The drawing width in px. Default to 500.

<field name="signature" widget="drawing" />
<field name="signature" widget="drawing" x-stroke-width="2" x-stroke-color="red" />
<field name="signature" widget="drawing" x-stroke-width="1.5" x-stroke-color="aqua" x-drawing-height="800" x-drawing-width="700" />

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 an icon)

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

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

Progress

The Progress widget is used to show a progress bar.

Progress widget supports following attributes:

  • min: number value to specify minimum range for progress (default to 0)

  • max: number value to specify maximum range for progress (default to 100)

  • x-colors: color options to configure the bar color (default to r:24,y:49,b:74,g:100)

<field name="progress" title="Progress" widget="Progress"
  x-colors="r:24,y:49,b:74,g:100" />

Using the x-colors options, you can configure the bar color. Four colors can be configured. With r:24,y:49,b:74,g:100, following colors will be used depending on the percentage value :

  • red (r) - if percentage value in range [0, 24]

  • yellow (y) - if percentage value in range [25, 49]

  • blue (b) - if percentage value in range [50, 74]

  • green (g) - if percentage value in range [75, 100]

SelectProgress

Similar to the Progress widget, the SelectProgress widget can be used with a selection field to show selection in editable mode and for readonly mode it will display as progress widget.

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 changed to vertical with x-direction="vertical" attribute.

CheckboxSelect

The CheckboxSelect is same as RadioSelect but uses checkbox list.

InlineCheckbox

The InlineCheckbox is same as the default boolean widget but with title on right.

ImageSelect

The ImageSelect widget can be used with a selection field where selection icon is either image urls or font icons. If no icon is provided, it uses the value as icon.

x-labels attribute can be provided to show or not the selection text (default to true).

<field name="IconSelect" selection="my.social.network.selection" widget="ImageSelect" title="Social network"/>

<selection name="my.social.network.selection">
   <option value="1" icon="discord">Discord</option>
   <option value="2" icon="facebook">Facebook</option>
   <option value="3" icon="instagram">Instagram</option>
   <option value="4" icon="linkedin">Linkedin</option>
   <option value="5" icon="twitter-x">X</option>
</selection>

MultiSelect

The MultiSelect widget can be used with a selection field to select multiple values displayed as tags. Tag colors can be defined in the selection options via the color attribute.

It also supports x-selection-show-checkbox attribute to show checkbox on options.

SingleSelect

The SingleSelect widget can be used with a selection field to select a single value displayed as a tag. Tag colors can be defined in the selection options via the color attribute.

SuggestBox

The SuggestBox widget can be used with a many-to-one or one-to-one field to show suggestion list of matching records (similar to selection fields).

TagSelect

The TagSelect widget can be used with a many-to-many field to select multiple values displayed as tags. Use x-color-field to specify the tag color field that should use selection color.name.selection.

Available tag color values for MultiSelect, SingleSelect, and TagSelect:

<selection name="color.name.selection">
  <option value="red" color="red">Red</option>
  <option value="pink" color="pink">Pink</option>
  <option value="purple" color="purple">Purple</option>
  <option value="deeppurple" color="deeppurple">Deep Purple</option>
  <option value="indigo" color="indigo">Indigo</option>
  <option value="blue" color="blue">Blue</option>
  <option value="lightblue" color="lightblue">Light Blue</option>
  <option value="cyan" color="cyan">Cyan</option>
  <option value="teal" color="teal">Teal</option>
  <option value="green" color="green">Green</option>
  <option value="lightgreen" color="lightgreen">Light Green</option>
  <option value="lime" color="lime">Lime</option>
  <option value="yellow" color="yellow">Yellow</option>
  <option value="amber" color="amber">Amber</option>
  <option value="orange" color="orange">Orange</option>
  <option value="deeporange" color="deeporange">Deep Orange</option>
  <option value="brown" color="brown">Brown</option>
  <option value="grey" color="grey">Grey</option>
  <option value="bluegrey" color="bluegrey">Blue Grey</option>
  <option value="black" color="black">Black</option>
  <option value="white" color="white">White</option>
</selection>

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

In edit mode, this widget is the same as RefSelect. But in readonly mode, it only displays the link to the record (the type is not displayed).

Example usage from TeamTask:

<field name="relatedModel"
  title="Link"
  colSpan="12"
  widget="ref-link"
  selection="team.task.links"
  x-related="relatedId" />

In edit mode, this widget is used as string field input and we can enter interpolate string value. But in readonly mode, it displayed as Image widget with src link to that input value.

EvalRefSelect

This widget can be used to select reference value depending on dynamic target model value. The following attributes should be provided:

  • x-eval-target: expression to find target model

  • x-eval-target-name: expression to find target model name field

  • x-eval-value: expression to get/set reference value (id)

  • x-eval-title: expression to get/set reference title (name value)

Example usage from MetaJsonField:

<field name="contextFieldValue"
  widget="eval-ref-select"
  x-eval-target="contextFieldTarget"
  x-eval-target-name="contextFieldTargetName"
  x-eval-value="contextFieldValue"
  x-eval-title="contextFieldTitle" />

RefText

This widget can be used to select string field value of a record.

  • x-target: target model

  • x-target-name: target model name field

  • x-target-search: optional additional field value in selection list, displayed as x-target-name (x-target-search)

  • x-domain: optional domain filter on target model

Example where we select model name of meta model:

<field name="model" required="true" widget="ref-text"
  x-target="com.axelor.meta.db.MetaModel"
  x-target-name="fullName" />

Example where we select name of meta view, add module name in selection list, and use a domain filter:

<field name="view" widget="ref-text"
  x-target="com.axelor.meta.db.MetaView"
  x-target-name="name"
  x-target-search="module"
  x-domain="self.model = :model AND self.type IN ('form', 'grid')" />

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 defined, use the default theme.

<field name="script" widget="code-editor" x-code-syntax="xml"/>
As part of the new v7 front-end built on top of React, x-code-theme is no more supported. It will be re-added in a future version.

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

Markdown

The Markdown widget is implemented with TOAST UI Editor and supports CommonMark and GFM specifications.

<field name="comment" widget="markdown"/>
Attribute Description

x-lite

Enable lite toolbar (defaults to false)

x-preview-style

Markdown editor’s preview style: tab (default), vertical

x-initial-edit-type

Initial editor type: markdown (default), wysiwyg

x-hide-mode-switch

Whether to hide edit typo switch tab bar (defaults to false)

InfoButton

This can be used on a button to dispay data bound to a record value (real or dummy). If the name of the button is the name of a field, it is bound to that field. Otherwise, use the x-field attribute to specify the bound field.

When using x-field, the button and the field are 2 distinct elements. Any attributes defined on that field will be used to format the value. Moreover, this allows to change the button attributes without impact on the bound field.

<panel>
  <button name="amountBtn" title="Amount" widget="info-button" x-field="amount" onClick="my-action"/>
  <field name="amount" hidden="true"/>
</panel>

Extra Attributes

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

Attribute Description Default

x-bind

expression to bind to the field value

x-dirty

whether the field contributes to the record dirty check

true

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

false

x-show-icons

comma-separated list of names of icons to show, or false to hide them all :

  • editor: edit, view, select, clear

  • multirelational field: select, new, edit, view, remove

x-can-copy

whether to allow copy of o2m/m2m field items

false

x-direction

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

horizontal

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)

false

x-labels

whether to show label in image-select widget

true

x-order

specify the order of suggest box list

x-limit

specify the maximum number of items in suggest box list

10

x-search-limit

specify the default page limit of search popup

40

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

It accepts an integer for a fix scale, or a field name for a dynamic evaluation.

2

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

x-big

allow duration of more than 100 hours in a duration widget

false

x-seconds

show seconds in a duration widget

false

x-accept

specify the file types the file input should accept

x-color-field

specify the color field to use with tag-select widget

x-popup-maximized

specify whether to open the editor, selector, or all popups as maximized

Expressions

The form view widget’s states can be set using 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. The 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

  • $user - login of current user

  • $group - group code of current user

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