The previous recipe showed how to pick a specific view for an action. Now we'll demonstrate how to make the form we defined previously more useful.
- Define the form view basic structure:
<record id="form_all_customers" model="ir.ui.view"> <field name="name">All customers</field> <field name="model">res.partner</field> <field name="arch" type="xml"> <form> <!--form content goes here --> </form> </field> </record> - To add a head bar, usually used for action buttons and stage pipeline, add inside the form:
<header> <button type="object" name="open_commercial_entity" string="Open commercial partner" class="oe_highlight" /> </header> - Add fields to the form, using group tags to visually organize them:
<group string="Content" name="my_content"> <field name="name" /> <field name="category_id" widget="many2many_tags" /> </group>
Now the form should display a top bar with a button and two vertically aligned fields.
We'll look at the arch field of the ir.ui.view model. Here, everything that the user sees happens. First, note that views are defined in XML themselves, so you need to pass the attribute type="xml" for the arch field, otherwise the parser will be confused. It is also mandatory that your view definition contains well formed XML, otherwise you'll get in trouble when loading this snippet.
Now, we'll walk through the tags used previously and summarize the others that are available.
When you define a form view, it is mandatory that the first element within the arch field is a form element. This fact is used internally to derive the record's type field, which is why you're not supposed to set this field. You'll see this a lot in legacy code though.
The form element can have two legacy attributes itself, which are string and version. In the previous versions of Odoo, those were used to decide on the title you saw in the breadcrumb and to differentiate between the forms written in pre-7.0 style and afterwards, but both can be considered obsolete by now. The title in the breadcrumb is now inferred from the model's name_get function, while the version is assumed to be 7.0 or above.
In addition to the elements listed next, you can use arbitrary HTML within the form tag. The algorithm is that every element unknown to Odoo is considered plain HTML and simply passed through to the browser. Be careful with that, as the HTML you fill in can interact with the HTML code the Odoo elements generate, which might distort the rendering.
This element is a container for the elements that should be shown in a form's header, which is rendered as a gray bar. Usually, as in this example, you place action buttons here or a status bar if your model has a state field.
The button element is used to allow the user to trigger an action. See the following recipe Adding buttons to forms for details.
The group element is Odoo's main means for organizing content. Fields placed within a group element are rendered with their title, and all the fields within the same group are aligned so that there's also a visual indicator that they belong together. You can also nest the group elements; this causes Odoo to render the contained fields in adjacent columns.
In general, you should use this mechanism for all your fields and only revert to other methods (see next) when necessary.
If you assign the attribute string on a group, its content will be rendered as a heading for the group.
You should develop the habit of assigning a name to every logical group of fields too. This name is not visible to the user, but very helpful when we override views in the following recipes. Keep the name unique within a form definition to avoid confusion about which group you refer to.
In order to actually show and manipulate data, your form should contain some field elements. They have one mandatory attribute name, which refers to the field's name in the model. So above, we offer the user to edit the partner's name and categories. If we only want to show one of them, without the user being able to edit the field, we set the attribute readonly to 1 or True. This attribute actually may contain a small subset of Python code, so readonly="2>1" would make the field read only too. The same applies to the attribute invisible, that you use to have the value read from the database, but not shown to the user. We'll see later in which situations we want to have that.
You must have noticed the attribute widget on the categories field. It defines how the data in the field is supposed to be presented to the user. Every type of field has its standard widget, so you don't have to explicitly choose a widget. But several types provide multiple ways of representation, in which case you might opt for something else than the default. As a complete list of available widgets would exceed the scope of this recipe, you'll have to resort to Odoo's source code to try them out and consult Chapter 15, Web Client Development for details on how to make your own.
On most elements (this includes group, field, and button), you can set the attributes attrs and groups. While
attrs is discussed next, the groups attribute gives you the possibility to show some elements only to the members of certain groups. Simply put the group's XML ID (separated by commas for multiple groups) in the attribute, and the element will be hidden for everyone who is not a member of at least one of the groups mentioned.
There are situations where you might want to deviate from the strict layout groups prescribed. A good example is, if you want the name field of a record to be rendered as a heading, the field's label would interfere with the appearance. In this case, don't put your field into a group element, but for example, into the plain HTML h1 element. Then before the h1 element, put a label element with the for attribute set to your field name:
<label for="name" /> <h1><field name="name" /></h1>
This will be rendered with the field's content as a big heading, but the field's name only small above. That's basically what the standard partner form does.
If you need a line break within a group, use the newline element. It's always empty.
<newline />
Another useful element is the
footer element. When you open a form as a popup, this is the good place to place the action buttons. It will be rendered as a gray bar too, analogous to the header element.
Since form views are basically HTML with some extensions, Odoo also makes extensive use of CSS classes. Two very useful ones are oe_read_only and oe_edit_only – they cause elements with these classes applied to be visible only in read/view mode or only in edit mode. So to have the label visible only in edit mode:
<label for="name" class="oe_edit_only" />
Further, the form element can have attributes create, edit, and delete. If you set one of those to false, the corresponding action won't be available for this form. Without this being explicitly set, the availability of the action is inferred from the user's permissions. Note that this is purely for straightening the UI; don't use this for security.
The widgets described earlier already offer a lot of functionality, but sooner or later you will encounter cases where they don't do exactly what you want. For defining your own widgets, refer to Chapter 15, Web Client Development.