# Views

The views are used to display records of an `ModelView` to the user.

In Tryton, `ModelView` can have several views. An action opens a window and defines which view to show.

The views are built from XML that is stored in the view directory of the module or in the databases thanks to the model ir.ui.view.

So generally, they are defined in xml files with this kind of xml where name is the name of the XML file in the view directory:

    <record model="ir.ui.view" id="view_id">
        <field name="model">model name</field>
        <field name="type">type name</field>
        <!--field name="inherit" ref="inherit_view_id"/-->
        <!--field name="field_childs">field name</field-->
        <field name="name">view_name</field>
    </record>

There is three types of views:

> - Form
> - Tree
> - Graph

## Form view

The RNG describing the xml of a form view is stored in trytond/ir/ui/form.rng. There is also a RNC in trytond/ir/ui/form.rnc.

A form view is used to display one record of an object.

Elements of the view are put on the screen following the rules:

> - Elements are placed on the screen from left to right, from top to bottom, according to the order of the xml.
> - The screen composed of a table with a fixed number of columns and enough rows to handle all elements.
> - Elements take one or more columns when they are put in the table. If there are not enough free columns on the current row, the elements are put at the begining of the next row.

### XML description

List of attributes shared by many form elements:

> - `id`: A unique identifier for the tag if there is no name attribute.
> - `yexpand`: A boolean to specify if the label should expand to take up any extra vertical space.
> - `yfill`: A boolean to specify if the label should fill the vertical space allocated to it in the table cell.
> - `yalign`: The vertical alignment, from 0.0 to 1.0.
> - `xexpand`: The same as yexpand but for horizontal space.
> - `xfill`: The same as yfill but for horizontal space.
> - `xalign`: The horizontal alignment, from 0.0 to 1.0.
> - `colspan`: The number of columns the widget must take in the table.

> - `states`: A string of PYSON statement that will be evaluated with the values of the current record.

>   It must return a dictionary where keys can be:

>   > - `invisible`: If true, the widget will be hidden.
>   > - `required`: If true, the field will be required.
>   > - `readonly`: If true, the field will be readonly.
>   > - `icon`: Only for button, it must return the icon name to use or False.
>   > - `pre_validate`: Only for button, it contains a domain to apply on the record before calling the button.

> - `help`: The string that will be displayed when the cursor hovers over the widget.
> - `pre_validate`: A boolean only for fields `trytond.model.fields.One2Many` to specify if the client must pre-validate the records using `trytond.model.Model.pre_validate()`.
> - `completion`: A boolean only for fields `trytond.model.fields.Many2One`, `trytond.model.fields.Many2Many` and `trytond.model.fields.One2Many` to specifiy if the client must auto-complete the field. The default value is True.
> - `factor`: A factor to apply on fields `trytond.model.fields.Integer`, `trytond.model.fields.Float` and `trytond.model.fields.Numeric` to display on the widget. The default value is 1.

#### form

Each form view must start with this tag.

> - `string`: The text that will be used as default title for the tab or the window.

> - `on_write`: The name of a method on the Model of the view that will be called when a record is saved. The method must return a list of record ids that the client must reload if they are already loaded. The function must have this syntax:

>   `on_write(self, ids)`

>   Note

>   The method must be registered in `trytond.model.Model.__rpc__`.

> - `col`: The number of columns for the view.

> - `cursor`: The name of the field that must have the cursor by default.

#### label

Display static string.

> - `string`: The string that will be displayed in the label.
> - `name`: The name of the field whose description will be used for string. Except if `string` is set, it will use this value and the value of the field if `string` is empty.
> - `id`: see common-attributes-id.
> - `yexpand`: see in common-attributes-yexpand.
> - `yfill`: see in common-attributes-yfill.
> - `yalign`: see in common-attributes-yalign.
> - `xexpand`: see in common-attributes-xexpand.
> - `xfill`: see in common-attributes-xfill.
> - `xalign`: see in common-attributes-xalign.
> - `colspan`: see in common-attributes-colspan.
> - `states`: see in common-attributes-states.
> - `help`: see in common-attributes-help.
> - Requires that either `id` or `name` is defined.

