How to Create & Configure Web Controllers in Odoo 19
Introduction
Web controllers are a core part of Odoo’s web framework and play a critical role in how Odoo applications interact with users, browsers, and external systems. In Odoo 19, web controllers are used to define endpoints that respond to HTTP and JSON requests, making them essential for building dynamic websites, portals, public forms, integrations, and custom APIs.
Unlike standard backend actions that are triggered from the Odoo UI, web controllers allow developers to expose custom URLs that can be accessed directly through a browser or programmatically via API calls. This makes controllers the foundation for features such as website pages, customer portals, checkout flows, AJAX interactions, and third-party system integrations.
A web controller acts as the entry point for a request. When a user accesses a URL, Odoo routes the request to the corresponding controller method, where developers can:
Read request parameters (GET, POST, JSON)
Apply authentication and access rules
Execute business logic through Odoo models
Return responses such as HTML pages, redirects, or JSON data
In Odoo 19, controllers continue to follow a clean and structured design that aligns with Odoo’s MVC-inspired architecture. While models are responsible for business logic and data persistence, controllers focus strictly on request handling and response generation. Keeping this separation clear is crucial for building scalable, secure, and maintainable applications.
This document provides a detailed, step-by-step guide on how to create and configure web controllers in Odoo 19. It covers controller structure, route configuration, security considerations, and real-world examples, enabling developers to confidently implement custom web functionality in production environments.
What Is a Web Controller?
A web controller is a Python class that:
Listens to specific URLs (routes)
Processes HTTP or JSON requests
Interacts with Odoo models
Returns HTML pages, redirects, or JSON responses
Basic Controller Definition
Creating a basic web controller in Odoo 19 involves defining a Python class that inherits from odoo.http.Controller and uses the @http.route decorator to map a URL path to a method.
Define the Controller in Python
In controllers/main.py, import the necessary modules and define your controller class and method.
2. Create a template
Controllers usually work with a QWeb template to render HTML content. The template can display data dynamically passed from the controller.
After installing and upgrading the module, visiting:
http://<your-domain>/my_page
will display the web page defined by the controller. The page can show dynamic content from the database, custom messages, or any HTML defined in the template.
Example: Creating a Contact List Page Using Web Controllers
To display contact information on the website, we create a web controller inside the controllers directory of our custom module. This controller defines a custom URL route and fetches contact records directly from the database. The retrieved data is then passed to a website template, allowing the contact list to be rendered dynamically on the frontend.
This controller creates a website route that allows logged-in users to view a list of customers.
In Odoo, the @http.route decorator plays a key role when creating URL routes. It is used to map a specific URL path to a controller method, defining how incoming web requests are handled. Below is a detailed breakdown of how this syntax works.
@http.route('/customers', type='http', auth='user', website=True
Each part of the decorator has a specific purpose:
type = 'http'
This option specifies that the route handles standard HTTP requests, meaning it is designed to be accessed through a web browser. For API-related routes that exchange data in JSON format, the json type is commonly used instead.
auth = 'user'
This setting controls who is allowed to access the route. Odoo provides several authentication levels:
public – The page can be accessed by anyone, including users who are not logged in.
user – Only logged-in users can open the page.
bearer – Authentication is done using an API token, commonly used for secure API access.
none – No authentication is required, so the route is completely open.
- website
This parameter defines whether the controller is related to the website. Setting it to True connects the route to website pages, while False is used for backend or non-website operations.
methods
This option restricts which HTTP methods are allowed for the route. If it is not specified, all methods are accepted by default. Commonly used methods include:
GET – Used to fetch data without making any changes.
POST – Used to send data or perform updates.
