What should onchange methods do and return?

I see a lot of onchange methods in the modules, but I'm not clear on their purpose and what they should return.

Version 7 and lower, the API for onchange methods are different for version 8+

The onchange method are server side functions called by the client when a field in a form view is changed.
They should be used to help the user during data input, allowing him to work faster.

The onchange methods can change the data of all the record fields, not only the field that was changed. If an onchange method changes the value of another field (with the 'value' dict key we'll see in a bit) it will trigger the onchange method of that field, if any. So pay attention to not create onchange loops.

Onchange methods can show errors and/or change fields domain/values by returning a dictionary with one of more of these keys:

  • `warning`
    • Used to show an error popup, useful for example for alerting the user that the value he inserted is invalid.
    • The value should be a dict in the form {'title': <title>, 'message': <message>} where <title> will be the title of the error popup and <message> the error message.
    • This doesn't replace server-side validation: even if the client shows a popup error and doesn't accept the value the user could send a bad value with a direct RPC call, request tampering and other ways..
  • `domain`:
    • Used to change the domain of a relational field. Useful you have a relational field B which options should be related to the value of field A: you can write and onchange method on field A that returns a new domain for field B according to the new value. For example, if you have a field "company" and a field "contact" you can make an onchange method that when you change the company will limit the options of "contact" to only people of that company.
    • The value should be in the form {<field>: <domain>, <field>: <domain>, ...}, where field is the name of the field you want to update and domain is the new domain, in the usual domain notation.
  • `value`:
    • Used to change the value of a field. Onchange methods can change values even if invisible and readonly fields. (but if the fields are readonly the values won't be saved: it should be seen only as a visual hint).
    • The value should be in the form {<field_name>: <value>, <field_name>:  <value>, ...} and value should be in the correct form according to the field type. You can even change the fields of a relational field by using the correct write syntax. For example, you can update the quantity field of all the lines of a sale order.
    • This doesn't replace functional fields and bussiness logic: as with `warning`, the user could bypass the automaatic value set by onchange if he wanted to.

An example of a complete onchange return dict structure (assume the model is sale_order):

    'warning': {'title': 'Error!', 'message': 'Something went wrong! Please check your data'},
    'domain': {'partner_shipping_id': [('parent_id', '=', 42)]},
    'value': {
        'partner_id': 42,
        'note': 'I was changed automatically!',
        'order_lines': [
            (1, 13, {'discount': 30, 'quantity': 10}),
            (1, 14, {'discount': 15, 'quantity': 34}),



Need more info?

This documentation page has been extracted from the Q&A section where you can discuss it and get feedback.
Related question