#### field

Display a field of the object with the value of the current record.

> - `name`: The name of the field.
> - `string`: The string that will be displayed for the widget.
> - `widget`: The widget that must be used instead of the default one.
> - `help`: The string that will be displayed when the cursor stays over the widget.
> - `width`: The minimum width the widget should request, or -1 to unset.
> - `height`: The minimum height the widget should request, or -1 to unset.
> - `readonly`: Boolean to set the field readonly.
> - `required`: Boolean to set the field required.
> - `mode`: Only for One2Many fields: it is a comma separated list, that specifies the order of the view used to display the relation. (Example: `tree,form`)
> - `view_ids`: A comma separated list that specifies the view ids used to display the relation.
> - `product`: Only for One2Many fields, a comma separated list of target field name used to create records from the cartesian product.
> - `completion`: Only for Many2One fields, it is a boolean to set the completion of the field.
> - `invisible`: The field will not be displayed, but it will fill cells in the table.
> - `filename_visible`: Only for Binary fields, boolean that enables the display of the filename.
> - `yexpand`: see in common-attributes-yexpand.
> - `yfill`: see in common-attributes-yfill.
> - `xexpand`: see in common-attributes-xexpand.
> - `xfill`: see in common-attributes-xfill.
> - `colspan`: see in common-attributes-colspan.
> - `help`: see in common-attributes-help.
> - `pre_validate`: see in common-attributes-pre_validate.
> - `completion`: see in common-attributes-completion.
> - `factor`: see in common-attributes-factor.

#### image

Display an image.

> - `name`: the name of the image. It must be the name with the extension of an image from `tryton/share/pixmaps/`.
> - `yexpand`: see in common-attributes-yexpand.
> - `yfill`: see in common-attributes-yfill.
> - `colspan`: see in common-attributes-colspan.
> - `states`: see in common-attributes-states.
> - `help`: see in common-attributes-help.

#### separator

Display a horizontal separator.

> - `string`: The string that will be displayed above the separator.
> - `name`: The name of the field from which the description will be used for string.
> - `id`: see in common-attributes-id.
> - `yexpand`: see in common-attributes-yexpand.
> - `yfill`: see in common-attributes-yfill.
> - `colspan`: see in common-attributes-colspan.
> - `states`: see in common-attributes-states.
> - `help`: see in common-attributes-help.
> - Requires that either `id` or `name` is defined.

#### newline

Force to use a new row.

#### button

Display a button.

> - `string`: The string that will be displayed inside the button.

> - `name`: The name of the function that will be called. The function must have this syntax:

>   > `button(cls, records)`

>   The function may return an ir.action id or one of those client side action keywords:

> > - `new`: to create a new record
> > - `delete`: to delete the selected records
> > - `remove`: to remove the record if it has a parent
> > - `copy`: to copy the selected records
> > - `next`: to go to the next record
> > - `previous`: to go to the previous record
> > - `close`: to close the current tab
> > - `switch <view type>`: to switch the view to the defined type
> > - `reload`: to reload the current tab
> > - `reload context`: to reload user context
> > - `reload menu`: to reload menu

> - `icon`
> - `confirm`: A text that will be displayed in a confirmation popup when the button is clicked.
> - `colspan`: see in common-attributes-colspan.
> - `states`: see in common-attributes-states.
> - `help`: see in common-attributes-help.

#### notebook

It adds a notebook widget which can contain page tags.

> - `colspan`: see in common-attributes-colspan.
> - `states`: see in common-attributes-states.

#### page

Define a new tab inside a notebook.

> - `string`: The string that will be displayed in the tab.
> - `angle`: The angle in degrees between the baseline of the label and the horizontal, measured counterclockwise.
> - `col`: The number of columns for the page view.
> - `id`: see in common-attributes-id.
> - `states`: see in common-attributes-states.
> - Requires that either `id` or `name` is defined.

