Mastering Odoo 19 Inner Inheritance: 5 Steps to Revolutionize Your QWeb Templates

Hello everyone! Welcome back to Odoistic, your go-to channel for Odoo tutorials, tips, and deep dives. Today, we’re diving into a feature that’s set to transform how you customize Odoo’s front-end: Odoo 19 inner inheritance. This powerful new addition to Odoo 19’s QWeb templating engine introduces a game-changing mode='inner' that allows for incredibly precise and safe template modifications. If you’ve ever struggled with complex XPath expressions or feared that an Odoo update might break your carefully crafted customizations, then this article is for you. We’ll break down exactly how mode='inner' works, why it’s a massive improvement, and provide a clear, step-by-step tutorial to get you started.

For a deeper visual explanation and direct insights from the creator, you can also watch the original video that inspired this guide here: https://www.youtube.com/watch?v=m56O9t1eyVg.

The Challenge: Template Customization in Odoo 19

Before we celebrate the arrival of Odoo 19 inner inheritance, let’s briefly look at the landscape of QWeb template customization in previous Odoo versions. Developers typically relied on two primary inheritance modes: primary and extension. While functional, these modes often introduced significant challenges, especially when dealing with intricate designs or when aiming for long-term maintainability.

The Pitfalls of Old Inheritance Modes:

• primary Mode: This mode was the most drastic. When you used mode='primary', your inheriting template completely replaced the base template. While straightforward for total overhauls, it meant losing all the original structure and content, requiring you to rebuild everything from scratch. This was cumbersome, error-prone, and made it incredibly difficult to track changes or merge upstream updates from Odoo, as you’d effectively have to re-implement the entire template each time.
• extension Mode: The extension mode offered more flexibility, allowing developers to merge changes into an existing template. However, it often necessitated deep manipulation of the Document Object Model (DOM) using complex XPath expressions. Targeting specific elements within a template’s hierarchy could become a developer’s nightmare. If the base template’s structure changed in an Odoo update, your XPath expressions could break, leading to runtime errors or unexpected visual glitches. Developers frequently found themselves carefully crafting long, fragile XPaths or even rebuilding large portions of template structures manually, which was inherently hard to maintain and prone to introducing bugs.
• Risk of Breaking Structure: A major concern with both modes was the inherent risk of disrupting the template’s overall structure. If you only wanted to tweak a header, footer, or a small content block, you often risked unintentionally altering surrounding elements or breaking the template’s intended layout. This led to tedious debugging sessions and slower development cycles.

These challenges underscored a clear need for a more granular, safer, and cleaner way to customize Odoo QWeb templates, especially for inner elements. The community yearned for a solution that would allow developers to target specific content without impacting the wrapping structure.

The Solution: Odoo 19 Inner Inheritance with mode='inner'

Enter Odoo 19, bringing with it a powerful and elegant solution to these long-standing customization headaches: the mode='inner' attribute for QWeb template inheritance. This seemingly small addition represents a significant leap forward, offering developers unprecedented control and safety when modifying existing templates.

Odoo 19 inner inheritance is designed to address the exact pain points described above. When you apply mode='inner' to a QWeb template tag, you are instructing Odoo to only replace or move the inner content of a specific node, while meticulously preserving its outer structure and any surrounding elements. This means you can target a <div>, a <p> tag, or any other element, and modify what’s inside it without touching the element itself or its siblings and parents.

How mode='inner' Works: An Example

Let’s illustrate with a simple example. Imagine you have a base template with a div and you want to change its content without altering the div itself:

Original Base Template (e.g., my_module.base_template):

<template id="my_module.base_template">
    <div class="container">
        <h1>Original Header</h1>
        <p>Some original content.</p>
    </div>
</template>

Inheriting Template using mode='inner':

<template id="my_module.inherit_template" inherit_id="my_module.base_template" mode="inner">
    <xpath expr="//div[@class='container']" position="replace">
        <h2>New Subheader</h2>
        <p>Updated content goes here.</p>
    </xpath>
</template>

In this example, the mode="inner" on the inheriting template, combined with position="replace" for the XPath, tells Odoo to find the div with class="container" in the base template. Then, instead of replacing the entire div, it replaces only the content within that div (i.e., the <h1> and <p> tags) with the new <h2> and <p> tags. The div itself, along with its class="container" attribute, remains perfectly intact. This level of precision is truly transformative.

