Form View

The form view shows a single record in form layout. It’s the main view to see a record with details.

Form view has two modes:

  • readonly - mode shows fields values as html text

  • editable - mode shows field editors with values

A form view is defined like this:

<form name="contact-form" title="Contact"
  model="com.axelor.contact.db.Contact"> (1)
  <panel title="Overview"> (2)
    <field name="fullName" readonly="false"> (3)
      <editor> (4)
        <field name="title" colSpan="3"/>
        <field name="firstName" colSpan="4"/>
        <field name="lastName" colSpan="5"/>
      </editor>
    </field>
    <field name="dateOfBirth" />
    <field name="email">
      <viewer><![CDATA[ (5)
      <a href="mailto:{{record.email}}">{{record.email}}</a>
      ]]></viewer>
    </field>
    <field name="phone">
      <viewer><![CDATA[
      <a href="tel:{{record.phone}}">{{record.phone}}</a>
      ]]></viewer>
    </field>
  </panel>
  <panel title="About me">
      <field name="notes" showTitle="false" colSpan="12"/>
  </panel>
  <panel-related field="addresses"> (6)
      <field name="street"/>
      <field name="area"/>
      <field name="city"/>
      <field name="state"/>
      <field name="zip"/>
      <field name="country"/>
  </panel-related>
  <panel sidebar="true"> (7)
    <field name="createdOn"/>
    <field name="createdBy"/>
    <field name="updatedOn"/>
    <field name="updatedBy"/>
  </panel-side>
</form>
1 form view for the given domain model
2 panel to group relevant fields
3 an input field bound to the given model
4 an editor can be used to define custom editor for the field
5 a viewer can be used to define custom template to display field value
6 a panel-related can be used to show o2m/m2m fields
7 a panel to show in the right sidebar

Form view can have following attributes:

Attribute Description

name

name of the view, duplicates are considered overriding

model

fully qualified name of the domain model

title

the form view title

id

If overriding some existing one, provide an unique id to identify this one.

editable

whether the form is editable

readonlyIf

an angular.js boolean expression to make form readonly

onNew

action to be called on creating new record

onLoad

action to be called when record is loaded

onSave

action to be called on saving this form

onSave

action to be called on saving this form

canNew

an angular.js boolean expression to the 'New' button

canEdit

an angular.js boolean expression to the 'Edit' button

canDelete

an angular.js boolean expression to the 'Delete' button

canCopy

an angular.js boolean expression to the 'Copy' button

canSave

an angular.js boolean expression to the 'SAve' button

canAttach

an angular.js boolean expression to the 'Attachment' button

width

The preferred width style of the view : mini, mid or large.

The form uses responsive layout that adjusts according to the available screen size. The form is divided into 12 columns. The first 8 columns are used to place main panels and the rest 4 columns are used to place the sidebar panels. If sidebar panels are not provided the normal panels will occupy all the 12 columns.

Panels

Let’s see each type of panel.

  • panel - panel with 12 columns, generally used to put simple fields

  • panel-tabs - holds another panels which are shown as notebook tabs

  • panel-stack - holds another panels which are attached

  • panel-related - a panel to put o2m/m2m fields

  • panel-include - include another panel form

  • panel-dashlet - dashlet panel can be used to embed another views

Panel

A panel can have following attributes:

Attribute Description

title

title of the panel

name

name of the panel

colSpan

number of columns taken by the widget

itemSpan

default span for child items

hidden

whether to hide the widget

hideIf

an angular.js boolean expression to hide the panel

readonly

whether the widget should be considered readonly

readonlyIf

an angular.js boolean expression to mark the panel readonly

showIf

an angular.js boolean expression to show the panel

onTabSelect

an action to execute when the panel tab is selected (if it’s top-level in panel-tabs)

showFrame

whether to show frame arround the panel

showTitle

whether to show the panel title

sidebar

whether to show this panel in sidebar

attached

whether to attach the panel with previous one

stacked

whether the stack panel items

if-module

use the widget if the given module is installed

<panel title="Overview">
  <!-- widgets -->
</panel-tabs>

Panel Tabs

A panel-tabs holds another panels which are shown as notebook tabs. It includes all panel attributes except for itemSpan, title and showTitle.

<panel-tabs>
  <panel-related field="relatedField"/>
  <panel title="Notes">
    <!-- widgets -->
  </panel>
</panel-tabs>

Panel Stack

A panel-stack holds another panels. It is a stack of panels and child panels are placed one by one.

It include all panel attributes except for itemSpan, title and showTitle.

<panel-stack showIf="color">
  <panel title="Page 1" showIf="color == 'black'"/>
  <panel title="Page 2" showIf="color == 'white'"/>
  <panel title="Page 3" showIf="color == 'gray'"/>
</panel-stack>

A panel-related is used to put o2m/m2m fields. It shows a separate panel bellow the normal panels with a grid widget having fields defined inside.

It include all panel and relational attributes except for itemSpan. A panel-related include following attributes:

Attribute Description

field

title of the panel

editable

whether the grid is inline editable

orderBy

comma separated list of field names to sort the records

onNew

action to be called on creating new record

onChange

action to be called when field value is changed