#### group

Create a sub-table in a cell.

> - `string`: If set a frame will be drawn around the field with a label containing the string. Otherwise, the frame will be invisible.
> - `rowspan`: The number of rows the group spans in the table.
> - `col`: The number of columns for the group contains.
> - `homogeneous`: If True all the tables cells are the same size.
> - `id`: see in common-attributes-id.
> - `yexpand`: see in common-attributes-yexpand.
> - `yfill`: see in common-attributes-yfill.
> - `colspan`: see in common-attributes-colspan.
> - `states`: see in common-attributes-states.
> - Requires that either `id` or `name` is defined.

#### hpaned, vpaned

> - `position`: The pixel position of divider, a negative value means that the position is unset.
> - `id`: see in common-attributes-id.
> - `colspan`: see in common-attributes-colspan. The default for panes is 4 columns.

#### child

Contains the childs of a hpaned or vpaned.

### Example

    <form string="Party" col="6">
        <label name="name"/>
        <field name="name" xexpand="1"/>
        <label name="code"/>
        <field name="code"/>
        <label name="active"/>
        <field name="active" xexpand="0" width="100"/>
        <notebook colspan="6">
            <page string="General">
                <field name="addresses" mode="form,tree" colspan="4"
                    view_ids="party.address_view_form,party.address_view_tree_sequence"/>
                <label name="type"/>
                <field name="type" widget="selection"/>
                <label name="lang"/>
                <field name="lang" widget="selection"/>
                <label name="website"/>
                <field name="website" widget="url"/>
                <separator string="Categories" colspan="4"/>
                <field name="categories" colspan="4"/>
            </page>
            <page string="Accounting">
                <label name="vat_country"/>
                <field name="vat_country"/>
                <label name="vat_number"/>
                <field name="vat_number"/>
            </page>
        </notebook>
    </form>

## Tree view

The RNG that describes the xml for a tree view is stored in trytond/ir/ui/tree.rng. There is also a RNC in trytond/ir/ui/tree.rnc.

Tree view is used to display records inside a list or a tree.

It is a tree if there is a field_childs defined and this tree will have drag and drop activated if the field_childs and the parent field are defined in the view.

The columns of the view are put on the screen from left to right.

### XML description

#### tree

Each tree view must start with this tag.

> - `string`: The text that will be used as default title for the tab or the window.
> - `on_write`: see form-attributes-on_write.
> - `editable`: If it is set to `top` or `bottom`, the list becomes editable and the new record will be added on `top` or `bottom` of the list.
> - `sequence`: The name of the field that is used for sorting. This field must be an integer and it will be updated to match the new sort order when the user uses `Drag and Drop` on list rows.
> - `keyword_open`: A boolean to specify if the client should look for a tree_open action on double click instead of switching view.
> - `tree_state`: A boolean to specify if the client should save the state of the tree.

#### field

> - `name`: The name of the field.
> - `readonly`: Boolean to set the field readonly.
> - `required`: Boolean to set the field required.
> - `widget`: The widget that must be used instead of the default one.
> - `tree_invisible`: Boolean to display or not the column.
> - `icon`: The name of the field that contains the name of the icon to display in the column.
> - `sum`: A text for the sum widget that will be added on the bottom of list with the sum of all the fields in the column.
> - `width`: Set the width of the column.
> - `expand`: Boolean to specify if the column should be expanded to take available extra space in the view. This space is shared equally among all columns that have their “expand” property set to True. Resize don’t work if this option is enabled.
> - `pre_validate`: see in common-attributes-pre_validate.
> - `completion`: see in common-attributes-completion.
> - `factor`: see in common-attributes-factor.

#### prefix or suffix

A `field` could contain one or many `prefix` or `suffix` that will be diplayed in the same column.

> - `string`: The text that will be displayed.
> - `name`: The name of the field whose value will be displayed.
> - `icon`: The name of the field that contains the name of the icon to display or the name of the icon.