Key Advantages of mode='inner' for Odoo 19 Inner Inheritance:

• Surgical Precision: Modify only what’s necessary, leaving the rest untouched.
• Structural Integrity: Guarantees that the outer HTML structure of the base template is never compromised.
• Simplified Logic: Reduces the complexity of inheritance rules and XPath expressions.

This feature represents a powerful leap forward for cleaner, safer, and more maintainable QWeb customizations in Odoo.

Why Odoo 19 Inner Inheritance is a Game-Changer

The introduction of mode='inner' in Odoo 19 inner inheritance isn’t just a minor tweak; it’s a fundamental shift in how developers can approach template customization. This new inheritance mode delivers a cascade of benefits that significantly improve the development experience, reduce risks, and enhance the longevity of your custom modules.

Cleaner and Safer Overrides

With mode='inner', your customizations become remarkably cleaner. You no longer need to rewrite entire sections of a template or meticulously reconstruct its structure just to change a single element. Overrides now specifically target only the content you intend to modify, making your code easier to read, understand, and debug. This precise targeting minimizes the risk of inadvertently breaking other parts of the template, leading to much safer customizations overall.

Maintained Wrapping Structure

One of the biggest anxieties in template inheritance used to be the fear of breaking the base template’s intended structure. mode='inner' completely alleviates this. It guarantees that the wrapping HTML structure—the parent tags and their attributes—remains untouched. This is crucial for maintaining consistent styling, JavaScript functionality, and overall UI integrity. You can confidently modify inner content knowing that the surrounding context will stay exactly as designed.

Avoid Conflicts and Improve Upgrade Safety

Odoo is constantly evolving, and core templates are subject to updates and changes with new versions. In the past, such updates often led to merge conflicts and broken customizations because your inheriting template might have entirely replaced the base or relied on XPath expressions that became invalid. With Odoo 19 inner inheritance, this risk is drastically reduced. Since you’re only modifying inner content, your custom code is less likely to conflict with upstream changes to the base template’s outer structure. This translates to much smoother and less painful module upgrades, saving countless hours of debugging and refactoring.

Simpler Inheritance Logic

Gone are the days of needing deep and overly complex XPath hacks to pinpoint a specific element. mode='inner' inherently simplifies the inheritance logic. You don’t need to rebuild parent structures manually, leading to more straightforward and intuitive inheritance definitions. This makes your custom modules easier for new developers to understand and contribute to, lowering the barrier to entry for QWeb customization. For more general insights on building robust Odoo modules, consider exploring resources on Odoo custom module development (placeholder for internal link).

Better Maintainability

The modularity offered by mode='inner' vastly improves the maintainability of your code. Each override is concise and self-contained, clearly defining what specific part of the template it’s affecting. This clarity means that when a bug arises or a new feature needs to be added, developers can quickly identify the relevant piece of code without wading through extensive, convoluted template definitions. The explicit nature of mode='inner' makes overrides clear and self-documenting.

Smoother Front-end and Report Customizations

Whether you’re tweaking a website page, a customer portal, or a printable report, mode='inner' offers a much smoother development experience. Front-end developers can focus on the specific content and layout they want to change, rather than worrying about the underlying template architecture. This leads to faster iteration, more efficient development, and ultimately, a more polished user experience.

In essence, Odoo 19 inner inheritance empowers developers to build more robust, resilient, and manageable customizations. It’s a testament to Odoo’s commitment to improving the developer experience and ensuring that the platform remains adaptable and future-proof.

Tutorial: Implementing Odoo 19 Inner Inheritance with mode='inner'

Now that we understand the immense benefits, let’s walk through a practical, step-by-step guide on how to leverage Odoo 19 inner inheritance using the mode='inner' attribute. This tutorial will show you how to safely modify the inner content of an existing QWeb template without affecting its structural integrity.

Prerequisites:

• An active Odoo 19 (or later) installation.
• A basic working knowledge of Odoo module development.
• Familiarity with creating and modifying XML files in Odoo.
• A fundamental understanding of QWeb templates and HTML structure.

Goal:

