unclecatvn/agent-skills / skills/odoo-16.0
odoo-16
UnverifiedOdoo 16 development reference for Python models and ORM (search, domain, read_group, compute fields), XML/CSV data and views, OWL/JS client code, QWeb reports, security (ACL, record rules, groups), cron and server actions, migrations and module upgrades, tests, i18n, and performance. Use this skill whenever work involves Odoo 16 or custom addons—even if the user only pastes a traceback, mentions addons/ or __manifest__.py, describes form/tree/kanban/XML errors, HTTP controllers, or business rules on models—including building features, fixing bugs, refactoring, or reviewing addon code. Includes CSS/SCSS asset authoring and review for Odoo addons.
references/odoo-16-owl-guide.md
View on GitHub---
name: odoo-16-owl
description: Complete reference for Odoo 16 OWL (Owl Web Library) 2.x components, hooks, services, registries, and patterns for building interactive JavaScript UI.
globs: "**/static/src/**/*.{js,xml,scss}"
topics:
- OWL basics (Component, setup, template, props, state)
- OWL hooks (useState, useRef, useEffect, useService, useSubEnv, onMounted, onWillStart, onWillUnmount)
- Odoo services (rpc, orm, notification, dialog, action, user, router, ui)
- QWeb templates and directives
- Registries (category, add, get, contains, fields, views, services, main_components)
- Patching existing classes and services
- Assets and module structure
when_to_use:
- Creating custom UI components
- Writing field widgets or view renderers
- Implementing client actions
- Extending or patching existing components
- Calling backend from the frontend
---
# Odoo 16 OWL Guide
Complete reference for Odoo 16 OWL (Owl Web Library) 2.x components, hooks, services, and patterns.
Odoo 16 ships with **OWL 2.x** (`addons/web/static/lib/owl/owl.js`). The exact sub-version can vary by source snapshot, but the component syntax is class-based with a `setup()` method and `static template`.
## Table of Contents
1. [OWL Basics](#owl-basics)
2. [Component Lifecycle](#component-lifecycle)
3. [OWL Hooks](#owl-hooks)
4. [Services (Odoo 16 specifics)](#services-odoo-16-specifics)
5. [QWeb Templates](#qweb-templates)
6. [Registries](#registries)
7. [Patching](#patching)
8. [Assets and File Layout](#assets-and-file-layout)
9. [Common Patterns](#common-patterns)
10. [Best Practices](#best-practices)
11. [Complete Example](#complete-example)
---
## OWL Basics
### Importing from @odoo/owl
```javascript
/** @odoo-module **/
import {
Component,
xml,
useState,
useRef,
useEffect,
useSubEnv,
onMounted,
onWillStart,
onWillUnmount,
} from "@odoo/owl";
```
All OWL primitives come from the `@odoo/owl` package. Odoo-specific hooks live in `@web/core/utils/hooks` and `@web/core/...`.
### Basic Component Structure
```javascript
/** @odoo-module **/
import { Component, useState } from "@odoo/owl";
export class Counter extends Component {
static template = "my_module.Counter";
static props = {
initial: { type: Number, optional: true },
onChange: { type: Function, optional: true },
};
static defaultProps = { initial: 0 };
setup() {
this.state = useState({ value: this.props.initial });
}
increment() {
this.state.value++;
this.props.onChange?.(this.state.value);
}
}
```
### Template in a Separate XML File (Recommended)
`my_module/static/src/counter/counter.js`:
```javascript
/** @odoo-module **/
import { Component, useState } from "@odoo/owl";
export class Counter extends Component {
static template = "my_module.Counter";
static props = { initial: { type: Number, optional: true } };
setup() {
this.state = useState({ value: this.props.initial || 0 });
}
increment() {
this.state.value++;
}
}
```
`my_module/static/src/counter/counter.xml`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<templates xml:space="preserve">
<t t-name="my_module.Counter" owl="1">
<div class="counter">
<button type="button" class="btn btn-primary" t-on-click="increment">
Count: <t t-esc="state.value"/>
</button>
</div>
</t>
</templates>
```
Convention: the template `t-name` should follow `addon_name.ComponentName`; that is a template-name convention, not a filename convention. Put the XML file alongside the component.
### Inline Template with `xml` (Small Components)
```javascript
import { Component, xml, useState } from "@odoo/owl";
export class Tiny extends Component {
static template = xml`
<div t-on-click="onClick">
<t t-esc="state.label"/>
</div>
`;
setup() {
this.state = useState({ label: "Click me" });
}
onClick() {
this.state.label = "Clicked!";
}
}
```
Prefer external XML files for anything non-trivial — you get proper indentation and `web-editor` support for translatable strings.
---
## Component Lifecycle
### Hooks Fired in Order
```javascript
import {
onWillStart,
onWillRender,
onRendered,
onMounted,
onWillUpdateProps,
onWillPatch,
onPatched,
onWillUnmount,
onWillDestroy,
} from "@odoo/owl";
setup() {
onWillStart(async () => {
// Async setup before first render. Good for loading data.
this.records = await this.orm.searchRead("res.partner", [], ["name"]);
});
onMounted(() => {
// DOM is live. Safe to integrate third-party libs.
});
onWillUpdateProps((nextProps) => { /* before props change */ });
onWillPatch(() => { /* before DOM patch */ });
onPatched(() => { /* after DOM patch */ });
onWillUnmount(() => {
// Tear down listeners / timers.
});
onWillDestroy(() => { /* final cleanup */ });
}
```
### Always Use `setup()`, Never `constructor`
```javascript
// CORRECT
class Good extends Component {
setup() {
this.state = useState({ n: 0 });
}
}
// WRONG
class Bad extends Component {
constructor(parent, props) {
super(parent, props);
this.state = useState({ n: 0 }); // Breaks in subclasses and patches.
}
}
```
`setup()` is overridable; `constructor` is not. The whole Odoo extension ecosystem relies on overriding `setup()`.
---
## OWL Hooks
### useState — Reactive State
```javascript
import { useState } from "@odoo/owl";
setup() {
this.state = useState({
count: 0,
user: { name: "Alice", email: "a@x.com" },
tags: ["a", "b"],
});
}
// Any assignment in reactive paths triggers a re-render:
this.state.count++;
this.state.user.name = "Bob";
this.state.tags.push("c");
```
### useRef — DOM References
```javascript
import { useRef, onMounted } from "@odoo/owl";
setup() {
this.input = useRef("input");
onMounted(() => this.input.el?.focus());
}
```
```xml
<input t-ref="input" type="text"/>
```
Access `this.input.el` — it is `null` before mount and after unmount.
### useEffect — Side Effects
```javascript
import { useEffect } from "@odoo/owl";
setup() {
this.state = useState({ query: "" });
// Runs whenever state.query changes
useEffect(
(query) => {
this.search(query);
return () => this.cancelSearch(); // cleanup
},
() => [this.state.query],
);
}
```
### useService — Injected Odoo Services
Defined in `@web/core/utils/hooks`:
```javascript
import { useService } from "@web/core/utils/hooks";
setup() {
this.rpc = useService("rpc"); // Call Python / JSON-RPC URLs
this.orm = useService("orm"); // High-level ORM helper
this.notification = useService("notification");
this.dialog = useService("dialog");
this.action = useService("action");
this.user = useService("user");
this.router = useService("router");
this.ui = useService("ui");
}
```
`useService` throws if the service is not registered. For services that declare async behavior in their metadata, pending async calls are guarded so a destroyed component does not resume with stale results.
### useSubEnv — Scoped Environment
```javascript
import { useSubEnv } from "@odoo/owl";
setup() {
useSubEnv({
model: this.props.record.resModel,
resId: this.props.record.resId,
});
}
```
Child components can read from `this.env.model` etc. Use sparingly — prefer props.
### Odoo-Specific Hooks
From `@web/core/utils/hooks`:
- `useBus(bus, eventName, callback)` — attach/detach a bus listener with proper cleanup.
Other helpers exist in this module, but verify the exact export set in your Odoo 16 server's `addons/web/static/src/core/utils/hooks.js` before depending on less common hooks.
---
## Services (Odoo 16 specifics)
### RPC Service
In Odoo 16, obtain `rpc` with `useService("rpc")`.
```javascript
import { useService } from "@web/core/utils/hooks";
setup() {
this.rpc = useService("rpc");
}
async load() {
// Direct controller call; params becomes the JSON-RPC `params` object.
const result = await this.rpc("/my_module/data", { domain: [["state", "=", "open"]] });
// call_kw is what the ORM service wraps; usually prefer this.orm instead.
const partners = await this.rpc("/web/dataset/call_kw/res.partner/search_read", {
model: "res.partner",
method: "search_read",
args: [[["is_company", "=", true]]],
kwargs: { fields: ["name", "email"] },
});
}
```
### ORM Service
`@web/core/orm_service.js` exposes typed helpers over `/web/dataset/call_kw/...`.
```javascript
this.orm = useService("orm");
// searchRead(model, domain, fields?, kwargs?)
const partners = await this.orm.searchRead(
"res.partner",
[["customer_rank", ">", 0]],
["name", "email", "phone"],
{ limit: 80, offset: 0 },
);
// read(model, ids, fields?, kwargs?)
const records = await this.orm.read("res.partner", [1, 2, 3], ["name"]);
// create(model, recordsList, kwargs?) — pass a LIST of dicts.
// For the single-record case shown here, Odoo 16 returns the created id.
const id = await this.orm.create("res.partner", [
{ name: "New Partner", email: "new@x.com" },
]);
// write(model, ids, values, kwargs?)
await this.orm.write("res.partner", ids, { phone: "555" });
// unlink(model, ids, kwargs?)
await this.orm.unlink("res.partner", ids);
// readGroup(model, domain, fields, groupby, kwargs?)
const groups = await this.orm.readGroup(
"sale.order",
[["state", "!=", "draft"]],
["amount_total:sum"],
["state"],
);
// searchCount(model, domain, kwargs?)
const count = await this.orm.searchCount("res.partner", [["customer_rank", ">", 0]]);
// call(model, method, args?, kwargs?) — arbitrary server method
const res = await this.orm.call("my.model", "action_validate", [recordIds]);
// Silent variant — no global RPC indicator
await this.orm.silent.read("res.partner", [1], ["name"]);
```
### Notification Service
In Odoo 16 the notification API is `notification.add(message, options)` (NOT `notification.notify(...)`).
```javascript
this.notification = useService("notification");
// Simple
this.notification.add("Record saved");
// With options
this.notification.add("Something failed", {
type: "danger", // "success" | "info" | "warning" | "danger"
title: "Error",
sticky: true,
className: "o_my_notif",
onClose: () => console.log("closed"),
buttons: [
{ name: "Retry", primary: true, onClick: () => this.retry() },
],
});
// add() returns a close function
const close = this.notification.add("Working...", { sticky: true });
// later:
close();
```
### Dialog Service
```javascript
import { ConfirmationDialog } from "@web/core/confirmation_dialog/confirmation_dialog";
this.dialog = useService("dialog");
// dialog.add(Component, props, options?)
this.dialog.add(ConfirmationDialog, {
title: _t("Delete record"),
body: _t("Are you sure? This cannot be undone."),
confirmLabel: _t("Delete"),
confirm: async () => {
await this.orm.unlink(this.props.resModel, [this.props.resId]);
},
cancel: () => {},
});
```
`dialog.add` returns a `close` function. The optional third argument accepts `{ onClose }`.
Custom dialog components receive a `close` prop to dismiss themselves.
### Action Service
```javascript
this.action = useService("action");
// Open an act_window
await this.action.doAction({
type: "ir.actions.act_window",
name: "Partners",
res_model: "res.partner",
views: [[false, "tree"], [false, "form"]],
domain: [["customer_rank", ">", 0]],
target: "current", // "current" | "new" | "fullscreen" | "inline"
});
// Open a specific form view
await this.action.doAction({
type: "ir.actions.act_window",
res_model: "res.partner",
res_id: partnerId,
views: [[false, "form"]],
target: "new",
});
// Run a server action or report by XML-id / database id
await this.action.doAction("my_module.action_my_report", {
additionalContext: { default_state: "draft" },
});
// Execute a view button action descriptor
await this.action.doActionButton({
type: "object",
name: "action_confirm",
resModel: "sale.order",
resId: orderId,
resIds: [orderId],
});
```
### User Service
Read-only snapshot of the current user, plus a cached `user.hasGroup(...)`.
```javascript
this.user = useService("user");
this.user.userId; // integer
this.user.name;
this.user.context;
this.user.lang;
this.user.tz;
this.user.isAdmin;
if (await this.user.hasGroup("base.group_system")) {
// ...
}
```
For company-related data, prefer reading the active company information from the session/context your screen already receives, and verify any convenience properties against your Odoo 16 `user_service.js` before relying on them by name.
### Router Service
```javascript
this.router = useService("router");
// Read current URL state
const hash = this.router.current.hash;
// Push updates to the URL hash
this.router.pushState({ view_type: "tree", action: 42 }, { replace: false });
```
### UI Service
```javascript
this.ui = useService("ui");
this.ui.isSmall; // boolean: mobile breakpoint
this.ui.size; // Current SIZES enum value
this.ui.activateElement(el); // Track a new UI active element
this.ui.block(); // Block the whole UI
this.ui.unblock();
```
---
## QWeb Templates
### Directives
```xml
<!-- Render value (escaped) -->
<t t-esc="state.value"/>
<!-- Render value with normal escaping; if you pass markup(...) / other safe markup, Owl trusts it and injects that HTML without escaping -->
<t t-out="state.safeHtml"/>
<!-- Conditionals -->
<div t-if="state.isActive">Active</div>
<div t-elif="state.isPending">Pending</div>
<div t-else="">Idle</div>
<!-- Loops (always include t-key) -->
<t t-foreach="state.records" t-as="rec" t-key="rec.id">
<div t-esc="rec.name"/>
</t>
<!-- Dynamic attributes -->
<input t-att-value="state.value"/>
<div t-att-class="state.isActive ? 'o_active' : ''"/>
<div t-att="{'data-id': rec.id, 'data-name': rec.name}"/>
<a t-attf-href="/record/{{ rec.id }}">Open</a>
<!-- Event handlers -->
<button type="button" t-on-click="onClick">Click</button>
<button type="button" t-on-click.stop="onClick">Click (stop propagation)</button>
<button type="button" t-on-click="() => this.select(item)">Inline arrow</button>
<input t-on-input="onInput"/>
<!-- Two-way binding -->
<input t-model="state.search"/>
<input type="checkbox" t-model="state.isOn"/>
<!-- Local variable -->
<t t-set="total" t-value="state.items.reduce((a, b) => a + b.qty, 0)"/>
<!-- Call another template -->
<t t-call="my_module.SubTemplate">
<t t-set="extra" t-value="'hi'"/>
</t>
<!-- Reference to DOM element -->
<input t-ref="searchInput"/>
```
### Slots
Parent exposes slots; children fill them:
```xml
<!-- Parent template -->
<t t-name="my_module.Card" owl="1">
<div class="card">
<div class="card-header">
<t t-slot="header"/>
</div>
<div class="card-body">
<t t-slot="default"/>
</div>
</div>
</t>
<!-- Usage -->
<Card>
<t t-set-slot="header"><h3>Title</h3></t>
<p>Body content</p>
</Card>
```
Scoped slots pass data to the slot content:
```xml
<!-- Parent -->
<t t-foreach="items" t-as="item" t-key="item.id">
<t t-slot="item" item="item"/>
</t>
<!-- Child -->
<MyList>
<t t-set-slot="item" t-slot-scope="scope">
<span t-esc="scope.item.name"/>
</t>
</MyList>
```
### Sub-Component Usage
```javascript
import { Dropdown } from "@web/core/dropdown/dropdown";
import { DropdownItem } from "@web/core/dropdown/dropdown_item";
export class Toolbar extends Component {
static template = "my_module.Toolbar";
static components = { Dropdown, DropdownItem };
}
```
```xml
<t t-name="my_module.Toolbar" owl="1">
<Dropdown>
<button type="button" class="btn btn-primary">Actions</button>
<t t-set-slot="content">
<DropdownItem onSelected="() => this.save()">Save</DropdownItem>
<DropdownItem onSelected="() => this.discard()">Discard</DropdownItem>
</t>
</Dropdown>
</t>
```
---
## Registries
`@web/core/registry` exposes a central registry with named categories. Registering under the right category is how Odoo discovers your widget/view/service.
```javascript
import { registry } from "@web/core/registry";
```
### Common Categories
| Category | What it holds |
|----------|---------------|
| `"services"` | OWL services (rpc, orm, notification, dialog, action, …) |
| `"main_components"` | Top-level components mounted in the webclient shell |
| `"fields"` | Field widgets (used by form/list views via `widget="..."`) |
| `"views"` | View definitions (list, form, kanban, graph, …) |
| `"actions"` | Client actions (used by `ir.actions.client`) |
| `"systray"` | Systray items |
| `"user_menuitems"` | User menu entries |
| `"formatters"` / `"parsers"` | Field formatters / parsers |
### Registering a Service
```javascript
import { registry } from "@web/core/registry";
export const myService = {
dependencies: ["rpc", "user"],
start(env, { rpc, user }) {
return {
async doStuff(id) {
return rpc("/my/endpoint", { id });
},
};
},
};
registry.category("services").add("myService", myService);
```
Then `this.myService = useService("myService");` from any component.
### Registering a Field Widget
```javascript
import { registry } from "@web/core/registry";
import { Component } from "@odoo/owl";
import { standardFieldProps } from "@web/views/fields/standard_field_props";
export class ColoredBadge extends Component {
static template = "my_module.ColoredBadge";
static props = { ...standardFieldProps };
get value() {
return this.props.record.data[this.props.name];
}
}
export const coloredBadge = {
component: ColoredBadge,
displayName: "Colored Badge",
supportedTypes: ["char"],
extractProps: ({ attrs, options }) => ({
// Map arch attrs to component props if needed
}),
};
registry.category("fields").add("colored_badge", coloredBadge);
```
Use in a view: `<field name="state" widget="colored_badge"/>`.
### Registering a Client Action
```javascript
import { registry } from "@web/core/registry";
import { Component } from "@odoo/owl";
class Dashboard extends Component {
static template = "my_module.Dashboard";
}
registry.category("actions").add("my_module.dashboard", Dashboard);
```
Then create an `ir.actions.client`:
```xml
<record id="action_dashboard" model="ir.actions.client">
<field name="name">Dashboard</field>
<field name="tag">my_module.dashboard</field>
</record>
```
### Other Registry Operations
```javascript
const cat = registry.category("fields");
cat.add("my_widget", def); // throws if already registered
cat.add("my_widget", def, { force: true });
cat.get("my_widget"); // throws if missing
cat.get("my_widget", defaultValue); // safe variant
cat.contains("my_widget"); // boolean
cat.remove("my_widget");
cat.getAll(); // array of values
cat.getEntries(); // array of [key, value]
```
---
## Patching
Prefer supported extension points first in Odoo 16: registries, services, component composition, subclassing where the framework exposes it, and documented hooks. Reach for `patch(...)` only when those options do not cover the behavior you need.
When patching is unavoidable, import it from `@web/core/utils/patch` and use the Odoo 16 signature `patch(obj, patchName, patchValue, options)`:
```javascript
import { patch } from "@web/core/utils/patch";
import { FormController } from "@web/views/form/form_controller";
patch(FormController.prototype, "my_module.FormController", {
// Wrap a real Odoo 16 method only after confirming you truly need a patch.
async saveButtonClicked(params = {}) {
const _super = this._super.bind(this);
const saved = await _super(...arguments);
if (saved) {
console.log("Form save completed");
}
return saved;
},
// Add a new method
myHelper() {
return 42;
},
});
```
Notes:
- Treat patching as a fallback for framework code you cannot extend cleanly through registries or other documented APIs.
- Pass the **prototype** when patching instance methods of a class.
- Pass the **class itself** when patching static members.
- The second argument is a unique patch name string; it must stay unique unless the old patch is removed first with `unpatch(obj, patchName)`.
- In sync methods, call the parent implementation with `this._super(...arguments)`.
- In async methods, bind `_super` before the first `await` because `this._super` is reassigned for each patched call.
- Keep patches small and narrowly scoped so future framework updates are easier to review.
- To remove a patch in tests, import and call `unpatch(obj, patchName)` explicitly.
Patching a service:
```javascript
import { patch } from "@web/core/utils/patch";
import { ORM } from "@web/core/orm_service";
patch(ORM.prototype, "my_module.orm_logging", {
async searchRead(model, domain, fields, kwargs = {}) {
const _super = this._super.bind(this);
console.log("searchRead", model, domain);
return _super(model, domain, fields, kwargs);
},
});
```
---
## Assets and File Layout
### File Structure
```
my_module/static/src/
├── components/
│ ├── my_widget/
│ │ ├── my_widget.js
│ │ ├── my_widget.xml
│ │ └── my_widget.scss
│ └── other_thing/
│ └── ...
├── client_actions/
│ └── partner_panel/
│ ├── partner_panel.js
│ └── partner_panel.xml
├── views/
│ └── my_view/
│ └── ...
└── services/
└── my_service.js
```
### Asset Bundles in `__manifest__.py`
```python
{
'name': 'My Module',
'version': '16.0.1.0.0',
'depends': ['web'],
'assets': {
'web.assets_backend': [
'my_module/static/src/components/**/*',
'my_module/static/src/services/**/*',
'my_module/static/src/client_actions/**/*',
],
'web.assets_frontend': [
'my_module/static/src/public/**/*',
],
'web.assets_common': [
'my_module/static/src/common/**/*',
],
},
}
```
Common bundles in Odoo 16:
- `web.assets_backend` — back-end webclient.
- `web.assets_frontend` — website / portal frontend.
- `web.assets_common` — shared by both.
- `web.report_assets_common` — PDF reports.
- `web.qunit_suite_tests` — QUnit tests.
Declare XML templates inside the same manifest bundle as the JavaScript that uses them. In practice, colocated component folders such as `static/src/components/**/*` or `static/src/client_actions/**/*` are a good default, because both the `.js` and `.xml` files are picked up together.
---
## Common Patterns
### Loading Data in `onWillStart`
```javascript
import { Component, useState, onWillStart } from "@odoo/owl";
import { useService } from "@web/core/utils/hooks";
export class PartnerList extends Component {
static template = "my_module.PartnerList";
static props = { domain: { type: Array, optional: true } };
static defaultProps = { domain: [] };
setup() {
this.orm = useService("orm");
this.state = useState({ partners: [] });
onWillStart(async () => {
this.state.partners = await this.orm.searchRead(
"res.partner",
this.props.domain,
["name", "email"],
{ limit: 80 },
);
});
}
}
```
### Props Validation
```javascript
static props = {
// Required
record: Object,
// Optional primitive
title: { type: String, optional: true },
// Union
value: { type: [String, Number], optional: true },
// Array of strings
tags: { type: Array, element: String, optional: true },
// Object shape
config: {
type: Object,
shape: { limit: Number, offset: Number },
optional: true,
},
// Function
onSave: { type: Function, optional: true },
// Accept anything else (slot spec etc.)
slots: { type: Object, optional: true },
};
static defaultProps = { tags: [] };
```
Avoid `static props = ["*"]` (accept any prop) in user code — it silently hides typos.
### Using `_t` for Translations
```javascript
import { _t } from "@web/core/l10n/translation";
this.notification.add(_t("Record saved"));
this.dialog.add(ConfirmationDialog, {
title: _t("Confirm"),
body: _t("Are you sure?"),
});
```
`_t` is picked up by Odoo's translation export. Do NOT concatenate translated strings, and do not pass interpolation values directly to `_t(...)` in Odoo 16 JS. Translate first, then format the result:
```javascript
import { sprintf } from "@web/core/utils/strings";
sprintf(_t("Hello %s"), name); // good
// bad: avoid passing interpolation args directly to _t(...) in Odoo 16 JS
_t("Hello ") + name; // bad: not fully translatable
```
### Cleaning Up
```javascript
setup() {
const timer = setInterval(() => this.tick(), 1000);
onWillUnmount(() => clearInterval(timer));
}
```
---
## Best Practices
### DO
1. Always use `setup()` (never `constructor`).
2. Put templates in dedicated `.xml` files colocated with the component; keep `addon.ComponentName` for the template `t-name`, not the filename.
3. Load async data in `onWillStart` — components don't render until it resolves.
4. Declare `static props` explicitly; avoid `["*"]`.
5. Use services (`useService`) for cross-cutting concerns rather than imports.
6. Clean up timers / bus listeners in `onWillUnmount`.
7. Use `_t` from `@web/core/l10n/translation` for every user-visible string.
8. Use `t-key` on every `t-foreach`.
9. Interact with the DOM only through `useRef` + lifecycle hooks.
10. Prefer registries, services, hooks, and composition before patching; if you must patch, use `patch(Cls.prototype, "my_module.patch_name", { ... })` and call the parent implementation through `this._super(...)`.
### DON'T
1. Don't override `constructor` — you cannot reach it from subclass `setup()`.
2. Don't import `rpc` as a plain function — in Odoo 16 it is a service (`useService("rpc")`).
3. Don't call `notification.notify(...)` — the v16 API is `notification.add(message, options)`.
4. Don't query the DOM with `document.querySelector` — use refs.
5. Don't mutate `this.props` — props are read-only.
6. Don't store persistent state in plain object properties when you want reactivity — use `useState`.
7. Don't forget to register your service/component in the right registry category.
---
## Complete Example
A client action that lists partners with search, multi-select, and bulk archive.
`my_module/static/src/client_actions/partner_panel/partner_panel.js`:
```javascript
/** @odoo-module **/
import { Component, useState, onWillStart } from "@odoo/owl";
import { useService } from "@web/core/utils/hooks";
import { _t } from "@web/core/l10n/translation";
import { registry } from "@web/core/registry";
import { sprintf } from "@web/core/utils/strings";
import { Dropdown } from "@web/core/dropdown/dropdown";
import { DropdownItem } from "@web/core/dropdown/dropdown_item";
import { ConfirmationDialog } from "@web/core/confirmation_dialog/confirmation_dialog";
export class PartnerPanel extends Component {
static template = "my_module.PartnerPanel";
static components = { Dropdown, DropdownItem };
static props = {};
setup() {
this.orm = useService("orm");
this.notification = useService("notification");
this.dialog = useService("dialog");
this.state = useState({
partners: [],
selected: new Set(),
search: "",
loading: false,
});
onWillStart(() => this.load());
}
async load() {
this.state.loading = true;
try {
this.state.partners = await this.orm.searchRead(
"res.partner",
[["active", "=", true]],
["name", "email", "phone"],
{ limit: 100 },
);
} catch (error) {
this.notification.add(_t("Failed to load partners"), { type: "danger" });
throw error;
} finally {
this.state.loading = false;
}
}
get filteredPartners() {
const q = this.state.search.toLowerCase();
if (!q) {
return this.state.partners;
}
return this.state.partners.filter((p) => p.name.toLowerCase().includes(q));
}
toggle(id) {
if (this.state.selected.has(id)) {
this.state.selected.delete(id);
} else {
this.state.selected.add(id);
}
// Trigger reactivity on Set
this.state.selected = new Set(this.state.selected);
}
onSearchInput(ev) {
this.state.search = ev.target.value;
}
get searchPlaceholder() {
return _t("Search...");
}
get actionsLabel() {
return _t("Actions");
}
get archiveSelectedLabel() {
return _t("Archive selected");
}
get loadingLabel() {
return _t("Loading...");
}
async archiveSelected() {
const ids = [...this.state.selected];
if (!ids.length) {
this.notification.add(_t("No partners selected"), { type: "warning" });
return;
}
this.dialog.add(ConfirmationDialog, {
title: _t("Archive partners"),
body: sprintf(_t("Archive %s partner(s)?"), ids.length),
confirm: async () => {
await this.orm.write("res.partner", ids, { active: false });
this.state.selected = new Set();
await this.load();
this.notification.add(_t("Partners archived"), { type: "success" });
},
cancel: () => {},
});
}
}
registry.category("actions").add("my_module.partner_panel", PartnerPanel);
```
`my_module/static/src/client_actions/partner_panel/partner_panel.xml`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<templates xml:space="preserve">
<t t-name="my_module.PartnerPanel" owl="1">
<div class="o_partner_panel p-3">
<div class="d-flex gap-2 mb-3">
<input
type="text"
class="form-control"
t-att-placeholder="searchPlaceholder"
t-att-value="state.search"
t-on-input="onSearchInput"
/>
<Dropdown>
<button type="button" class="btn btn-primary">
<t t-esc="actionsLabel"/>
</button>
<t t-set-slot="content">
<DropdownItem onSelected="() => this.archiveSelected()">
<t t-esc="archiveSelectedLabel"/>
</DropdownItem>
</t>
</Dropdown>
</div>
<div t-if="state.loading" class="text-center text-muted">
<i class="fa fa-spinner fa-spin"/> <t t-esc="loadingLabel"/>
</div>
<div class="list-group" t-else="">
<t t-foreach="filteredPartners" t-as="p" t-key="p.id">
<button
type="button"
class="list-group-item list-group-item-action d-flex justify-content-between"
t-att-class="state.selected.has(p.id) ? 'active' : ''"
t-on-click="() => this.toggle(p.id)"
>
<span>
<strong t-esc="p.name"/>
<small t-if="p.email" class="text-muted ms-2" t-esc="p.email"/>
</span>
<i class="fa fa-check" t-if="state.selected.has(p.id)"/>
</button>
</t>
</div>
</div>
</t>
</templates>
```
`my_module/__manifest__.py` excerpt:
```python
'assets': {
'web.assets_backend': [
'my_module/static/src/client_actions/**/*',
],
},
```
`my_module/views/client_action.xml`:
```xml
<odoo>
<record id="action_partner_panel" model="ir.actions.client">
<field name="name">Partner Panel</field>
<field name="tag">my_module.partner_panel</field>
</record>
</odoo>
```
---
## Base Code Reference
The APIs documented here live in the Odoo 16 source:
- `addons/web/static/lib/owl/owl.js` — OWL 2.x (`Component`, `useState`, `useRef`, `useEffect`, lifecycle hooks, `xml`).
- `addons/web/static/src/core/utils/hooks.js` — `useService`, `useBus`, and other Odoo-specific hook helpers.
- `addons/web/static/src/core/registry.js` — the registry singleton and categories.
- `addons/web/static/src/core/network/rpc_service.js` — the `rpc` service.
- `addons/web/static/src/core/orm_service.js` — the `orm` service (`ORM` class API).
- `addons/web/static/src/core/notifications/notification_service.js` — `notification.add`.
- `addons/web/static/src/core/dialog/dialog_service.js` — `dialog.add`.
- `addons/web/static/src/webclient/actions/action_service.js` — `action.doAction`, `doActionButton`.
- `addons/web/static/src/core/utils/patch.js` — `patch(obj, patchName, patchValue, options)` and `unpatch(obj, patchName)`.
- `addons/web/static/src/core/l10n/translation.js` — `_t` helper.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |