addons-cm/docs/QWEB_BEST_PRACTICES.md

# QWeb Template Best Practices - Odoo 18

**Reference**: website_sale_aplicoop template error fix
**Odoo Version**: 18.0+
**Created**: 2026-02-16

---

## Table of Contents

1. [Attribute Expression Best Practices](#attribute-expression-best-practices)
2. [None/Null Safety Patterns](#nonenull-safety-patterns)
3. [Variable Computation Patterns](#variable-computation-patterns)
4. [Common Pitfalls](#common-pitfalls)
5. [Real-World Examples](#real-world-examples)

---

## Attribute Expression Best Practices

### The Problem: t-attf-* Operator Issues

**Issue**: QWeb's `t-attf-*` (template attribute) directives don't handle chained `or` operators well when expressions can evaluate to None.

```xml
<!-- ❌ PROBLEMATIC -->
<form t-attf-data-price="{{ price1 or price2 or 0 }}">

<!-- Error when price1 is None and QWeb tries to evaluate: 'NoneType' object is not callable -->
```

### The Solution: Pre-compute Safe Variables

**Key Pattern**: Use `<t t-set>` to compute safe values **before** using them in attributes.

```xml
<!-- ✅ CORRECT -->
<t t-set="safe_price"
   t-value="price1 if price1 else (price2 if price2 else 0)"/>
<form t-attf-data-price="{{ safe_price }}">
```

### Why This Works

1. **Separation of Concerns**: Logic (t-set) is separate from rendering (t-attf-*)
2. **Explicit Evaluation**: QWeb evaluates the conditional expression fully before passing to t-set
3. **Type Safety**: Pre-computed value is guaranteed to be non-None
4. **Readability**: Clear intent of what value is being used

---

## None/Null Safety Patterns

### Pattern 1: Intermediate Variable + Simple Fallback (RECOMMENDED)

**Scenario**: Value might be None, need a default

```python
# Python context
price_value = None  # or any value that could be None
product_price = 100.0
```

```xml
<!-- ✅ BEST: Two-step approach with simple fallback -->
<!-- Step 1: Extract the potentially-None value -->
<t t-set="extracted_price" t-value="some_dict.get('price')"/>

<!-- Step 2: Apply fallback chain using Python's 'or' operator -->
<t t-set="safe_price" t-value="extracted_price or product_price or 0"/>

<!-- Step 3: Use in attributes -->
<div t-attf-data-price="{{ safe_price }}"/>
```

**Why this works**:
- Step 1 extracts without defaults (returns None if missing)
- Step 2 uses Python's short-circuit `or` for safe None-handling
- Step 3 uses simple variable reference in attribute
- QWeb can reliably evaluate each step

### Pattern 2: Nested Object Access (Safe Chaining)

**Scenario**: Need to access nested attributes safely (e.g., `product.uom_id.category_id.name`)

```python
# Python context
product.uom_id = UoM(...)        # Valid UoM with category_id
product.uom_id.category_id = None # Category is None
```

```xml
<!-- ✅ GOOD: Safe nested access with proper chaining -->
<t t-set="safe_category"
   t-value="product.uom_id.category_id.name if (product.uom_id and product.uom_id.category_id) else ''"/>
<div t-attf-data-category="{{ safe_category }}"/>
```

### Pattern 3: Type Coercion

**Scenario**: Value might be wrong type, need guaranteed type

```python
# Python context
quantity = "invalid_string"  # Should be int/float
```

```xml
<!-- ❌ BAD: Type mismatch in attribute -->
<input t-attf-value="{{ quantity }}"/>

<!-- ✅ GOOD: Pre-compute with type checking -->
<t t-set="safe_qty"
   t-value="int(quantity) if (quantity and str(quantity).isdigit()) else 0"/>
<input t-attf-value="{{ safe_qty }}"/>
```

---

## Variable Computation Patterns

### Pattern 1: Extract Then Fallback (The Safe Pattern)

When values might be None, use extraction + fallback:

```xml
<!-- ✅ BEST: Three-step pattern for None-safe variables -->

<!-- Step 1: Extract the value (might be None) -->
<t t-set="value_extracted" t-value="data.get('field')"/>

<!-- Step 2: Apply fallbacks (using Python's or) -->
<t t-set="value_safe" t-value="value_extracted or default1 or default2"/>

<!-- Step 3: Use in template -->
<div t-text="value_safe"/>
<form t-attf-data-value="{{ value_safe }}">
```

**Why it works**:
- Extraction returns None cleanly
- `or` operator handles None values using Python's short-circuit evaluation
- Each step is simple enough for QWeb to parse
- No complex conditionals that might fail

### Pattern 2: Sequential Computation with Dependencies

When multiple variables depend on each other:

```xml
<!-- ✅ GOOD: Compute in order, each referencing previous -->
<t t-set="price_raw" t-value="data.get('price')"/>
<t t-set="price_safe" t-value="price_raw or default_price or 0"/>
<t t-set="price_formatted" t-value="'%.2f' % price_safe"/>

<span t-text="price_formatted"/>
```

### Pattern 3: Conditional Blocks with t-set

For complex branching logic:

```xml
<!-- ✅ GOOD: Complex logic in t-if with t-set -->
<t t-if="product.has_special_price">
    <t t-set="final_price" t-value="product.special_price"/>
</t>
<t t-else="">
    <t t-set="final_price" t-value="product.list_price or 0"/>
</t>

<div t-attf-data-price="{{ final_price }}"/>
```

---

## Common Pitfalls

### Pitfall 1: Complex Conditionals in t-set

**Problem**: Nested `if-else` expressions in t-set fail

```xml
<!-- ❌ WRONG: QWeb can't parse nested conditionals -->
<t t-set="price" t-value="a if a else (b if b else c)"/>
<!-- Result: TypeError: 'NoneType' object is not callable -->

<!-- ✅ CORRECT: Use simple extraction + fallback -->
<t t-set="a_value" t-value="source.get('a')"/>
<t t-set="price" t-value="a_value or b or c"/>
```

**Why**: QWeb's expression parser gets confused by nested `if-else`. Python's `or` operator is simpler and works reliably.

### Pitfall 2: Using `or` Directly in Attributes

**Problem**: The `or` operator might not work in `t-attf-*` contexts

```xml
<!-- ❌ WRONG: Direct or in attribute (may fail) -->
<div t-attf-data-value="{{ obj.value or 'default' }}"/>

<!-- ✅ CORRECT: Pre-compute in t-set -->
<t t-set="safe_value" t-value="obj.value or 'default'"/>
<div t-attf-data-value="{{ safe_value }}"/>
```

**Why**: Attribute parsing is stricter than body content. Always pre-compute to be safe.

### Pitfall 3: Assuming Nested Attributes Exist

**Problem**: Not checking intermediate objects before accessing

```python
# Context: product.uom_id might be None
```

```xml
<!-- ❌ WRONG: Will crash if uom_id is None -->
<div t-attf-uom="{{ product.uom_id.category_id.name }}"/>

<!-- ✅ CORRECT: Check entire chain -->
<t t-set="uom_cat"
   t-value="product.uom_id.category_id.name if (product.uom_id and product.uom_id.category_id) else ''"/>
<div t-attf-uom="{{ uom_cat }}"/>
```

### Pitfall 3: Complex Logic in t-att (non-template attributes)

**Problem**: Using complex expressions in non-template attributes

```xml
<!-- ❌ WRONG: Complex expression in regular attribute -->
<div data-value="{{ complex_function(arg1, arg2) if condition else default }}"/>

<!-- ✅ CORRECT: Pre-compute, keep attributes simple -->
<t t-set="computed_value" t-value="complex_function(arg1, arg2) if condition else default"/>
<div data-value="{{ computed_value }}"/>
```

### Pitfall 4: Forgetting t-attf- Prefix

**Problem**: Using `data-*` instead of `t-attf-data-*`

```xml
<!-- ❌ WRONG: Not interpreted as template attribute -->
<form data-product-id="{{ product.id }}"/>
<!-- Result: Literal "{{ product.id }}" in HTML, not rendered -->

<!-- ✅ CORRECT: Use t-attf- prefix for template attributes -->
<form t-attf-data-product-id="{{ product.id }}"/>
<!-- Result: Actual product ID in HTML -->
```

---

## Real-World Examples

### Example 1: E-commerce Product Card

**Scenario**: Displaying product with optional fields

```xml
<!-- ✅ GOOD: Handles None prices, missing categories -->

<!-- Compute safe values first -->
<t t-set="display_price"
   t-value="product.special_price if product.special_price else product.list_price"/>
<t t-set="safe_price"
   t-value="display_price if display_price else 0"/>
<t t-set="has_tax"
   t-value="product.taxes_id and len(product.taxes_id) > 0"/>
<t t-set="price_with_tax"
   t-value="safe_price * (1 + (product.taxes_id[0].amount/100 if has_tax else 0))"/>

<!-- Use pre-computed values in form -->
<form class="product-card"
    t-attf-data-product-id="{{ product.id }}"
    t-attf-data-price="{{ safe_price }}"
    t-attf-data-price-with-tax="{{ price_with_tax }}"
    t-attf-data-has-tax="{{ '1' if has_tax else '0' }}"
>
    <input type="hidden" name="product_id" t-attf-value="{{ product.id }}"/>
    <span class="price" t-text="'{:.2f}'.format(safe_price)"/>
</form>
```

### Example 2: Nested Data Attributes

**Scenario**: Form with deeply nested object access

```xml
<!-- ✅ GOOD: Null-safe navigation for nested objects -->

<!-- Define safe variables for nested chains -->
<t t-set="partner_id" t-value="order.partner_id.id if order.partner_id else ''"/>
<t t-set="partner_name" t-value="order.partner_id.name if order.partner_id else 'N/A'"/>
<t t-set="company_name"
   t-value="order.partner_id.company_id.name if (order.partner_id and order.partner_id.company_id) else 'N/A'"/>
<t t-set="address"
   t-value="order.partner_id.street if order.partner_id else 'No address'"/>

<!-- Use in form attributes -->
<form class="order-form"
    t-attf-data-partner-id="{{ partner_id }}"
    t-attf-data-partner-name="{{ partner_name }}"
    t-attf-data-company="{{ company_name }}"
    t-attf-data-address="{{ address }}"
>
    ...
</form>
```

### Example 3: Conditional Styling

**Scenario**: Attribute value depends on conditions

```xml
<!-- ✅ GOOD: Pre-compute class/style values -->

<t t-set="stock_level" t-value="product.qty_available"/>
<t t-set="is_low_stock" t-value="stock_level and stock_level <= 10"/>
<t t-set="css_class"
   t-value="'product-low-stock' if is_low_stock else 'product-in-stock'"/>
<t t-set="disabled_attr"
   t-value="'disabled' if (stock_level == 0) else ''"/>

<div t-attf-class="product-card {{ css_class }}"
     t-attf-data-stock="{{ stock_level }}"
     t-attf-disabled="{{ disabled_attr if disabled_attr else None }}">
    ...
</div>
```

---

## Summary Table

| Pattern | ❌ Don't | ✅ Do |
|---------|---------|-------|
| **Fallback values** | `t-attf-x="{{ a or b or c }}"` | `<t t-set="x" t-value="a or b or c"/>` then `{{ x }}` |
| **Nested objects** | `{{ obj.nested.prop }}` | `<t t-set="val" t-value="obj.nested.prop if (obj and obj.nested) else ''"/>` |
| **Type checking** | `<input value="{{ qty }}"/>` | `<t t-set="safe_qty" t-value="int(qty) if is_digit(qty) else 0"/>` |
| **Complex logic** | `{{ function(a, b) if condition else default }}` | Pre-compute in Python, reference in template |
| **Chained operators** | `{{ a or b if c else d or e }}` | Break into multiple t-set statements |

---

## Tools & Validation

### XML Validation
```bash
# Validate XML syntax
python3 -m xml.dom.minidom template.xml

# Or use pre-commit hooks
pre-commit run check-xml
```

### QWeb Template Testing
```python
# In Odoo shell
from odoo.tools import misc
arch = env['ir.ui.view'].search([('name', '=', 'template_name')])[0].arch
# Check if template compiles without errors
```

### Debugging Template Issues
```xml
<!-- Add debug output -->
<t t-set="debug_info" t-value="'DEBUG: value=' + str(some_value)"/>
<span t-if="debug_mode" t-text="debug_info"/>

<!-- Use JavaScript console -->
<script>
    console.log('Data attributes:', document.querySelector('.product-card').dataset);
</script>
```

---

## References

- [Odoo QWeb Documentation](https://www.odoo.com/documentation/18.0/developer/reference/frontend/qweb.html)
- [Odoo Templates](https://www.odoo.com/documentation/18.0/developer/reference/backend/orm.html#templates)
- [Python Ternary Expressions](https://docs.python.org/3/tutorial/controlflow.html#more-on-conditions)

---

## Related Issues & Fixes

- [website_sale_aplicoop Template Error Fix](./FIX_TEMPLATE_ERROR_SUMMARY.md) - Real-world example of this pattern
- [Git Commit 0a0cf5a](../../../.git/logs/HEAD) - Implementation of these patterns

---

**Last Updated**: 2026-02-16
**Odoo Version**: 18.0+
**Status**: ✅ Documented and tested