To replace specific inner content of a base template while preserving its outer HTML tags and attributes.

Step 1: Identify the Base Template

First, you need to determine which existing QWeb template you wish to modify. You’ll need its unique id. For this tutorial, let’s assume we have a simple module called my_module and it contains a base template defined as follows:

File: my_module/views/base_templates.xml

<odoo>
    <template id="my_module.product_card_template">
        <div class="product-card o_text_center">
            <h3 class="product-title">Original Product Name</h3>
            <p class="product-description">This is the original description of the product.</p>
            <span class="product-price">$99.00</span>
        </div>
    </template>
</odoo>

Our goal is to change the product-title and product-description inside the div.product-card without touching the div itself or the product-price span.

Step 2: Create a New Template to Inherit

Now, create a new XML file in your custom module (e.g., my_module/views/custom_templates.xml) where your inheritance logic will reside. In this file, you’ll define a new template that inherits from my_module.product_card_template. Crucially, you will set mode="inner" on this inheriting template.

<odoo>
    <template id="my_module.inherit_product_card" inherit_id="my_module.product_card_template" mode="inner">
        <!-- Target the product-card div and replace its inner content -->
        <xpath expr="//div[hasclass('product-card')]" position="replace">
            <h3 class="product-title text-success">Custom Product Name</h3>
            <p class="product-description lead">A detailed custom description for our amazing product.</p>
            <!-- The original price span will be preserved as it's not targeted by this specific XPath -->
        </xpath>
    </template>
</odoo>

Explanation of the Inheriting Template:

• id="my_module.inherit_product_card": A unique identifier for your new custom template.
• inherit_id="my_module.product_card_template": This specifies the base template you are extending.
• mode="inner": This is the core of Odoo 19 inner inheritance. It instructs Odoo to perform the inheritance operation only on the inner content of the matched element by the XPath, preserving the outer tag.
• <xpath expr="//div[hasclass('product-card')]" position="replace">: This XPath expression is vital.
  • //div[hasclass('product-card')]: This targets the div element that has the class product-card. Using hasclass() is generally safer than relying on a direct class string match like [@class='product-card'] as it accounts for multiple classes. If you need a refresher on XPath, W3Schools offers a great XPath tutorial (DoFollow).
  • position="replace": This attribute dictates how your new content will be inserted relative to the targeted element. When used with mode="inner", position="replace" will replace the entire inner content of the targeted node. The content inside your <xpath> tag will then become the new inner content.
  Other common position values include:
  1. inside: Appends the content inside the matched element, at the end of its children.
  2. before: Inserts the content as a sibling before the matched element.
  3. after: Inserts the content as a sibling after the matched element.
  4. attributes: Adds or replaces attributes of the matched element. (Note: For mode="inner", this would typically be used to modify attributes of the targeted node, not its inner content directly.)

Step 3: Update Your Module’s Manifest File

Ensure that your module’s __manifest__.py file includes the XML file containing your inheriting template. This tells Odoo to load these template definitions when your module is installed or updated.

File: my_module/__manifest__.py

{
    'name': "My Custom Module",
    'version': '1.0',
    'depends': ['web'], # Or any other necessary dependencies, e.g., 'website'
    'data': [
        'views/base_templates.xml',    # Include your base template if it's part of your module
        'views/custom_templates.xml',  # Crucially, include your inheriting template
    ],
    'installable': True,
    'application': False,
    'auto_install': False,
}

Step 4: Upgrade Your Module

In your Odoo instance, navigate to the “Apps” module. Search for “My Custom Module” (or whatever you named your module) and click the “Upgrade” button. This action will apply your template changes to the Odoo database.

Step 5: Verify the Changes

Finally, navigate to the specific Odoo view or page where my_module.product_card_template is rendered. You should observe the updated content within the original div.product-card structure.

Expected Result:

The rendered HTML should look like this:

<div class="product-card o_text_center">
    <h3 class="product-title text-success">Custom Product Name</h3>
    <p class="product-description lead">A detailed custom description for our amazing product.</p>
    <span class="product-price">$99.00</span>
</div>