canMove

whether to allow re-ordering of rows with drag & drop

height

number of rows (not pixel height)

The object should have a numeric field named sequence to allow re-ordering with drag & drop.
<panel-related field="addresses">
  <!-- grid widgets -->
</panel-related>

Panel Include

A panel-include includes another panel form.

A panel-include can have following attributes:

Attribute Description

view

Name of an existing view

from

Name of the module from which the view should be included

if-module

use the widget if the given module is installed

<panel-include view="product-from" from="axelor-sale"/>

Panel Dashlet

A panel-dashlet can be used to embed another views like chart, portlet, iframe …​

A panel-dashlet can have following attributes:

Attribute Description

action

name

name of the panel

title

title of the panel

canSearch

enable search header on grid view portlet

height

height taken by the widget

colSpan

number of columns taken by the widget

hidden

whether to hide the widget

hideIf

an angular.js boolean expression to hide the panel

readonly

whether the widget should be considered readonly

readonlyIf

an angular.js boolean expression to mark the panel readonly

showIf

an angular.js boolean expression to show the panel

showTitle

whether to show the panel title

if-module

use the widget if the given module is installed

<panel-dashlet action="chart:chart.sales.per.month"/>

Panel Widgets

The panel can use following widgets:

  • menu - define a custom menu for the panel

  • field - binds a model field, automatically selects appropriate widget

  • spacer - can be used to skip a cell

  • label - can be used to set a static label (prefer static)

  • static - can be used to show static text (preferred over label)

  • help - can be used to show static help information

  • button - a button widget that executes some action

  • button-group - group of buttons

  • panel - an embed panel

  • panel-dashlet - an embed panel-dashlet

  • panel-include - an embed panel-include

  • panel-related - an embed panel-related

The field has few properties, but most common of them are:

  • name - name of the widget

  • hidden - whether the widget is hidden

  • readonly - whether the widget is readonly

  • required - whether the field is required

Dummy fields

Form view can have dummy fields. These fields are not bound to any of the model fields but used to provide additional context.

Dummy fields can be specified like:

<!-- string field if type is not specified -->
<field name="some" />
<!-- integer field, prefixed with $ to avoid dirty flag -->
<field name="$another" type="integer" min="1" max="100" />

<!-- relational fields -->
<field name="some" type="many-to-one"
  x-target="com.axelor.contact.db.Contact"
  x-target-name="fullName" />

Dummy field names can be prefixed with $ to avoid dirty flag on the form when that field is updated. The context still gets value without the $ prefix.

Field editor

We can define custom editor for fields using <editor> child element on a field.

<!-- editor for a computed field -->
<field name="fullName">
  <editor>
    <field name="title" />
    <field name="firstName" />
    <field name="lastName" />
  </editor>
</field>

<!-- editor for a many-to-one field -->
<field name="customer">
  <editor x-viewer="true">
    <field name="firstName" />
    <field name="lastName" />
    <field name="email" />
  </editor>
</field>

<!-- editor for a one-to-many field -->
<field name="emails">
  <editor layout="table" onNew="compute-default-email">
    <field name="email" />
    <field name="primary" widget="toggle" x-icon="fa-star-o" x-icon-active="fa-star" x-exclusive="true" />
    <field name="optOut" widget="toggle" x-icon="fa-ban" />
    <field name="invalid" widget="toggle" x-icon="fa-exclamation-circle" />
  </editor>
</field>

The editor can have following properties:

  • layout - alternarive layout (panel (default) or table)

  • onNew - an action to call when creating new record (only for one-to-many editors)

  • x-viewer - can be used to consider editor as viewer

  • x-show-titles - whether to show titles on editor fields

  • x-show-on-new - whether to show the editor when creating new record

The toggle widget is specifically created for one-to-many editors to set boolean flags on the record. The toggle widget has following attributes:

  • x-icon - the icon to show when field value is not set or false

  • x-icon-ative - the icon to show when field value is true

  • x-exclusive - if true than the field of only this line of o2m list can be true

Field viewer

We can define custom viewer for fields using <viewer> child element on a field.

<!-- custom viewer on a normal field -->
<field name="fullName">
  <viewer><![CDATA[
  <strong>{{record.fullName|upper}}</strong>
  ]]></viewer>
</field>

<!-- custom viewer on a many-to-one field -->
<field name="customer">
  <viewer depends="fullName,email"><![CDATA[
  <a href="mailto:{{record.customer.email}}">{{record.customer.email}}</a>
  ]]></viewer>
</field>

<!-- customer viewer on a one-to-many field -->
<field name="emails">
  <viewer><![CDATA[
  <a href="mailto:{{record.email}}">{{record.email}}</a>
  ]]></viewer>
</field>

The viewer uses angular.js template to render the values. The template can access current record with record variable.

If viewer uses fields not in current form view, they should be listed as a comma seperated list of fields with depends="" attribute.

The viewer template can have following helper functions to render values:

  • $get(name) - get the nested value

  • $moment(date) - covert date value to moment.js instance

  • $number(value) - convert text value to number

  • $image(fieldName) - get image url for the given image field

  • $fmt(fieldName) - get formated value of the given field