#### button

Same as in form-button.

### Example

    <tree string="Taxes" sequence="sequence">
        <field name="name"/>
        <field name="percentage">
            <suffix string="%"/>
        </field>
        <field name="group"/>
        <field name="type"/>
        <field name="active"/>
        <field name="sequence" tree_invisible="1"/>
    </tree>

#### button

Display a button.

> - `string`: The string that will be displayed inside the button.

> - `name`: The name of the function that will be called. The function must have this syntax:

>   > `button(cls, records)`

> - `confirm`: A text that will be displayed in a confirmation popup when the button is clicked.

> - `help`: see in common-attributes-help

## Graph view

The RNG that describes the xml for a graph view is stored in trytond/ir/ui/graph.rng. There is also a RNC in trytond/ir/ui/graph.rnc.

### XML description

#### graph

Each graph view must start with this tag.

> - `type`: `vbar`, `hbar`, `line`, `pie`
> - `string`: the name of the graph.
> - `background`: an hexaecimal value for the color of the background.
> - `color`: the main color.
> - `legend`: a boolean to specify if the legend must be displayed.

#### x, y

> Describe the field that must be used for axis. `x` must contain only one tag `field` and `y` must at least one but may contain many.

#### field

> - `name`: the name of the field on the object to use.

> - `string`: allow to override the string that comes from the object.

> - `key`: can be used to distinguish fields with the same name but with different domain.

> - `domain`: a PySON string which is evaluated with the object value as context. If the result is true the field value is added to the graph.

> - `fill`: defined if the graph shall be filled.

> - `empty`: defined if the line graph must put a point for missing dates.

> - `color`: the color of the field.

> - `interpolation`: defined how the line graph must interpolate points. The default is `linear`.

>   > - `constant-center`: use the value of the nearest point, see Nearest-neighbor interpolation
>   > - `constant-left`: use the value of the nearest left point.
>   > - `constant-right`: use the value of the nearest right point.
>   > - `linear`: see linear interpolation

### Example

    <graph string="Invoice by date" type="vbar">
      <x>
          <field name="invoice_date"/>
      </x>
      <y>
          <field name="total_amount"/>
      </y>
    </graph>

## Board view

The RNG that describes the xml for a board view is stored in trytond/ir/ui/board.rng. There is also a RNC in trytond/ir/ui/graph.rnc.

Board view is used to display multiple views at once.

Elements are put on the screen followin the same rules as for `Form` view.

The views can be updated by the selection of records on an other view inside the same board by using `Eval()` on the action id of the other view in the domain.

### XML description

#### board

Each board view must start with this tag.

> - `string`: The text that will be used as default titla for the atb or the window.
> - `col`: The number of columns for the view.

#### image

Same as in `Form` view.

#### separator

Same as in `Form` view.

#### label

Same as in `Form` view.

#### newline

Same as in `Form` view.

#### notebook

Same as in `Form` view.

#### page

Same as in `Form` view.

#### group

Same as in `Form` view.

#### hpaned, vpaned

Same as in `Form` view.

#### child

Same as in `Form` view.

#### action

> - `name`: The id of the action window.
> - `colspan`: see in common-attributes-colspan.

## Calendar view

The RNG that describes the xml for a calendar view is stored in trytond/ir/ui/calendar.rng. There is also a RNC in trytond/ir/ui/calendar.rnc.

Calendar view is use to display records as events on a calendar based on a dtstart and optionally a dtend.

### XML description

#### calendar

Each calendar view must start with this tag.

> - `dtstart`: The name of the field that contains the start date.
> - `dtend`: The name of the field that contains the end date.
> - `string`: The text that will be used as default title for the tab or the window.

#### field

> - `name`: The name of the field.

### Example

    <calendar string="Productions" dtstart="planned_date">
        <field name="code"/>
        <field name="product"/>
        <field name="reference"/>
    </calendar>