Notice how the div with class="product-card" and o_text_center remains, and the span.product-price is also untouched. Only the h3 and p that were explicitly targeted (by being replaced within the XPath with position="replace") have changed, now reflecting your custom content and classes. This clearly demonstrates the power and safety of Odoo 19 inner inheritance.

Key Considerations for Effective mode='inner' Usage

While Odoo 19 inner inheritance simplifies customization significantly, a few considerations will help you leverage it most effectively:

• Precise XPath Expressions: Crafting the correct XPath expression is paramount. An overly broad XPath might affect more than you intend, while an overly narrow one might fail to find the target. Always test your XPath in a browser’s developer console (using $x("your_xpath_here")) to ensure it selects the exact element you want. For complex scenarios, consider using multiple, more specific xpath tags within your template definition. You can find excellent resources on XPath syntax and best practices online, such as this guide to XPath selectors (DoFollow).
• Understanding position with mode='inner': The position attribute behaves slightly differently when mode='inner' is active. Specifically, position="replace" will replace the entire inner content of the targeted node, not the node itself. position="inside" will append to the inner content, and position="attributes" will modify the attributes of the targeted node. Choose your position wisely based on whether you want to add, replace, or modify.
• Module Dependencies: Always ensure that your custom module declares a dependency on any Odoo module that defines the base template you are inheriting from. This guarantees that the base template is loaded before your custom template tries to modify it.
• Thorough Testing: After upgrading your module, always perform comprehensive testing. Check not only the visible changes but also verify that no unexpected side effects have occurred, especially if JavaScript functionalities are tied to the modified HTML elements.
• Readability and Comments: Even with simpler logic, good coding practices dictate clear naming conventions for your template IDs and helpful comments within your XML files to explain complex inheritance choices.

By keeping these points in mind, you can fully harness the potential of mode='inner' to create robust, maintainable, and upgrade-safe customizations in Odoo.

Odoo 18 vs. Odoo 19 mode="inner": A Clear Comparison

To underscore the advancement, let’s briefly compare the fundamental difference in how template customization worked previously versus now.

Feature / Mode	Odoo 18 (e.g., mode="primary" or extension with complex XPath)	Odoo 19 (mode="inner")
Customization Goal	Replace entire template or merge changes by deeply manipulating structure.	Modify only the inner content of a specific node.
Structural Impact	High risk of breaking or completely replacing the original template’s outer structure.	Preserves the outer structure of the targeted node and its siblings.
Complexity	Often required extensive rebuilds, fragile deep XPath expressions, and manual structure reconstruction.	Simpler inheritance logic, directly targeting inner content, reducing the need for complex XPaths.
Upgrade Safety	High likelihood of conflicts and breakage during Odoo core updates due to structural changes.	Significantly improved. Less prone to conflicts as the outer structure remains untouched by your customization.
Maintainability	Harder to maintain, debug, and understand; changes could have ripple effects.	Cleaner, more modular overrides; easier to read, understand, and manage.
Development Speed	Slower due to debugging, careful XPath crafting, and rebuilding efforts.	Faster iteration and development due to precise targeting and reduced risk.

As evident from this comparison, mode="inner" represents a monumental shift towards more developer-friendly, robust, and sustainable Odoo customizations.

Conclusion

The introduction of Odoo 19 inner inheritance with the mode='inner' attribute is a testament to Odoo’s continuous evolution, providing developers with a truly powerful and elegant solution for QWeb template customization. It effectively addresses the long-standing challenges of complexity, fragility, and upgrade headaches that plagued previous inheritance methods.

By allowing you to surgically target and modify only the inner content of elements while preserving their wrapping structure, mode='inner' ensures cleaner overrides, dramatically improves upgrade safety, and simplifies your inheritance logic. This means less time debugging broken templates and more time building innovative features. It truly is a game-changer for front-end and report customizations, fostering a much smoother and more reliable development experience.

So, what do you think? Will this powerful new feature simplify your front-end workflows in Odoo 19? We’d love to hear your thoughts and experiences. Drop a comment below and let’s start a discussion!

If you found this breakdown helpful, don’t forget to like, share, and subscribe to Odoistic for more deep dives into Odoo implementation, customizations, and full implementations. For professional support or custom Odoo development, feel free to reach us at contact@odoistic.co.uk.

Thank you so much for watching, and I will see you in the next video!