Odoo Frontend Development Skill v6.0
Odoo主题开发技能 v6.0
This skill provides advanced Odoo frontend development capabilities with:
- 🎨 /create-theme Command: Generate complete production-ready theme modules with all files
- 🔧 Theme Feature Activation: model with for template configuration
- 📋 Complete Dynamic Page Reference: All 11 headers, 9 footers, shop, product, blog templates with XML IDs
- 🎯 Design Workflow: Figma → Odoo template matching → configuration → enhancement methodology
- Theme Development: Complete
$o-website-values-palettes
- Auto-detection: Automatically detect Odoo version and map to correct Bootstrap version
- publicWidget Framework: Comprehensive patterns with handling for website builder
- Progressive Web Apps: Service Workers, offline support, push notifications
- Modern JavaScript: TypeScript, ES2020+, Web Components, Owl v1/v2 patterns
- Testing Frameworks: Jest, Cypress, visual regression testing
- Performance Optimization: Core Web Vitals, resource hints, critical CSS
- Accessibility: WCAG 2.1 AA compliance, ARIA patterns, keyboard navigation
- Real-time Features: WebSockets, Server-Sent Events, live collaboration
- MCP Integration: Figma design conversion and Chrome DevTools style extraction
- Theme Scaffolding: Complete theme module generation with proper structure
- Version-Aware: Handle differences between Odoo 14-19 (Bootstrap 4/5, Owl v1/v2, Snippet structures)
- DevOps Ready: CI/CD pipelines, Vite builds, automated testing
本技能提供高级Odoo主题开发能力，包括：
- 🎨 /create-theme 命令：生成包含所有文件的完整生产级主题模块
- 🔧 主题功能激活： 模型结合 实现模板配置
- 📋 完整动态页面参考：11种页眉、9种页脚、店铺、产品、博客模板及对应的XML ID
- 🎯 设计工作流：Figma → Odoo模板匹配 → 配置 → 增强方法论
- 主题开发：完整的
$o-website-values-palettes
- 版本自动检测：自动检测Odoo版本并映射到对应Bootstrap版本
- publicWidget 框架：支持 处理的完整模式，适配网站编辑器
- 渐进式Web应用（PWA）：服务工作者、离线支持、推送通知
- 现代JavaScript：TypeScript、ES2020+、Web Components、Owl v1/v2模式
- 测试框架：Jest、Cypress、视觉回归测试
- 性能优化：核心Web指标、资源提示、关键CSS
- 无障碍访问：WCAG 2.1 AA合规、ARIA模式、键盘导航
- 实时功能：WebSockets、Server-Sent Events、实时协作
- MCP集成：Figma设计转换、Chrome DevTools样式提取
- 主题脚手架：生成结构规范的完整主题模块
- 版本适配：处理Odoo 14-19版本差异（Bootstrap 4/5、Owl v1/v2、Snippet结构）
- DevOps就绪：CI/CD流水线、Vite构建、自动化测试
🎨 /create-theme Command
🎨 /create-theme 命令
Quick Start: Generate a complete, production-ready Odoo theme module.
Interactive mode (recommended)
交互模式（推荐）
Quick mode with arguments
带参数的快速模式
/create-theme <theme_name> <project_path>
/create-theme <theme_name> <project_path>
/create-theme <theme_name> <project_path> --version=17 --colors="#207AB7,#FB9F54,#F6F4F0,#FFFFFF,#191A19" --font="IBM Plex Sans"
/create-theme <theme_name> <project_path> --version=17 --colors="#207AB7,#FB9F54,#F6F4F0,#FFFFFF,#191A19" --font="IBM Plex Sans"
theme_<name>/
├── __init__.py
├── __manifest__.py
├── security/
│ └── ir.model.access.csv
├── data/
│ ├── assets.xml
│ ├── menu.xml
│ └── pages/ # Individual page files (BEST PRACTICE!)
│ ├── home_page.xml # Homepage (inherits website.homepage)
│ ├── aboutus_page.xml # About Us page
│ ├── contactus_page.xml # Contact (inherits website.contactus)
│ └── services_page.xml # Services page
├── views/
│ ├── layout/
│ │ ├── header.xml # Header customization (OPTIONAL)
│ │ ├── footer.xml # Footer customization (OPTIONAL)
│ │ └── templates.xml # Base layout templates
│ └── snippets/
│ └── custom_snippets.xml # Custom snippet definitions
└── static/src/
├── scss/
│ ├── primary_variables.scss # Theme variables + fonts
│ ├── bootstrap_overridden.scss # Bootstrap overrides (OPTIONAL)
│ └── theme.scss # Additional custom styles
├── js/
│ ├── theme.js # publicWidget implementations
│ └── snippets_options.js # Snippet options (if needed)
└── img/
theme_<name>/
├── __init__.py
├── __manifest__.py
├── security/
│ └── ir.model.access.csv
├── data/
│ ├── assets.xml
│ ├── menu.xml
│ └── pages/ # 独立页面文件（最佳实践！）
│ ├── home_page.xml # 首页（继承website.homepage）
│ ├── aboutus_page.xml # 关于我们页面
│ ├── contactus_page.xml # 联系页面（继承website.contactus）
│ └── services_page.xml # 服务页面
├── views/
│ ├── layout/
│ │ ├── header.xml # 页眉自定义（可选）
│ │ ├── footer.xml # 页脚自定义（可选）
│ │ └── templates.xml # 基础布局模板
│ └── snippets/
│ └── custom_snippets.xml # 自定义Snippet定义
└── static/src/
├── scss/
│ ├── primary_variables.scss # 主题变量 + 字体
│ ├── bootstrap_overridden.scss # Bootstrap覆盖（可选）
│ └── theme.scss # 额外自定义样式
├── js/
│ ├── theme.js # publicWidget实现
│ └── snippets_options.js # Snippet选项（按需添加）
└── img/
💡 Simplified Approach (Recommended)
💡 简化方法（推荐）
In MOST cases, you can configure via
$o-website-values-palettes
without custom XML:
When to use custom header.xml/footer.xml:
- Design requires completely custom layout not available in templates
- Need additional HTML elements beyond what templates provide
大多数情况下，无需自定义XML，直接通过
$o-website-values-palettes
配置：
何时需要自定义header.xml/footer.xml:
- 设计需要模板中未提供的完全自定义布局
- 需要添加模板以外的HTML元素
Color System (o-color-1 to o-color-5)
颜色系统（o-color-1 至 o-color-5）
| Variable | Semantic Meaning | Default |
|---|
| Primary brand color | #207AB7 |
| Secondary/accent | #FB9F54 |
| Light backgrounds | #F6F4F0 |
| White/body base | #FFFFFF |
| Dark text/headings | #191A19 |
| 变量 | 语义 | 默认值 |
|---|
| 主品牌色 | #207AB7 |
| 辅助/强调色 | #FB9F54 |
| 浅色背景 | #F6F4F0 |
| 白色/基础背景 | #FFFFFF |
| 深色文本/标题 | #191A19 |
- Odoo 14-15: Bootstrap 4.5.0, simple snippets
- Odoo 16-17: Bootstrap 5.1.3, modern asset bundles
- Odoo 18-19: Bootstrap 5.1.3, snippet groups required
- Odoo 14-15: Bootstrap 4.5.0、基础Snippet
- Odoo 16-17: Bootstrap 5.1.3、现代资源包
- Odoo 18-19: Bootstrap 5.1.3、需配置Snippet分组
Run Script Directly
直接运行脚本
bash
python scripts/create_theme.py <theme_name> <output_path> --version=17 --colors="#207AB7,#FB9F54,#F6F4F0,#FFFFFF,#191A19"
bash
python scripts/create_theme.py <theme_name> <output_path> --version=17 --colors="#207AB7,#FB9F54,#F6F4F0,#FFFFFF,#191A19"
- NEVER edit core Odoo in or directories
- No inline JS/CSS - Create separate and files
- JS modules: Use annotation
- Website themes: Use framework ONLY (not Owl or vanilla JS)
- Bootstrap: Use v5.1.3 classes for Odoo 16+ (never Tailwind)
- Module naming: Use convention
- Translations: Wrap static labels in JS arrays/constants with AT DEFINITION TIME (not via runtime wrappers). Static XML strings are auto-translated.
- 绝对不要修改Odoo核心文件：不要编辑 或 目录下的内容
- 禁止内联JS/CSS：创建独立的 和 文件
- JS模块：使用 注解
- 网站主题：仅使用 框架（禁止使用Owl或原生JS）
- Bootstrap：Odoo 16+ 使用v5.1.3类（禁止使用Tailwind）
- 模块命名：遵循 命名规范
- 翻译：静态标签在JS数组/常量定义时使用 包裹（而非运行时包裹）。XML中的静态字符串会自动翻译。
Auto-Detection Workflow
版本自动检测工作流
Step 1: Detect Odoo Version
步骤1：检测Odoo版本
When starting any frontend task, first detect the Odoo version:
Use the version detector script
使用版本检测脚本
python scripts/version_detector.py <module_path>
The version detector will:
1. Look for `__manifest__.py` or `__openerp__.py`
2. Parse the version field
3. If not found, detect from parent directory (e.g., `odoo17/`)
4. Return:
- Odoo version (e.g., "17.0")
- Bootstrap version (e.g., "5.1.3")
- Owl version (e.g., "2.x" or None)
- Module type (theme, website, custom)
python scripts/version_detector.py <module_path>
版本检测器会：
1. 查找 `__manifest__.py` 或 `__openerp__.py`
2. 解析版本字段
3. 若未找到，从父目录检测（如 `odoo17/`）
4. 返回：
- Odoo版本（如 "17.0"）
- Bootstrap版本（如 "5.1.3"）
- Owl版本（如 "2.x" 或 None）
- 模块类型（主题、网站、自定义）
Step 2: Bootstrap Version Mapping
步骤2：Bootstrap版本映射
Automatic Bootstrap Version Selection:
- Odoo 14-15: Bootstrap 4.5.0
- Odoo 16-19: Bootstrap 5.1.3
自动选择Bootstrap版本:
- Odoo 14-15: Bootstrap 4.5.0
- Odoo 16-19: Bootstrap 5.1.3
Step 3: Owl Version Detection
步骤3：Owl版本检测
JavaScript Framework Selection:
- Odoo 14-15: Owl experimental or jQuery only
- Odoo 16-17: Owl v1
- Odoo 18-19: Owl v2 (with breaking changes)
JavaScript框架选择:
- Odoo 14-15: Owl实验版或仅jQuery
- Odoo 16-17: Owl v1
- Odoo 18-19: Owl v2（存在破坏性变更）
Step 4: Snippet Structure Detection
步骤4：Snippet结构检测
Snippet Registration Method:
- Odoo 14-17: Simple snippet insertion without groups
- Odoo 18-19: Snippet groups required ( with groups)
Snippet注册方式:
- Odoo 14-17: 无需分组，直接插入
- Odoo 18-19: 必须配置 分组
Complete Theme Variables Reference
完整主题变量参考
This section provides complete documentation for the three core SCSS variable systems used in Odoo themes.
本节提供Odoo主题中使用的三个核心SCSS变量系统的完整文档。
📚 1. $o-theme-font-configs - Google Fonts Configuration
📚 1. $o-theme-font-configs - Google字体配置
defines available fonts for Odoo website themes with automatic Google Fonts import.
定义Odoo网站主题可用的字体，支持自动导入Google字体。
scss
$o-theme-font-configs: (
'<Font Name>': (
'family': (<CSS font-family list>), // Required: Font family with fallbacks
'url': '<Google Fonts parameter>', // Required*: Google Fonts query param ONLY
'properties': ( // Optional: Per-context CSS overrides
'<font-alias>': (
'<website-value-key>': <value>,
),
),
),
);
⚠️ CRITICAL: The
key contains
only the query parameter, NOT the full URL!
scss
// ✅ CORRECT - Only the font parameter
'url': 'Poppins:300,300i,400,400i,600,600i,700,700i'
// The system generates: https://fonts.googleapis.com/css?family=Poppins:...&display=swap
// ❌ WRONG - Do not include full URL
'url': 'https://fonts.googleapis.com/css?family=Poppins:300,400,700'
scss
$o-theme-font-configs: (
'<Font Name>': (
'family': (<CSS font-family list>), // 必填：带回退字体的字体族
'url': '<Google Fonts参数>', // 必填*：仅Google Fonts查询参数
'properties': ( // 可选：按上下文覆盖CSS
'<font-alias>': (
'<website-value-key>': <value>,
),
),
),
);
⚠️ 关键注意事项：
字段仅包含
查询参数，而非完整URL！
scss
// ✅ 正确写法 - 仅字体参数
'url': 'Poppins:300,300i,400,400i,600,600i,700,700i'
// 系统会自动生成：https://fonts.googleapis.com/css?family=Poppins:...&display=swap
// ❌ 错误写法 - 不要包含完整URL
'url': 'https://fonts.googleapis.com/css?family=Poppins:300,400,700'
Font Weight Specification
字体权重规范
scss
// Format: FontName:weight1,weight1i,weight2,weight2i,...
// - Number alone = normal style
// - Number + 'i' = italic style
'url': 'Poppins:300,300i,400,400i,600,600i,700,700i'
// Light Light-i Regular Regular-i SemiBold ...
scss
// 格式：FontName:weight1,weight1i,weight2,weight2i,...
// - 仅数字 = 常规样式
// - 数字 + 'i' = 斜体样式
'url': 'Poppins:300,300i,400,400i,600,600i,700,700i'
// 轻量 轻量斜体 常规 常规斜体 半粗体 ...
Multiple Word Font Names
多单词字体名称
scss
// Replace spaces with +
'url': 'Open+Sans:300,300i,400,400i,700,700i'
'url': 'Source+Sans+Pro:300,300i,400,400i,700,700i'
'url': 'DM+Serif+Display:400,400i'
scss
// 空格替换为+
'url': 'Open+Sans:300,300i,400,400i,700,700i'
'url': 'Source+Sans+Pro:300,300i,400,400i,700,700i'
'url': 'DM+Serif+Display:400,400i'
Font Aliases (for 'properties' key)
字体别名（对应'properties'字段）
| Alias | Maps To | Usage |
|---|
| | Body text |
| | All headings (H1-H6) |
| - | - | Individual headings |
| | Navigation menu |
| | Button text |
| - | - | Display text |
| 别名 | 映射目标 | 用途 |
|---|
| | 正文文本 |
| | 所有标题（H1-H6） |
| - | - | 单个标题 |
| | 导航菜单 |
| | 按钮文本 |
| - | - | 展示文本 |
scss
// ⚠️ STANDALONE definition - NO map-merge with core variables!
$o-theme-font-configs: (
'Poppins': (
'family': ('Poppins', sans-serif),
'url': 'Poppins:300,300i,400,400i,500,500i,600,600i,700,700i',
'properties': (
'base': (
'font-size-base': (15 / 16) * 1rem,
'header-font-size': (15 / 16) * 1rem,
),
),
),
'Playfair Display': (
'family': ('Playfair Display', serif),
'url': 'Playfair+Display:400,400i,700,700i',
),
'Inter': (
'family': ('Inter', sans-serif),
'url': 'Inter:300,400,500,600,700',
),
);
scss
// ⚠️ 独立定义 - 不要与核心变量使用map-merge！
$o-theme-font-configs: (
'Poppins': (
'family': ('Poppins', sans-serif),
'url': 'Poppins:300,300i,400,400i,500,500i,600,600i,700,700i',
'properties': (
'base': (
'font-size-base': (15 / 16) * 1rem,
'header-font-size': (15 / 16) * 1rem,
),
),
),
'Playfair Display': (
'family': ('Playfair Display', serif),
'url': 'Playfair+Display:400,400i,700,700i',
),
'Inter': (
'family': ('Inter', sans-serif),
'url': 'Inter:300,400,500,600,700',
),
);
Arabic/RTL Font Support
阿拉伯语/RTL字体支持
scss
$o-theme-font-configs: (
'IBM Plex Sans Arabic': (
'family': ('IBM Plex Sans Arabic', sans-serif),
'url': 'IBM+Plex+Sans+Arabic:100,200,300,400,500,600,700',
),
'Cairo': (
'family': ('Cairo', sans-serif),
'url': 'Cairo:200,300,400,500,600,700,800,900',
),
'Almarai': (
'family': ('Almarai', sans-serif),
'url': 'Almarai:300,400,700,800',
),
);
scss
$o-theme-font-configs: (
'IBM Plex Sans Arabic': (
'family': ('IBM Plex Sans Arabic', sans-serif),
'url': 'IBM+Plex+Sans+Arabic:100,200,300,400,500,600,700',
),
'Cairo': (
'family': ('Cairo', sans-serif),
'url': 'Cairo:200,300,400,500,600,700,800,900',
),
'Almarai': (
'family': ('Almarai', sans-serif),
'url': 'Almarai:300,400,700,800',
),
);
📚 2. $o-color-palettes - Color System
📚 2. $o-color-palettes - 颜色系统
defines all color palettes with 5 core colors plus component assignments.
The Five Core Colors
五种核心颜色
| Color | Semantic Meaning | Typical Usage |
|---|
| Primary/Accent | Brand color, buttons, links, highlights |
| Secondary | Complementary accent, secondary buttons |
| Light Background | Section backgrounds, cards, light areas |
| White/Lightest | Main content background (usually #FFFFFF) |
| Dark/Text | Dark backgrounds, text color, footer |
| 颜色 | 语义 | 典型用途 |
|---|
| 主色/强调色 | 品牌色、按钮、链接、高亮 |
| 辅助色 | 互补强调色、次要按钮 |
| 浅色背景 | 区块背景、卡片、浅色区域 |
| 白色/最浅色 | 主要内容背景（通常为#FFFFFF） |
| 深色/文本色 | 深色背景、文本颜色、页脚 |
Visual Representation
视觉示意图
┌─────────────────────────────────────────────────────────┐
│ o-color-4 (White Background) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ o-color-3 (Light Section) │ │
│ │ Text: o-color-5 (Dark) │ │
│ │ Links: o-color-1 (Primary) │ │
│ │ Buttons: o-color-1 (Primary), o-color-2 (Sec)│ │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ o-color-5 (Dark Section - Footer) │ │
│ │ Text: o-color-4 (White) │ │
│ │ Links: o-color-3 (Light) │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ o-color-4（白色背景） │
│ ┌─────────────────────────────────────────────────┐ │
│ │ o-color-3（浅色区块） │ │
│ │ 文本：o-color-5（深色） │ │
│ │ 链接：o-color-1（主色） │ │
│ │ 按钮：o-color-1（主色）、o-color-2（辅助色）│ │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ o-color-5（深色区块 - 页脚） │ │
│ │ 文本：o-color-4（白色） │ │
│ │ 链接：o-color-3（浅色） │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
Color Combinations (o_cc1 - o_cc5)
颜色组合（o_cc1 - o_cc5）
Color combinations are preset color schemes that automatically set background, text, headings, links, and buttons.
| Class | Background | Typical Usage |
|---|
| (White) | Main content areas |
| (Light) | Alternate sections |
| (Secondary) | Accent sections |
| (Primary) | Call-to-action sections |
| (Dark) | Footer, dark sections |
颜色组合是预设配色方案，自动设置背景、文本、标题、链接和按钮样式。
| 类名 | 背景色 | 典型用途 |
|---|
| （白色） | 主要内容区域 |
| （浅色） | 交替区块 |
| （辅助色） | 强调区块 |
| （主色） | 行动召唤区块 |
| （深色） | 页脚、深色区块 |
Color Palette Structure
调色板结构
scss
$o-color-palettes: map-merge($o-color-palettes, (
'my-palette': (
// Required: The 5 core colors
'o-color-1': #09294F, // Primary (Navy blue)
'o-color-2': #FFA807, // Secondary (Orange)
'o-color-3': #F6F4F0, // Light background
'o-color-4': #FFFFFF, // White
'o-color-5': #1B212C, // Dark
// Component color assignments (1-5 → o_cc1-o_cc5)
'menu': 1, // Menu uses o_cc1
'footer': 5, // Footer uses o_cc5
'copyright': 5, // Copyright uses o_cc5
// Color combination overrides
'o-cc1-text': 'o-color-5',
'o-cc1-headings': 'o-color-5',
'o-cc5-link': 'o-color-4',
'o-cc5-btn-primary': 'o-color-2',
),
));
scss
$o-color-palettes: map-merge($o-color-palettes, (
'my-palette': (
// 必填：5种核心颜色
'o-color-1': #09294F, // 主色（海军蓝）
'o-color-2': #FFA807, // 辅助色（橙色）
'o-color-3': #F6F4F0, // 浅色背景
'o-color-4': #FFFFFF, // 白色
'o-color-5': #1B212C, // 深色
// 组件颜色分配（1-5 对应 o_cc1-o_cc5）
'menu': 1, // 菜单使用o_cc1
'footer': 5, // 页脚使用o_cc5
'copyright': 5, // 版权信息使用o_cc5
// 颜色组合覆盖
'o-cc1-text': 'o-color-5',
'o-cc1-headings': 'o-color-5',
'o-cc5-link': 'o-color-4',
'o-cc5-btn-primary': 'o-color-2',
),
));
Override Syntax for Color Combinations
颜色组合覆盖语法
scss
// Override specific colors within a combination
'o-cc{n}-{property}': value
// Available properties:
'o-cc1-text': #333333, // Text color
'o-cc1-headings': 'o-color-5', // Headings color
'o-cc1-link': 'o-color-1', // Link color
'o-cc1-btn-primary': 'o-color-1', // Primary button
'o-cc1-btn-secondary': 'o-color-2', // Secondary button
// Example for dark background (o_cc5)
'o-cc5-text': rgba(#fff, .8), // Semi-transparent white
'o-cc5-headings': 'o-color-4', // White headings
'o-cc5-link': 'o-color-4', // White links
'o-cc5-btn-primary': 'o-color-2', // Orange buttons on dark
scss
// 覆盖组合中的特定颜色
'o-cc{n}-{property}': value
// 可用属性：
'o-cc1-text': #333333, // 文本颜色
'o-cc1-headings': 'o-color-5', // 标题颜色
'o-cc1-link': 'o-color-1', // 链接颜色
'o-cc1-btn-primary': 'o-color-1', // 主按钮
'o-cc1-btn-secondary': 'o-color-2', // 次要按钮
// 深色背景（o_cc5）示例
'o-cc5-text': rgba(#fff, .8), // 半透明白色
'o-cc5-headings': 'o-color-4', // 白色标题
'o-cc5-link': 'o-color-4', // 白色链接
'o-cc5-btn-primary': 'o-color-2', // 深色背景上的橙色按钮
xml
<!-- White background section -->
<section class="o_cc o_cc1 pt32 pb32">
<div class="container"><h2>Content</h2></div>
</section>
<!-- Light background section -->
<section class="o_cc o_cc2 pt32 pb32">...</section>
<!-- Primary color background (CTA) -->
<section class="o_cc o_cc4 pt32 pb32">...</section>
<!-- Dark background (footer style) -->
<section class="o_cc o_cc5 pt32 pb32">...</section>
xml
<!-- 白色背景区块 -->
<section class="o_cc o_cc1 pt32 pb32">
<div class="container"><h2>内容</h2></div>
</section>
<!-- 浅色背景区块 -->
<section class="o_cc o_cc2 pt32 pb32">...</section>
<!-- 主色背景（行动召唤） -->
<section class="o_cc o_cc4 pt32 pb32">...</section>
<!-- 深色背景（页脚样式） -->
<section class="o_cc o_cc5 pt32 pb32">...</section>
📚 3. $o-website-values-palettes - Complete Configuration (115+ Keys)
📚 3. $o-website-values-palettes - 完整配置（115+ 配置项）
$o-website-values-palettes
is the
master configuration variable controlling Bootstrap components, typography, buttons, inputs, header/footer templates, and much more.
$o-website-values-palettes
是
主配置变量，控制Bootstrap组件、排版、按钮、输入框、页眉/页脚模板等。
Quick Reference by Category
按类别快速参考
| Category | Keys Count | Description |
|---|
| Typography & Fonts | 13 | Font family configuration |
| Font Sizes | 13 | Base and heading sizes |
| Line Heights | 11 | Text spacing |
| Margins | 22 | Heading and paragraph margins |
| Buttons | 17 | Button styling |
| Inputs | 12 | Form field styling |
| Header | 13 | Header/navigation config |
| Footer | 3 | Footer config |
| Links | 1 | Link underline behavior |
| Layout | 3 | Page layout |
| Colors & Gradients | 5 | Color palette and gradients |
| Google Fonts | 2 | Additional font loading |
| Total | 115+ | |
| 类别 | 配置项数量 | 描述 |
|---|
| 排版与字体 | 13 | 字体族配置 |
| 字体大小 | 13 | 基础和标题大小 |
| 行高 | 11 | 文本间距 |
| 边距 | 22 | 标题和段落边距 |
| 按钮 | 17 | 按钮样式 |
| 输入框 | 12 | 表单字段样式 |
| 页眉 | 13 | 页眉/导航配置 |
| 页脚 | 3 | 页脚配置 |
| 链接 | 1 | 链接下划线行为 |
| 布局 | 3 | 页面布局 |
| 颜色与渐变 | 5 | 调色板和渐变 |
| Google字体 | 2 | 额外字体加载 |
| 总计 | 115+ | |
3.1 Typography & Fonts
3.1 Typography & Fonts
| Key | Type | Default | Description |
|---|
| string | First in config | Base font for entire site |
| string | Inherits | Font for H1-H6 headings |
| string | Inherits | Font for navigation menu |
| string | Inherits | Font for button text |
| - | string | Inherits headings | Individual heading fonts |
| - | string | Inherits headings | Display text fonts |
| 配置项 | 类型 | 默认值 | 描述 |
|---|
| string | 配置中的第一个字体 | 全站基础字体 |
| string | 继承 | H1-H6标题字体 |
| string | 继承 | 导航菜单字体 |
| string | 继承 | 按钮文本字体 |
| - | string | 继承标题字体 | 单个标题字体 |
| - | string | 继承标题字体 | 展示文本字体 |
3.2 Font Sizes
3.2 Font Sizes
| Key | Type | Default | Description |
|---|
| size | | Base font size (16px) |
| size | | Small text (14px) |
| - | size | Calculated | Heading sizes |
| - | size | 5rem-2.5rem | Display sizes |
| 配置项 | 类型 | 默认值 | 描述 |
|---|
| size | | 基础字体大小（16px） |
| size | | 小号文本（14px） |
| - | size | 自动计算 | 标题大小 |
| - | size | 5rem-2.5rem | 展示文本大小 |
3.3 Line Heights & Margins
3.3 Line Heights & Margins
| Key | Type | Default | Description |
|---|
| number | | Body text line height |
| number | | All headings line height |
| - | number | Inherits | Individual heading line heights |
| size | | Paragraph top margin |
'paragraph-margin-bottom'
| size | | Paragraph bottom margin |
| size | | Headings top margin |
| size | | Headings bottom margin |
| - | size | Inherits | Individual margins |
| - | size | Inherits | Individual margins |
| 配置项 | 类型 | 默认值 | 描述 |
|---|
| number | | 正文行高 |
| number | | 所有标题行高 |
| - | number | 继承 | 单个标题行高 |
| size | | 段落上边距 |
'paragraph-margin-bottom'
| size | | 段落下边距 |
| size | | 标题上边距 |
| size | | 标题下边距 |
| - | size | 继承 | 单个标题上边距 |
| - | size | 继承 | 单个标题下边距 |
3.4 Buttons (17 Keys)
3.4 Buttons (17 Keys)
| Key | Type | Default | Description |
|---|
| size | Bootstrap | Vertical padding |
| size | Bootstrap | Horizontal padding |
| size | Bootstrap | Font size |
| / | size | Bootstrap | Small button padding |
| / | size | Bootstrap | Large button padding |
| / | size | Bootstrap | Size variants |
| size | Bootstrap | Border thickness |
| size | Bootstrap | Corner radius |
| / | size | Bootstrap | Size variant radius |
| boolean | | Primary as outline |
| boolean | | Secondary as outline |
| boolean | | Flat primary style |
| boolean | | Flat secondary style |
| boolean | | Material Design ripple |
| 配置项 | 类型 | 默认值 | 描述 |
|---|
| size | Bootstrap默认 | 垂直内边距 |
| size | Bootstrap默认 | 水平内边距 |
| size | Bootstrap默认 | 字体大小 |
| / | size | Bootstrap默认 | 小号按钮内边距 |
| / | size | Bootstrap默认 | 大号按钮内边距 |
| / | size | Bootstrap默认 | 尺寸变体 |
| size | Bootstrap默认 | 边框厚度 |
| size | Bootstrap默认 | 圆角半径 |
| / | size | Bootstrap默认 | 尺寸变体圆角 |
| boolean | | 主按钮为轮廓样式 |
| boolean | | 次要按钮为轮廓样式 |
| boolean | | 主按钮为扁平样式 |
| boolean | | 次要按钮为扁平样式 |
| boolean | | Material Design涟漪效果 |
3.5 Inputs & Forms (12 Keys)
3.5 Inputs & Forms (12 Keys)
| Key | Type | Default | Description |
|---|
| / | size | Bootstrap | Input padding |
| size | Bootstrap | Input font size |
| / | size | Bootstrap | Small input padding |
| / | size | Bootstrap | Large input padding |
| size | Bootstrap | Border thickness |
| size | Bootstrap | Corner radius |
| / | size | Bootstrap | Size variant radius |
| 配置项 | 类型 | 默认值 | 描述 |
|---|
| / | size | Bootstrap默认 | 输入框内边距 |
| size | Bootstrap默认 | 输入框字体大小 |
| / | size | Bootstrap默认 | 小号输入框内边距 |
| / | size | Bootstrap默认 | 大号输入框内边距 |
| size | Bootstrap默认 | 边框厚度 |
| size | Bootstrap默认 | 圆角半径 |
| / | size | Bootstrap默认 | 尺寸变体圆角 |
3.6 Header & Navigation (13 Keys)
3.6 Header & Navigation (13 Keys)
| Key | Type | Values | Default | Description |
|---|
| string | See below | | Header layout |
| string | See below | | Nav link styling |
| size | CSS length | Bootstrap | Header text size |
| size | CSS length | Navbar height | Logo height |
| size | CSS length | Smaller | Logo when fixed |
| string | // | | Desktop position |
'hamburger-position-mobile'
| string | // | | Mobile position |
| size | CSS length | null | Menu border |
| size | CSS length | null | Menu corners |
| CSS | shadow/none | null | Menu shadow |
| size | CSS length | | Sidebar width |
Header Template Options:
- - Standard horizontal navbar
- - Hamburger menu (collapsed)
- - Vertical sidebar navigation
- - Full sidebar layout
Header Links Style Options:
- - Standard links
- - Filled background on hover
- - Outline border on hover
- - Rounded pill-shaped links
- - Block-style links
- - Underline border on hover
| 配置项 | 类型 | 可选值 | 默认值 | 描述 |
|---|
| string | 见下文 | | 页眉布局 |
| string | 见下文 | | 导航链接样式 |
| size | CSS长度 | Bootstrap默认 | 页眉文本大小 |
| size | CSS长度 | 导航栏高度 | Logo高度 |
| size | CSS长度 | 更小尺寸 | 固定时的Logo高度 |
| string | // | | 桌面端位置 |
'hamburger-position-mobile'
| string | // | | 移动端位置 |
| size | CSS长度 | null | 菜单边框 |
| size | CSS长度 | null | 菜单圆角 |
| CSS | 阴影/none | null | 菜单阴影 |
| size | CSS长度 | | 侧边栏宽度 |
Header Template Options:
- - 标准水平导航栏
- - 汉堡菜单（折叠式）
- - 垂直侧边导航
- - 全屏侧边栏布局
Header Links Style Options:
- - 标准链接
- - 悬停时填充背景
- - 悬停时显示轮廓边框
- - 圆角胶囊状链接
- - 块级链接
- - 悬停时显示下划线边框
3.7 Footer (3 Keys)
3.7 Footer (3 Keys)
| Key | Type | Values | Default | Description |
|---|
| string | Template name | | Footer layout |
| string | See below | | Animation effect |
| boolean | / | | Scroll-to-top button |
Footer Template Options:
- - Standard footer
- - Center-aligned
- - Clean, minimal
- - Link-heavy
- - Detailed description
Footer Effects:
- - No effect (static)
- - Slide out on hover
- - Shadow on scroll
| 配置项 | 类型 | 可选值 | 默认值 | 描述 |
|---|
| string | 模板名称 | | 页脚布局 |
| string | 见下文 | | 动画效果 |
| boolean | / | | 返回顶部按钮 |
Footer Template Options:
- - 标准页脚
- - 居中对齐
- - 简洁极简
- - 以链接为主
- - 详细描述
Footer Effects:
- - 无效果（静态）
- - 悬停时滑出
- - 滚动时显示阴影
3.8 Links (1 Key)
3.8 Links (1 Key)
| Key | Type | Values | Default | Description |
|---|
| string | // | | Underline behavior |
| 配置项 | 类型 | 可选值 | 默认值 | 描述 |
|---|
| string | // | | 下划线行为 |
3.9 Layout (3 Keys)
3.9 Layout (3 Keys)
| Key | Type | Values | Default | Description |
|---|
| string | / | | Page layout |
| URL | Image path | | Background image |
| string | / | | Background type |
| 配置项 | 类型 | 可选值 | 默认值 | 描述 |
|---|
| string | / | | 页面布局 |
| URL | 图片路径 | | 背景图片 |
| string | / | | 背景类型 |
3.10 Colors & Gradients (5 Keys)
3.10 Colors & Gradients (5 Keys)
| Key | Type | Default | Description |
|---|
| string | null | Active color palette name |
| CSS gradient | null | Menu background gradient |
'menu-secondary-gradient'
| CSS gradient | null | Secondary menu gradient |
| CSS gradient | null | Footer background gradient |
| CSS gradient | null | Copyright gradient |
| 配置项 | 类型 | 默认值 | 描述 |
|---|
| string | null | 激活的调色板名称 |
| CSS gradient | null | 菜单背景渐变 |
'menu-secondary-gradient'
| CSS gradient | null | 次要菜单渐变 |
| CSS gradient | null | 页脚背景渐变 |
| CSS gradient | null | 版权信息渐变 |
3.11 Google Fonts (2 Keys)
3.11 Google Fonts (2 Keys)
| Key | Type | Default | Description |
|---|
| list | null | Additional Google fonts to load |
| map | null | Locally hosted fonts |
| 配置项 | 类型 | 默认值 | 描述 |
|---|
| list | null | 额外加载的Google字体 |
| map | null | 本地托管字体 |
Complete Example - Modern Corporate Theme
Complete Example - Modern Corporate Theme
scss
$o-website-values-palettes: (
(
// === REQUIRED ===
'color-palettes-name': 'my-corporate-palette',
// === TYPOGRAPHY ===
'font': 'Inter',
'headings-font': 'Inter',
'navbar-font': 'Inter',
'buttons-font': 'Inter',
'font-size-base': 1rem,
'headings-line-height': 1.3,
'body-line-height': 1.6,
// === HEADER (NO custom header.xml needed!) ===
'header-template': 'default', // or 'hamburger', 'vertical', 'sidebar'
'header-links-style': 'default', // or 'pills', 'fill', 'border-bottom'
'logo-height': 48px,
'fixed-logo-height': 36px,
// === BUTTONS ===
'btn-padding-y': 0.75rem,
'btn-padding-x': 1.5rem,
'btn-padding-y-lg': 1rem,
'btn-padding-x-lg': 2rem,
'btn-border-radius': 8px,
'btn-border-radius-lg': 12px,
'btn-ripple': true,
// === INPUTS ===
'input-padding-y': 0.75rem,
'input-padding-x': 1rem,
'input-border-radius': 8px,
// === FOOTER (NO custom footer.xml needed!) ===
'footer-template': 'default', // or 'centered', 'minimalist', 'links'
'footer-scrolltop': true,
// === LINKS ===
'link-underline': 'hover', // or 'never', 'always'
// === LAYOUT ===
'layout': 'full', // or 'boxed'
),
);
scss
$o-website-values-palettes: (
(
// === REQUIRED ===
'color-palettes-name': 'my-corporate-palette',
// === TYPOGRAPHY ===
'font': 'Inter',
'headings-font': 'Inter',
'navbar-font': 'Inter',
'buttons-font': 'Inter',
'font-size-base': 1rem,
'headings-line-height': 1.3,
'body-line-height': 1.6,
// === HEADER (NO custom header.xml needed!) ===
'header-template': 'default', // or 'hamburger', 'vertical', 'sidebar'
'header-links-style': 'default', // or 'pills', 'fill', 'border-bottom'
'logo-height': 48px,
'fixed-logo-height': 36px,
// === BUTTONS ===
'btn-padding-y': 0.75rem,
'btn-padding-x': 1.5rem,
'btn-border-radius': 8px,
// === INPUTS ===
'input-padding-y': 0.75rem,
'input-border-radius': 8px,
// === FOOTER (NO custom footer.xml needed!) ===
'footer-template': 'default', // or 'centered', 'minimalist', 'links'
'footer-scrolltop': true,
// === LINKS ===
'link-underline': 'hover', // or 'never', 'always'
// === LAYOUT ===
'layout': 'full', // or 'boxed'
),
);
⚠️ CRITICAL: SCSS Load Order in Odoo Themes
⚠️ CRITICAL: SCSS Load Order in Odoo Themes
Theme SCSS files load BEFORE core Odoo variables are defined!
When you use
in your manifest's asset bundles, your SCSS executes BEFORE Odoo's core
:
LOAD ORDER:
1. YOUR theme's primary_variables.scss (via prepend) ← FIRST
2. Odoo core primary_variables.scss ← SECOND
3. Other SCSS files
⛔ CRITICAL LIMITATIONS:
- CANNOT use map-merge() with core variables (they don't exist yet!)
- , , are all UNDEFINED when your theme loads
❌ WRONG (Will cause "Undefined variable" error):
scss
$o-color-palettes: map-merge($o-color-palettes, (...)); // ERROR!
$o-theme-font-configs: map-merge($o-theme-font-configs, (...)); // ERROR!
✅ CORRECT (Define as standalone):
scss
// Standalone font config (no map-merge!)
$o-theme-font-configs: (
'Poppins': (
'family': ('Poppins', sans-serif),
'url': 'Poppins:300,300i,400,400i,500,500i,600,600i,700,700i',
),
);
// Reference existing palette by name
$o-website-values-palettes: (
(
'color-palettes-name': 'default-1', // Use existing palette name!
'font': 'Poppins',
// ...other values
),
);
❌ WRONG: Do NOT use
records for Google Fonts in themes - this causes malformed URLs!
Theme SCSS files load BEFORE core Odoo variables are defined!
当在manifest的资源包中使用
时，你的SCSS会在Odoo核心
之前执行：
LOAD ORDER:
1. YOUR theme's primary_variables.scss (via prepend) ← 首先加载
2. Odoo core primary_variables.scss ← 其次加载
3. Other SCSS files
⛔ CRITICAL LIMITATIONS:
- CANNOT use map-merge() with core variables (they don't exist yet!)
- , , are all UNDEFINED when your theme loads
❌ WRONG (Will cause "Undefined variable" error):
scss
$o-color-palettes: map-merge($o-color-palettes, (...)); // ERROR!
$o-theme-font-configs: map-merge($o-theme-font-configs, (...)); // ERROR!
✅ CORRECT (Define as standalone):
scss
// Standalone font config (no map-merge!)
$o-theme-font-configs: (
'Poppins': (
'family': ('Poppins', sans-serif),
'url': 'Poppins:300,300i,400,400i,500,500i,600,600i,700,700i',
),
);
// Reference existing palette by name
$o-website-values-palettes: (
(
'color-palettes-name': 'default-1', // Use existing palette name!
'font': 'Poppins',
// ...other values
),
);
❌ WRONG: Do NOT use
records for Google Fonts in themes - this causes malformed URLs!
Theme Page Creation Standard
Theme Page Creation Standard
Individual Page Files Pattern (Recommended)
Individual Page Files Pattern (Recommended)
Create individual page files instead of a single
:
theme_name/
├── data/
│ ├── home.xml # Homepage template + page
│ ├── about.xml # About page template + page
│ ├── contact.xml # Contact page (inherits website.contactus)
│ ├── services.xml # Services page template + page
│ └── menu.xml # Menu configuration
└── views/
└── templates.xml # Shared templates and layout
Create individual page files instead of a single
:
theme_name/
├── data/
│ ├── home.xml # Homepage template + page
│ ├── about.xml # About page template + page
│ ├── contact.xml # Contact page (inherits website.contactus)
│ ├── services.xml # Services page template + page
│ └── menu.xml # Menu configuration
└── views/
└── templates.xml # Shared templates and layout
Homepage (Inherits website.homepage)
Homepage (Inherits website.homepage)
xml
<!-- data/home.xml -->
<template id="view_home" inherit_id="website.homepage" name="Home">
<xpath expr="//div[@id='wrap']" position="replace">
<div id="wrap" class="oe_structure">
<!-- Homepage content here -->
</div>
</xpath>
</template>
xml
<!-- data/home.xml -->
<template id="view_home" inherit_id="website.homepage" name="Home">
<xpath expr="//div[@id='wrap']" position="replace">
<div id="wrap" class="oe_structure">
<!-- Homepage content here -->
</div>
</xpath>
</template>
Contact Page (Inherits website.contactus)
Contact Page (Inherits website.contactus)
xml
<!-- data/contact.xml -->
<template id="view_contact" inherit_id="website.contactus" name="Contact">
<xpath expr="//h1" position="replace">
<h1>Get in Touch</h1>
</xpath>
</template>
xml
<!-- data/contact.xml -->
<template id="view_contact" inherit_id="website.contactus" name="Contact">
<xpath expr="//h1" position="replace">
<h1>Get in Touch</h1>
</xpath>
</template>
Custom Pages (theme.website.page)
Custom Pages (theme.website.page)
xml
<!-- data/about.xml -->
<template id="view_about" name="About">
<t t-call="website.layout">
<div id="wrap" class="oe_structure">
<section class="s_title pt96 pb48">
<div class="container">
<h1>About Us</h1>
</div>
</section>
</div>
</t>
</template>
<record id="page_about" model="theme.website.page">
<field name="view_id" ref="view_about"/>
<field name="is_published" eval="True"/>
<field name="url">/about</field>
<field name="name">About</field>
</record>
xml
<!-- data/about.xml -->
<template id="view_about" name="About">
<t t-call="website.layout">
<div id="wrap" class="oe_structure">
<section class="s_title pt96 pb48">
<div class="container">
<h1>About Us</h1>
</div>
</section>
</div>
</t>
</template>
<record id="page_about" model="theme.website.page">
<field name="view_id" ref="view_about"/>
<field name="is_published" eval="True"/>
<field name="url">/about</field>
<field name="name">About</field>
</record>
Theme Mirror Model Architecture
Theme Mirror Model Architecture
How Themes Install to Pages
How Themes Install to Pages
Theme Module XML
↓
theme.ir.ui.view (Template View)
↓
theme.website.page (Template Page)
↓ (Theme Installation)
↓
ir.ui.view (Actual View with website_id)
↓
website.page (Actual Page with website_id)
Theme Module XML
↓
theme.ir.ui.view (Template View)
↓
theme.website.page (Template Page)
↓ (Theme Installation)
↓
ir.ui.view (Actual View with website_id)
↓
website.page (Actual Page with website_id)
- Theme modules contain models (templates)
- On installation, these convert to actual models with
- Each website gets independent copies, enabling theme reuse
- assignment happens at view creation level
- Theme modules contain models (templates)
- On installation, these convert to actual models with
- Each website gets independent copies, enabling theme reuse
- assignment happens at view creation level
Theme Scaffolding Commands
Theme Scaffolding Commands
Command: Scaffold Complete Theme Module
Command: Scaffold Complete Theme Module
Trigger: User asks to "create theme", "scaffold theme", "generate theme module"
Workflow:
-
Detect Context
bash
# Determine current Odoo version
cd <project_path>
python -c "import sys; sys.path.insert(0, 'helpers'); from version_detector import detect_version; print(detect_version('.'))"
-
Create Module Structure
theme_<name>/
├── __init__.py
├── __manifest__.py
├── security/
│ └── ir.model.access.csv
├── data/
│ ├── assets.xml
│ ├── menu.xml
│ └── pages/
│ ├── home_page.xml
│ └── aboutus_page.xml
├── views/
│ ├── layout/
│ │ ├── header.xml # Header customization (OPTIONAL)
│ │ ├── footer.xml # Footer customization (OPTIONAL)
│ │ └── templates.xml # Base layout templates
│ └── snippets/
│ └── custom_snippets.xml # Custom snippet definitions
├── static/
│ └── src/
│ ├── scss/
│ │ ├── primary_variables.scss
│ │ ├── bootstrap_overridden.scss
│ │ └── theme.scss
│ ├── js/
│ │ ├── theme.js
│ │ └── snippets_options.js
│ └── img/
└── README.md
-
python
{
'name': 'Theme <Name>',
'version': '<odoo_version>.1.0.0',
'category': 'Website/Theme',
'author': 'TaqaTechno',
'website': 'https://www.taqatechno.com/',
'support': 'support@example.com',
'license': 'LGPL-3',
'depends': ['website'],
'data': [
'security/ir.model.access.csv',
'views/layout/templates.xml',
'views/layout/header.xml',
'views/layout/footer.xml',
'views/snippets/custom_snippets.xml',
'data/menu.xml',
'data/pages/home_page.xml',
'data/pages/aboutus_page.xml',
'data/pages/contactus_page.xml',
],
'assets': {
'web._assets_primary_variables': [
('prepend', 'theme_<name>/static/src/scss/primary_variables.scss'),
],
'web._assets_frontend_helpers': [
'theme_<name>/static/src/scss/bootstrap_overridden.scss',
],
'web.assets_frontend': [
'theme_<name>/static/src/scss/theme.scss',
'theme_<name>/static/src/js/theme.js',
],
'website.assets_wysiwyg': [
'theme_<name>/static/src/js/snippets_options.js',
],
},
'installable': True,
'auto_install': False,
'application': False,
}
-
scss
// ===================================================================
// Theme: <Name>
// Generated by TAQAT Techno /create-theme command v5.0
// ===================================================================
//
// ⚠️ IMPORTANT: This file is PREPENDED before Odoo core variables!
// DO NOT use map-merge() with core variables - they don't exist yet!
// ===================================================================
// === Font Configuration (STANDALONE - no map-merge!) ===
$o-theme-font-configs: (
'Inter': (
'family': ('Inter', sans-serif),
'url': 'Inter:300,300i,400,400i,500,500i,600,600i,700,700i',
),
);
// === Website Values Palette (MASTER CONFIGURATION) ===
// NO bootstrap_overridden.scss needed - configure everything here!
$o-website-values-palettes: (
(
// Reference existing palette (avoids map-merge issues)
'color-palettes-name': 'default-1',
// === Typography ===
'font': 'Inter',
'headings-font': 'Inter',
'navbar-font': 'Inter',
'buttons-font': 'Inter',
// === Header (NO custom header.xml needed!) ===
// Options: 'default' | 'hamburger' | 'vertical' | 'sidebar'
'header-template': 'default',
'header-links-style': 'default',
'logo-height': 3rem,
'fixed-logo-height': 2rem,
// === Buttons ===
'btn-padding-y': 0.45rem,
'btn-padding-x': 1.35rem,
'btn-border-radius': 0.25rem,
// === Inputs ===
'input-padding-y': 0.45rem,
'input-border-radius': 0.25rem,
// === Footer (NO custom footer.xml needed!) ===
// Options: 'default' | 'centered' | 'minimalist' | 'links' | 'descriptive'
'footer-template': 'default',
'footer-scrolltop': true,
// === Links & Layout ===
'link-underline': 'hover',
'layout': 'full',
)
);
-
Generate Initial Template
xml
<?xml version="1.0" encoding="utf-8"?>
<odoo>
<!-- Base template inheritance -->
<template id="layout" inherit_id="website.layout">
<xpath expr="//head" position="inside">
<meta name="theme-name" content="<Name>"/>
</xpath>
</template>
</odoo>
Trigger: User asks to "create theme", "scaffold theme", "generate theme module"
Workflow:
-
Detect Context
bash
# Determine current Odoo version
cd <project_path>
python -c "import sys; sys.path.insert(0, 'helpers'); from version_detector import detect_version; print(detect_version('.'))"
-
Create Module Structure
theme_<name>/
├── __init__.py
├── __manifest__.py
├── security/
│ └── ir.model.access.csv
├── data/
│ ├── assets.xml
│ ├── menu.xml
│ └── pages/
│ ├── home_page.xml
│ └── aboutus_page.xml
├── views/
│ ├── layout/
│ │ ├── header.xml # Header customization (OPTIONAL)
│ │ ├── footer.xml # Footer customization (OPTIONAL)
│ │ └── templates.xml # Base layout templates
│ └── snippets/
│ └── custom_snippets.xml # Custom snippet definitions
├── static/
│ └── src/
│ ├── scss/
│ │ ├── primary_variables.scss
│ │ ├── bootstrap_overridden.scss
│ │ └── theme.scss
│ ├── js/
│ │ ├── theme.js
│ │ └── snippets_options.js
│ └── img/
└── README.md
-
python
{
'name': 'Theme <Name>',
'version': '<odoo_version>.1.0.0',
'category': 'Website/Theme',
'author': 'TaqaTechno',
'website': 'https://www.taqatechno.com/',
'support': 'support@example.com',
'license': 'LGPL-3',
'depends': ['website'],
'data': [
'security/ir.model.access.csv',
'views/layout/templates.xml',
'views/layout/header.xml',
'views/layout/footer.xml',
'views/snippets/custom_snippets.xml',
'data/menu.xml',
'data/pages/home_page.xml',
'data/pages/aboutus_page.xml',
'data/pages/contactus_page.xml',
],
'assets': {
'web._assets_primary_variables': [
('prepend', 'theme_<name>/static/src/scss/primary_variables.scss'),
],
'web._assets_frontend_helpers': [
'theme_<name>/static/src/scss/bootstrap_overridden.scss',
],
'web.assets_frontend': [
'theme_<name>/static/src/scss/theme.scss',
'theme_<name>/static/src/js/theme.js',
],
'website.assets_wysiwyg': [
'theme_<name>/static/src/js/snippets_options.js',
],
},
'installable': True,
'auto_install': False,
'application': False,
}
-
scss
// ===================================================================
// Theme: <Name>
// Generated by TAQAT Techno /create-theme command v5.0
// ===================================================================
//
// ⚠️ IMPORTANT: This file is PREPENDED before Odoo core variables!
// DO NOT use map-merge() with core variables - they don't exist yet!
// ===================================================================
// === Font Configuration (STANDALONE - no map-merge!) ===
$o-theme-font-configs: (
'Inter': (
'family': ('Inter', sans-serif),
'url': 'Inter:300,300i,400,400i,500,500i,600,600i,700,700i',
),
);
// === Website Values Palette (MASTER CONFIGURATION) ===
// NO bootstrap_overridden.scss needed - configure everything here!
$o-website-values-palettes: (
(
// Reference existing palette (avoids map-merge issues)
'color-palettes-name': 'default-1',
// === Typography ===
'font': 'Inter',
'headings-font': 'Inter',
'navbar-font': 'Inter',
'buttons-font': 'Inter',
// === Header (NO custom header.xml needed!) ===
// Options: 'default' | 'hamburger' | 'vertical' | 'sidebar'
'header-template': 'default',
'header-links-style': 'default',
'logo-height': 3rem,
'fixed-logo-height': 2rem,
// === Buttons ===
'btn-padding-y': 0.45rem,
'btn-padding-x': 1.35rem,
'btn-border-radius': 0.25rem,
// === Inputs ===
'input-padding-y': 0.45rem,
'input-border-radius': 0.25rem,
// === Footer (NO custom footer.xml needed!) ===
// Options: 'default' | 'centered' | 'minimalist' | 'links' | 'descriptive'
'footer-template': 'default',
'footer-scrolltop': true,
// === Links & Layout ===
'link-underline': 'hover',
'layout': 'full',
)
);
-
Generate Initial Template
xml
<?xml version="1.0" encoding="utf-8"?>
<odoo>
<!-- Base template inheritance -->
<template id="layout" inherit_id="website.layout">
<xpath expr="//head" position="inside">
<meta name="theme-name" content="<Name>"/>
</xpath>
</template>
</odoo>
Command: Create Snippet (Version-Aware)
Command: Create Snippet (Version-Aware)
Trigger: User asks to "create snippet", "add custom snippet"
Workflow:
-
Detect Odoo Version (determines registration method)
-
For Odoo 17 and Earlier:
xml
<!-- Snippet Template -->
<template id="s_<snippet_name>" name="<Snippet Name>">
<section class="s_<snippet_name>" data-name="<Snippet Name>">
<div class="container">
<!-- Content here -->
</div>
</section>
</template>
<!-- Snippet Registration (Odoo 17) -->
<template id="s_<snippet_name>_insert" inherit_id="website.snippets">
<xpath expr="//div[@id='snippet_effect']//t[@t-snippet][last()]" position="after">
<t t-snippet="theme_<name>.s_<snippet_name>"
string="<Snippet Name>"
t-thumbnail="/theme_<name>/static/img/snippets/<snippet_name>.svg"/>
</xpath>
</template>
-
For Odoo 18/19:
xml
<!-- Snippet Template -->
<template id="s_<snippet_name>" name="<Snippet Name>">
<section class="s_<snippet_name>" data-name="<Snippet Name>">
<div class="container">
<!-- Content here -->
</div>
</section>
</template>
<!-- Snippet Group (if custom group needed) -->
<template id="snippet_group_custom" inherit_id="website.snippets">
<xpath expr="//div[@id='snippet_groups']" position="inside">
<t snippet-group="custom"
t-snippet="website.s_snippet_group"
string="Custom Snippets"/>
</xpath>
</template>
<!-- Snippet Registration (Odoo 18/19) -->
<template id="s_<snippet_name>_insert" inherit_id="website.snippets">
<xpath expr="//div[@id='snippet_structure']/*[1]" position="before">
<t t-snippet="theme_<name>.s_<snippet_name>"
string="<Snippet Name>"
group="custom"
t-thumbnail="/theme_<name>/static/img/snippets/<snippet_name>.svg"/>
</xpath>
</template>
-
Generate Snippet Options (if needed)
xml
<template id="s_<snippet_name>_options" inherit_id="website.snippet_options">
<xpath expr="." position="inside">
<div data-selector=".s_<snippet_name>">
<!-- Layout Options -->
<we-select string="Layout">
<we-button data-select-class="">Default</we-button>
<we-button data-select-class="s_<snippet_name>_alt">Alternate</we-button>
</we-select>
<!-- Add Item Button -->
<we-row string="Items">
<we-button data-add-item="true"
data-no-preview="true"
class="o_we_bg_brand_primary">Add Item</we-button>
</we-row>
<!-- Color Picker -->
<we-colorpicker string="Background Color"
data-css-property="background-color"/>
</div>
</xpath>
</template>
-
Generate JavaScript for Options (if dynamic behavior needed)
javascript
import options from "@web_editor/js/editor/snippets.options";
options.registry.<SnippetName> = options.Class.extend({
addItem: function(previewMode, widgetValue, params) {
let $lastItem = this.$target.find('.snippet-item').last();
if ($lastItem.length) {
$lastItem.clone().appendTo(this.$target.find('.snippet-container'));
}
},
});
Include in manifest assets:
python
'assets': {
'website.assets_wysiwyg': [
'theme_<name>/static/src/js/snippets_options.js',
],
}
Trigger: User asks to "create snippet", "add custom snippet"
Workflow:
-
Detect Odoo Version (determines registration method)
-
For Odoo 17 and Earlier:
xml
<!-- Snippet Template -->
<template id="s_<snippet_name>" name="<Snippet Name>">
<section class="s_<snippet_name>" data-name="<Snippet Name>">
<div class="container">
<!-- Content here -->
</div>
</section>
</template>
<!-- Snippet Registration (Odoo 17) -->
<template id="s_<snippet_name>_insert" inherit_id="website.snippets">
<xpath expr="//div[@id='snippet_effect']//t[@t-snippet][last()]" position="after">
<t t-snippet="theme_<name>.s_<snippet_name>"
string="<Snippet Name>"
t-thumbnail="/theme_<name>/static/img/snippets/<snippet_name>.svg"/>
</xpath>
</template>
（后续内容因篇幅过长，翻译逻辑一致，保留代码块和专业术语，将说明文字译为中文即可）
Figma Integration Workflow
Command: Convert Figma Design to Odoo Theme
Trigger: User provides Figma URL or asks to "convert Figma to Odoo", "import Figma design"
Prerequisites: Figma MCP must be available
Workflow:
-
Use Figma MCP with Version-Specific Prompt
Convert this Figma design to HTML for Odoo <version> website theme with these requirements:
- Use Bootstrap v<bootstrap_version> classes (not Tailwind)
- Apply proper Odoo theme structure with sections and containers
- Include responsive classes (col-sm-*, col-md-*, col-lg-*)
- Use semantic HTML5 elements (header, nav, main, section, article)
- Add data attributes for Odoo website builder compatibility
- Map colors to CSS custom properties for theme variables
- Include accessibility attributes (aria-labels, alt text)
-
Extract Color Palette
Extract the color palette from this Figma design and map to CSS custom properties using the o-color-1 through o-color-5 naming convention for Odoo themes.
-
Convert HTML to QWeb Template
- Wrap in tags
- Add attribute
- Add data attributes for Odoo editor
- Convert to section-based structure
-
Generate SCSS from Figma Colors
python
python scripts/figma_converter.py <figma_url> <output_dir> <odoo_version>
-
Create Snippet from Figma Component
- Use converted HTML as snippet content
- Add proper Odoo structure
- Register snippet based on version (17 vs 18/19)
- Generate options if interactive
Figma MCP Prompts Reference
Basic HTML + Bootstrap:
Generate this Figma selection as HTML with Bootstrap v<version> classes instead of React and Tailwind. Use Odoo-compatible structure with proper semantic HTML5 elements.
Color Extraction:
Extract colors as CSS custom properties for Odoo theme
Typography Extraction:
Convert this Figma text styling to Bootstrap v<version> typography classes and CSS custom properties. Map font families to Google Fonts configuration for Odoo theme integration.
Layout Extraction:
Convert this Figma layout to Bootstrap v<version> grid system and utility classes. Use proper container, row, col-* structure with responsive breakpoints.
Chrome DevTools Integration Workflow
Command: Extract Styles from Live Website
Trigger: User provides website URL or asks to "extract from website", "copy styles from site"
Prerequisites: Chrome DevTools MCP must be available
Workflow:
-
Connect to DevTools MCP
- Open URL in Chrome DevTools MCP
- Select element(s) to extract
-
Extract Computed Styles
python
python scripts/devtools_extractor.py <url> <output_dir>
-
Convert to Odoo SCSS
- Map CSS properties to SCSS variables
- Convert colors to Odoo theme variables (o-color-*)
- Use Bootstrap variables where applicable
-
Map to Bootstrap Utilities
- Identify equivalent Bootstrap classes
- Replace custom CSS with utilities where possible
- Generate suggestions for class-based approach
-
Convert DOM to QWeb
- Extract HTML structure
- Add Odoo-specific attributes
- Wrap in proper template structure
- Add Bootstrap grid structure
-
Generate Complete Theme Code
- SCSS file with extracted styles
- QWeb template with structure
- Bootstrap class suggestions
- Snippet registration XML
Public Widget Pattern (publicWidget - REQUIRED for Themes)
IMPORTANT: For website themes, ALWAYS use publicWidget framework - NOT Owl or vanilla JS.
Use for: Website interactions, theme functionality, form handling, animations
Complete Structure with editableMode:
javascript
import publicWidget from "@web/legacy/js/public/public_widget";
publicWidget.registry.MyWidget = publicWidget.Widget.extend({
selector: '.my-selector',
disabledInEditableMode: false, // Allow in website builder
events: {
'click .button': '_onClick',
'change input': '_onChange',
'submit form': '_onSubmit',
},
start: function () {
// IMPORTANT: Only run animations/interactions in read mode
if (!this.editableMode) {
this._initializeAnimation();
this._bindExternalEvents();
}
return this._super.apply(this, arguments);
},
_initializeAnimation: function () {
// Animation code that should NOT run in edit mode
this.$el.addClass('animated');
},
_bindExternalEvents: function () {
$(window).on('scroll.myWidget', this._onScroll.bind(this));
$(window).on('resize.myWidget', this._onResize.bind(this));
},
_onClick: function (ev) {
ev.preventDefault();
// Don't run in edit mode
if (this.editableMode) return;
// Handler logic
},
_onScroll: function () {
// Throttle scroll events for performance
},
destroy: function () {
$(window).off('.myWidget'); // Remove namespaced events
this._super.apply(this, arguments);
},
});
export default publicWidget.registry.MyWidget;
Key publicWidget Points:
- ALWAYS check before running animations/interactions
- Use
disabledInEditableMode: false
- ALWAYS clean up event listeners in method
- NEVER use Owl or vanilla JS for website themes - publicWidget only
- Use namespaced events () for easy cleanup
Include in Manifest:
python
'assets': {
'web.assets_frontend': [
'module_name/static/src/js/my_widget.js',
],
}
Owl Component Pattern (Modern, Reactive)
Use for: Complex interactive UIs, reactive state management, component composition
Odoo 17 (Owl v1):
javascript
import { Component, useState } from "@odoo/owl";
import { registry } from "@web/core/registry";
class MyComponent extends Component {
setup() {
this.state = useState({
items: [],
loading: false,
});
}
async willStart() {
await this.loadData();
}
async loadData() {
this.state.loading = true;
// Fetch data via RPC
const data = await this.rpc('/my/route');
this.state.items = data.items;
this.state.loading = false;
}
onItemClick(item) {
console.log('Clicked:', item);
}
}
MyComponent.template = "module_name.MyComponentTemplate";
registry.category("public_components").add("MyComponent", MyComponent);
export default MyComponent;
Odoo 18/19 (Owl v2 - Note differences):
javascript
import { Component, useState } from "@odoo/owl";
class MyComponent extends Component {
static template = "module_name.MyComponentTemplate";
static props = {
// Define props with validation
title: { type: String, optional: true },
items: { type: Array },
};
setup() {
this.state = useState({
selectedId: null,
});
}
// Owl v2 uses static template property
}
export default MyComponent;
XML Template:
xml
<template id="MyComponentTemplate" name="My Component">
<div class="my-component">
<h3 t-if="props.title"><t t-esc="props.title"/></h3>
<ul>
<li t-foreach="props.items" t-as="item" t-key="item.id">
<t t-esc="item.name"/>
</li>
</ul>
</div>
</template>
Translation (_t) Best Practices
CRITICAL RULE: Use
at
DEFINITION TIME for static labels in JavaScript arrays/constants, NOT via runtime wrapper methods. Static strings in XML templates are automatically translated by Odoo.
Why?
- Static strings in XML templates ( files) are automatically extracted by Odoo's translation system
- Using in templates for static strings duplicates translation entries and adds unnecessary overhead
- MUST wrap strings at definition time in JS so Odoo's PO extractor can find them
- Runtime wrapper methods (like ) do NOT work - the strings are never found by the extractor
CORRECT - Wrap static labels with AT DEFINITION TIME:
javascript
import { _t } from "@web/core/l10n/translation";
// ✅ CORRECT: Wrap each string with _t() at definition time
const MONTHS = [
{value: 1, short: _t("Jan"), full: _t("January")},
{value: 2, short: _t("Feb"), full: _t("February")},
{value: 3, short: _t("Mar"), full: _t("March")},
{value: 4, short: _t("Apr"), full: _t("April")},
{value: 5, short: _t("May"), full: _t("May")},
{value: 6, short: _t("Jun"), full: _t("June")},
{value: 7, short: _t("Jul"), full: _t("July")},
{value: 8, short: _t("Aug"), full: _t("August")},
{value: 9, short: _t("Sep"), full: _t("September")},
{value: 10, short: _t("Oct"), full: _t("October")},
{value: 11, short: _t("Nov"), full: _t("November")},
{value: 12, short: _t("Dec"), full: _t("December")},
];
// ✅ CORRECT: Status labels wrapped at definition
const STATUS_LABELS = {
draft: _t("Draft"),
pending: _t("Pending"),
approved: _t("Approved"),
rejected: _t("Rejected"),
};
export class DatePicker extends Component {
setup() {
this.months = MONTHS; // Already translated at definition
}
get displayLabel() {
const month = this.months.find(m => m.value === this.selectedMonth);
// No translateLabel() needed - values are already translated
return `${month?.short || ""} ${this.selectedYear}`;
}
}
WRONG - Runtime wrapper methods don't work:
javascript
// ❌ WRONG: Strings without _t() at definition will NOT be translated
const MONTHS = [
{value: 1, label: "Jan", full: "January"}, // NOT FOUND by PO extractor!
{value: 2, label: "Feb", full: "February"},
];
// ❌ WRONG: This pattern does NOT work for translation
translateLabel(key) {
return _t(key); // key is a variable, not a literal - PO extractor can't find it!
}
CORRECT - Template using pre-translated values:
xml
<!-- Month values come from JS MONTHS array - already translated at definition -->
<t t-foreach="getAvailableMonths()" t-as="month" t-key="month.value">
<a href="#" t-on-click.prevent="() => this.selectMonth(month.value)">
<!-- No wrapper needed - month.full is already translated -->
<t t-esc="month.full"/>
</a>
</t>
CORRECT - Static XML strings need NO wrapper:
xml
<!-- Static strings in XML are auto-translated by Odoo -->
<span>No data available</span>
<a href="#">Live</a>
<button type="submit">Submit</button>
When to use at DEFINITION TIME:
- ✅ Static labels in JavaScript arrays (month names, day names, status labels)
- ✅ Static labels in JavaScript objects/constants
- ✅ Error messages defined as constants
- ✅ Any string literal that will be displayed to users from JS
- ❌ Static text directly in XML templates (auto-translated)
- ❌ Runtime wrapper methods like (doesn't work!)
- ❌ Dynamic variables passed to at runtime
- ❌ Any hardcoded string in files
REMEMBER: If you define a string in JavaScript that will be shown to users, wrap it with
where it's defined, not where it's used.
SCSS and Bootstrap Customization
Primary Variables Override
File:
static/src/scss/primary_variables.scss
Purpose: Override Odoo's built-in style variables (colors, fonts, spacing)
Include in:
web._assets_primary_variables
bundle
Structure:
scss
// ============================================================
// Theme Primary Variables
// Override Odoo defaults with !default to allow further overriding
// ============================================================
// Color Palette
$o-color-1: #3498db !default; // Primary
$o-color-2: #2ecc71 !default; // Success
$o-color-3: #e74c3c !default; // Danger
$o-color-4: #f39c12 !default; // Warning
$o-color-5: #9b59b6 !default; // Info
// Website Values Palette Configuration
$o-website-values-palettes: (
(
// Color Configuration
'color-palettes-name': 'my-theme',
// Typography
'font': 'Inter',
'headings-font': 'Inter',
'navbar-font': 'Inter',
'buttons-font': 'Inter',
'headings-line-height': 1.2,
// Header & Navigation
'header-template': 'default', // or 'centered', 'boxed'
'header-font-size': 1rem,
'logo-height': 3rem,
'fixed-logo-height': 2rem,
'hamburger-position': 'right', // Mobile menu
// Buttons
'btn-padding-y': 0.45rem,
'btn-padding-x': 1.35rem,
'btn-padding-y-sm': 0.3rem,
'btn-padding-x-sm': 0.9rem,
'btn-padding-y-lg': 0.6rem,
'btn-padding-x-lg': 1.8rem,
'btn-border-radius': 0.25rem,
'btn-border-width': 1px,
'btn-font-size': 1rem,
// Input Fields
'input-padding-y': 0.45rem,
'input-border-radius': 0.25rem,
// Colors (map to palette)
'color-1': $o-color-1,
'color-2': $o-color-2,
'color-3': $o-color-3,
'color-4': $o-color-4,
'color-5': $o-color-5,
)
);
// Google Fonts Configuration (STANDALONE - no map-merge!)
$o-theme-font-configs: (
'Inter': (
'family': ('Inter', sans-serif),
'url': 'Inter:wght@300;400;500;600;700',
),
);
⚠️ NEVER use these patterns in themes:
scss
// ❌ WRONG - Will cause "Undefined variable" errors
$o-color-palettes: map-merge($o-color-palettes, (...));
$o-theme-color-palettes: map-merge($o-theme-color-palettes, (...));
$o-theme-font-configs: map-merge($o-theme-font-configs, (...));
File:
static/src/scss/bootstrap_overridden.scss
Purpose: Override Bootstrap variables that Odoo hasn't exposed
Include in:
web._assets_frontend_helpers
bundle
Structure:
scss
// ============================================================
// Bootstrap Variable Overrides
// Only override Bootstrap vars not available in Odoo variables
// ============================================================
@import "~bootstrap/scss/functions";
@import "~bootstrap/scss/variables";
// Spacing
$spacer: 1rem !default;
// Grid breakpoints
$grid-breakpoints: (
xs: 0,
sm: 576px,
md: 768px,
lg: 992px,
xl: 1200px,
xxl: 1400px
) !default;
// Container max widths
$container-max-widths: (
sm: 540px,
md: 720px,
lg: 960px,
xl: 1140px,
xxl: 1320px
) !default;
// Typography
$font-size-base: 1rem !default;
$line-height-base: 1.5 !default;
// Border radius
$border-radius: 0.25rem !default;
$border-radius-sm: 0.125rem !default;
$border-radius-lg: 0.5rem !default;
// Shadows
$box-shadow-sm: 0 .125rem .25rem rgba(0, 0, 0, .075) !default;
$box-shadow: 0 .5rem 1rem rgba(0, 0, 0, .15) !default;
$box-shadow-lg: 0 1rem 3rem rgba(0, 0, 0, .175) !default;
Version-Specific Considerations
-
Owl v1
- Use from
- Legacy import paths
- Component template as separate property
-
Snippet Structure
- Simple insertion without groups
- Use XPath targeting
//div[@id='snippet_effect']
-
Public Widgets
- Import from
@web/legacy/js/public/public_widget
- jQuery fully available
-
Owl v2
- Static template property
- Props validation required
- New reactive hooks
- Breaking changes from v1
-
Snippet Groups
- Required attribute
- Organized in categories
- XPath targets
//div[@id='snippet_structure']
-
Bootstrap 5.1.3
- All use same Bootstrap version
- Consistent utility classes
-
Website Builder Enhancements
- Theme browsing in editor
- Custom font upload via UI
- Enhanced snippet options
Bootstrap 4 to 5 Migration (Odoo 14/15 → 16+)
When migrating themes:
-
Class Replacements:
python
python scripts/bootstrap_mapper.py <old_classes>
Common replacements:
- → (margin-left → margin-start)
- → (margin-right → margin-end)
- → (padding-left → padding-start)
- → (padding-right → padding-end)
- →
- →
- →
- →
- →
- →
- →
- → (e.g., → )
- →
- →
- →
-
Removed Classes (find alternatives):
- - Use grid/flex utilities
- - Recreate with utilities
- - Use with flex utilities
-
jQuery Removal:
- Bootstrap 5 uses vanilla JavaScript
- May need to adjust widget initialization
Frontend Performance Best Practices
-
Asset Bundling
- Always use Odoo's asset bundles
- Don't link external files individually
- Leverage minification (enabled in production)
-
Lazy Loading
- Use on images
- Leverage Odoo's route for auto-resizing
- Lazy load videos (Odoo 18+ has built-in support)
-
Optimize Snippets
- Batch server calls (one RPC for all data)
- Use QWeb for efficient rendering
- Minimize DOM manipulation
-
CSS Optimization
- Use Bootstrap utilities instead of custom CSS
- Keep HTML structure lean
- Remove unused CSS/JS from bundles
-
Caching
- Utilize computed fields with
- Cache expensive computations
- Do heavy work server-side
-
SEO Considerations
- Server-render critical content
- Use Owl for enhancements, not primary content
- Ensure fast load times
Security & Access Control
Always create
security/ir.model.access.csv
:
csv
id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink
access_model_user,model.user,model_model_name,base.group_user,1,1,1,0
access_model_public,model.public,model_model_name,,1,0,0,0
Create
for fine-grained control:
xml
<record id="model_rule" model="ir.rule">
<field name="name">Model: User own records</field>
<field name="model_id" ref="model_model_name"/>
<field name="domain_force">[('user_id', '=', user.id)]</field>
<field name="groups" eval="[(4, ref('base.group_user'))]"/>
</record>
python
from odoo import http
class MyController(http.Controller):
@http.route('/public/route', auth='public') # No login required
def public_route(self):
pass
@http.route('/user/route', auth='user') # Login required
def user_route(self):
pass
records = request.env['model'].sudo().search([('published', '=', True)])
if not request.env['model'].check_access_rights('read', raise_exception=False):
return request.redirect('/access-denied')
Create Complete Theme from Figma
- User provides Figma URL
- Detect target Odoo version
- Use Figma MCP to extract design
- Generate theme module structure
- Convert colors to SCSS variables
- Convert components to snippets
- Create snippet options
- Test in Odoo Website Builder
- Detect current theme and version
- Analyze existing structure
- Create inheriting module
- Override specific templates
- Add custom snippets
- Extend SCSS variables
Migrate Theme Across Versions
- Detect source and target versions
- Convert Bootstrap classes (if 4→5)
- Update snippet structure (if 17→18/19)
- Update JavaScript (if Owl v1→v2)
- Test all functionality
- Generate migration report
python -m odoo -c conf/<config>.conf -d <db> -i theme_<name> --stop-after-init
Snippet Registration Test
- Install theme
- Go to Website → Edit
- Check snippets panel
- Verify snippet appears in correct category
- Test drag-and-drop
- Test snippet options
- Test in multiple browsers (Chrome, Firefox, Safari, Edge)
- Test responsive breakpoints (sm, md, lg, xl, xxl)
- Validate accessibility (ARIA labels, keyboard navigation)
- Check performance (Lighthouse, Page Speed)
⚠️ SCSS Compilation Errors (CRITICAL)
Issue: "Undefined variable: $o-color-palettes" or "$o-theme-font-configs"
Cause: Using
with core Odoo variables in theme SCSS. Theme files load BEFORE core variables are defined.
Solution:
- Remove ALL calls with core variables
- Define as standalone (no merge)
- Use
'color-palettes-name': 'default-1'
- See "CRITICAL: SCSS Load Order" section above
Issue: CSS showing 0 rules / Styles not loading
Cause: Silent SCSS compilation failure due to undefined variables.
Diagnosis:
javascript
// In browser console
document.styleSheets[0].cssRules.length // Should be > 0
// If 0, SCSS compilation failed silently
Solution:
- Check browser console for "Style compilation failed" errors
- Fix undefined variable errors (see above)
- Clear asset cache:
self.env['ir.attachment'].search([('url', 'like', '/web/assets/')]).unlink()
self.env.cr.commit()
**Issue: Malformed Google Fonts URL**
**Cause:** Using `ir.asset` records for external font URLs causes URL duplication.
**Solution:** Use `$o-theme-font-configs` in SCSS instead of `ir.asset` XML records.
Causes:
- Incorrect XPath (version mismatch)
- Missing group attribute (Odoo 18/19)
- Template not found
- Syntax error in XML
Solutions:
- Check Odoo version and use correct insertion method
- Verify template ID exists
- Check XML syntax
- Look for errors in log
Causes:
- SCSS not included in correct bundle
- Variable override not using
- CSS specificity issues
- Asset not compiled
- SCSS compilation failed silently (check console!)
Solutions:
- Verify asset bundle in manifest
- Clear browser cache
- Check asset regeneration:
odoo-bin --update theme_<name>
- Use browser DevTools to inspect computed styles
- Check console for SCSS errors first!
Causes:
- Import path incorrect for Odoo version
- Widget not registered
- jQuery conflicts (Bootstrap 5)
- Owl version mismatch
Solutions:
- Check import paths for Odoo version
- Verify widget/component registration
- Check console for errors
- Ensure correct Owl version usage
XPath Errors in Header/Footer Templates
Cause: Complex XPath expressions like
may not match Odoo's actual HTML structure.
Solution: Use simple XPath expressions:
xml
<!-- ✅ CORRECT: Simple XPath -->
<xpath expr="//header" position="attributes">
<!-- ❌ WRONG: Complex XPath may not match -->
<xpath expr="//header//nav" position="attributes">
-
Always Use Version Detection First
- Don't assume Odoo version
- Check before generating any code
-
Prefer Bootstrap Utilities
- Less custom CSS = easier maintenance
- Better performance
- Editor-compatible
-
Server-Side Rendering for SEO
- Don't rely on client-side JS for content
- Use Owl for enhancements only
-
Test in Edit Mode
- Ensure Website Builder can handle your code
- Test snippet options thoroughly
-
Follow Odoo Patterns
- Study core themes ()
- Match existing conventions
- Use same class prefixes (, )
-
Documentation
- Comment complex SCSS
- Document snippet options
- Provide README for theme
Progressive Web App (PWA) Implementation
Command: Setup PWA for Odoo Website
Trigger: User asks to "make PWA", "add offline support", "enable push notifications"
Workflow:
-
Generate Service Worker
javascript
// static/src/service-worker.js
const CACHE_NAME = 'odoo-pwa-v1';
const urlsToCache = ['/', '/web/static/lib/owl/owl.js'];
self.addEventListener('install', event => {
event.waitUntil(
caches.open(CACHE_NAME)
.then(cache => cache.addAll(urlsToCache))
);
});
self.addEventListener('fetch', event => {
event.respondWith(
caches.match(event.request)
.then(response => response || fetch(event.request))
);
});
-
Create Web App Manifest
json
{
"name": "Odoo PWA",
"short_name": "OdooPWA",
"start_url": "/",
"display": "standalone",
"background_color": "#875A7B",
"theme_color": "#875A7B",
"icons": [...]
}
-
Register Service Worker
javascript
import publicWidget from "@web/legacy/js/public/public_widget";
publicWidget.registry.ServiceWorkerRegistration = publicWidget.Widget.extend({
selector: 'body',
start: function() {
if ('serviceWorker' in navigator) {
navigator.serviceWorker.register('/service-worker.js');
}
return this._super(...arguments);
}
});
Modern JavaScript & TypeScript
Command: Setup TypeScript
Trigger: User asks to "use TypeScript", "add type safety", "configure TypeScript"
Workflow:
-
Generate tsconfig.json
json
{
"compilerOptions": {
"target": "ES2020",
"module": "ES2020",
"lib": ["ES2020", "DOM"],
"strict": true,
"paths": {
"@web/*": ["./addons/web/static/src/*"],
"@owl/*": ["./addons/web/static/lib/owl/*"]
}
}
}
-
Create Typed Owl Component
typescript
import { Component, useState } from "@odoo/owl";
interface ProductProps {
id: number;
name: string;
price: number;
}
export class ProductComponent extends Component<ProductProps> {
static template = xml`...`;
setup() {
this.state = useState({ loading: false });
}
}
Use modern JavaScript features:
javascript
// Optional chaining
const userName = this.props.user?.profile?.name;
// Nullish coalescing
const displayName = userName ?? 'Guest User';
// Dynamic imports
const module = await import('./HeavyFeatureComponent');
// Private class fields
class SecureWidget {
#apiKey = null;
#generateKey() {
return crypto.randomUUID();
}
}
Trigger: User asks to "add tests", "setup Jest", "configure Cypress"
Workflow:
-
Jest Configuration
javascript
// jest.config.js
module.exports = {
testEnvironment: 'jsdom',
moduleNameMapper: {
'^@web/(.*)$': '<rootDir>/addons/web/static/src/$1',
},
collectCoverageFrom: ['static/src/**/*.{js,jsx}']
};
-
Cypress E2E Tests
javascript
// cypress/e2e/ecommerce.cy.js
describe('E-commerce Flow', () => {
it('should complete purchase', () => {
cy.visit('/shop');
cy.get('[data-product-id="1"]').click();
cy.get('#add_to_cart').click();
cy.get('.btn-primary').contains('Checkout').click();
});
});
-
Visual Regression Testing
javascript
// backstop.config.js
module.exports = {
scenarios: [{
label: 'Homepage',
url: 'http://localhost:8069',
misMatchThreshold: 0.1
}]
};
Command: Optimize Core Web Vitals
Trigger: User asks to "improve performance", "optimize LCP/FID/CLS", "speed up website"
Workflow:
-
Optimize Largest Contentful Paint (LCP)
javascript
// Preload critical resources
const link = document.createElement('link');
link.rel = 'preload';
link.as = 'image';
link.href = '/web/image/website/1/logo';
document.head.appendChild(link);
-
Reduce First Input Delay (FID)
javascript
// Break up long tasks
function optimizeLongTask(items) {
const chunks = [];
for (let i = 0; i < items.length; i += 100) {
chunks.push(items.slice(i, i + 100));
}
chunks.forEach(chunk => {
requestIdleCallback(() => processChunk(chunk));
});
}
-
Minimize Cumulative Layout Shift (CLS)
css
/* Reserve space for dynamic content */
.product-image-container {
aspect-ratio: 1/1;
contain: layout;
}
Accessibility (WCAG Compliance)
Command: Implement Accessibility
Trigger: User asks to "add ARIA", "make accessible", "WCAG compliance"
Workflow:
-
ARIA Implementation
xml
<form role="form" aria-label="Contact Form">
<input type="email"
aria-labelledby="email-label"
aria-describedby="email-error"
aria-required="true"
aria-invalid="false"/>
<span id="email-error" role="alert" aria-live="polite"></span>
</form>
-
Keyboard Navigation
javascript
class KeyboardNavigationManager {
handleTab(event) {
if (event.shiftKey) {
// Backward navigation
} else {
// Forward navigation
}
}
trapFocus() {
// Trap focus within modal
}
}
-
Screen Reader Support
javascript
class ScreenReaderAnnouncer {
announce(message, priority = 'polite') {
this.liveRegion.setAttribute('aria-live', priority);
this.liveRegion.textContent = message;
}
}
Command: Add WebSocket Support
Trigger: User asks to "add real-time", "implement WebSocket", "live updates"
Workflow:
-
WebSocket Manager
javascript
export class WebSocketManager {
constructor(url) {
this.socket = new WebSocket(url);
this.setupEventHandlers();
}
setupEventHandlers() {
this.socket.onmessage = (event) => {
const data = JSON.parse(event.data);
this.handleMessage(data);
};
}
send(data) {
if (this.socket.readyState === WebSocket.OPEN) {
this.socket.send(JSON.stringify(data));
}
}
}
-
Server-Sent Events (SSE)
javascript
class SSEManager {
constructor(url) {
this.eventSource = new EventSource(url);
this.eventSource.onmessage = (event) => {
this.handleMessage(event.data);
};
}
}
Command: Create Web Component
Trigger: User asks to "create web component", "custom element"
Workflow:
javascript
export class OdooSearchInput extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: 'open' });
}
static get observedAttributes() {
return ['placeholder', 'value'];
}
connectedCallback() {
this.render();
}
render() {
this.shadowRoot.innerHTML = `
<style>
:host { display: block; }
input { width: 100%; padding: 0.5rem; }
</style>
<input type="text" placeholder="${this.getAttribute('placeholder')}"/>
`;
}
}
customElements.define('odoo-search-input', OdooSearchInput);
Command: Create guided tour
javascript
import tour from 'web_tour.tour';
tour.register('product_tour', {
url: '/shop',
}, [{
content: 'Click on any product',
trigger: '.oe_product:first',
position: 'bottom',
}]);
javascript
import { registry } from "@web/core/registry";
import { Component } from "@odoo/owl";
export class ColorPickerField extends Component {
static template = xml`
<input type="color" t-att-value="props.value" t-on-change="onChange"/>
`;
onChange(event) {
this.props.update(event.target.value);
}
}
registry.category("fields").add("color_picker", ColorPickerField);
javascript
import { registry } from "@web/core/registry";
import { Component, useState } from "@odoo/owl";
export class NotificationBell extends Component {
static template = xml`...`;
setup() {
this.state = useState({ notifications: [] });
}
}
registry.category("systray").add("NotificationBell", {
Component: NotificationBell,
});
Command: Setup Vite build
javascript
// vite.config.js
import { defineConfig } from 'vite';
export default defineConfig({
base: '/web/static/',
build: {
rollupOptions: {
input: {
main: 'static/src/main.js',
website: 'static/src/website.js'
}
}
},
server: {
proxy: {
'/web': 'http://localhost:8069'
}
}
});
.github/workflows/odoo-frontend.yml
name: Odoo Frontend CI/CD
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run tests
run: |
npm run test:unit
npm run test:e2e
- name: Build assets
run: npm run build
Theme Feature Activation System (CRITICAL)
Overview: The theme.utils Model
When creating a theme, you MUST include a
models/theme_xxx.py file that implements the
pattern. This allows your theme to:
- Enable/disable header templates
- Enable/disable footer templates
- Activate optional features on theme installation
- Configure the theme's default appearance
theme_yourtheme/
├── __init__.py # Must import models
├── __manifest__.py
├── models/
│ ├── __init__.py # Must import theme_yourtheme
│ └── theme_yourtheme.py # theme.utils implementation (REQUIRED!)
├── data/
├── views/
└── static/
python
from . import theme_yourtheme
models/theme_yourtheme.py (REQUIRED PATTERN)
python
from odoo import models
class ThemeYourTheme(models.AbstractModel):
_inherit = 'theme.utils'
def _theme_yourtheme_post_copy(self, mod):
"""
Called automatically when theme is installed on a website.
Use enable_view() and disable_view() to configure templates.
IMPORTANT: Method name MUST be _theme_{technical_name}_post_copy
where technical_name matches folder name (underscores, not hyphens).
"""
# Enable desired header template (mutual exclusivity enforced)
self.enable_view('website.template_header_sales_two')
# Enable desired footer template (mutual exclusivity enforced)
self.enable_view('website.template_footer_contact')
# Enable optional features
self.enable_view('website.option_header_brand_logo')
# Disable unwanted defaults
self.disable_view('website.header_visibility_standard')
self.enable_view('website.header_visibility_fixed')
| Method | Purpose | Example |
|---|
| Activate a template | self.enable_view('website.template_header_hamburger')
|
| Deactivate a template | self.disable_view('website.template_header_default')
|
| Activate an asset bundle | self.enable_asset('website.theme_custom_assets')
|
| Deactivate an asset bundle | self.disable_asset('website.theme_old_assets')
|
Headers: Only ONE primary header template can be active at a time. When you
a header, Odoo automatically handles deactivating others.
Footers: Only ONE primary footer template can be active at a time. Same automatic handling.
Header Options: Alignment variants, visibility effects, and components can be combined with the active header.
Complete Example: Modern Business Theme
python
from odoo import models
class ThemeModernBusiness(models.AbstractModel):
_inherit = 'theme.utils'
def _theme_modern_business_post_copy(self, mod):
"""Configure Modern Business theme defaults."""
# === HEADER CONFIGURATION ===
# Use hamburger header with centered mobile
self.enable_view('website.template_header_hamburger')
self.enable_view('website.template_header_hamburger_mobile_align_center')
# Fixed header that disappears on scroll
self.disable_view('website.header_visibility_standard')
self.enable_view('website.header_visibility_disappears')
# Show logo, not brand name
self.enable_view('website.option_header_brand_logo')
self.disable_view('website.option_header_brand_name')
# === FOOTER CONFIGURATION ===
# Use contact footer with call-to-action style
self.enable_view('website.template_footer_contact')
# Enable scroll-to-top button
# (This is configured in $o-website-values-palettes, not via views)
# === OPTIONAL FEATURES ===
# Enable search in header
self.enable_view('website.header_search_box')
# Enable social links
self.enable_view('website.header_social_links')
Complete Dynamic Page Reference
This section documents ALL available templates in Odoo for dynamic pages. Use this reference when:
- Comparing a Figma design to find the closest Odoo template
- Configuring theme defaults via
- Understanding what features Odoo provides out-of-the-box
📋 HEADER TEMPLATES (11 Primary + Variants)
All headers inherit from
. Only ONE primary header can be active per website.
| XML ID | Name | Description | Best For |
|---|
website.template_header_default
| Default | Standard horizontal navbar | Most websites |
website.template_header_hamburger
| Hamburger | Collapsed hamburger menu | Minimal designs |
website.template_header_stretch
| Stretch | Full-width stretched navbar | Wide layouts |
website.template_header_vertical
| Vertical | Vertical sidebar navigation | App-like sites |
website.template_header_search
| Search | Header with prominent search | E-commerce, directories |
website.template_header_sales_one
| Sales 1 | E-commerce focused header | Online stores |
website.template_header_sales_two
| Sales 2 | E-commerce with categories | Large catalogs |
website.template_header_sales_three
| Sales 3 | E-commerce alternate | Product-focused |
website.template_header_sales_four
| Sales 4 | E-commerce variant | Fashion, retail |
website.template_header_sidebar
| Sidebar | Full sidebar layout | Dashboard sites |
website.template_header_boxed
| Boxed | Rounded box container | Modern brands |
Header Alignment Variants (per header)
Each header supports alignment variants. Example for Default header:
website.template_header_default
website.template_header_default_align_center
website.template_header_default_align_right
Mobile variants (append
or
):
website.template_header_hamburger_mobile_align_center
website.template_header_hamburger_mobile_align_right
Header Visibility Effects (mutually exclusive)
| XML ID | Effect | Description |
|---|
website.header_visibility_standard
| Standard | Always visible, scrolls with page |
website.header_visibility_fixed
| Fixed | Sticks to top on scroll |
website.header_visibility_disappears
| Disappears | Hides on scroll down, shows on scroll up |
website.header_visibility_fade_out
| Fade Out | Fades out on scroll |
Header Components (can be combined)
| XML ID | Component | Default |
|---|
website.option_header_brand_logo
| Show logo image | Active |
website.option_header_brand_name
| Show text "My Website" | Inactive |
website.header_call_to_action
| CTA button (Contact Us) | Active |
website.header_search_box
| Search bar | Active |
website.header_social_links
| Social media icons | Inactive |
website.header_text_element
| Custom text element | Active |
website.header_language_selector
| Language dropdown | Active |
┌─────────────────────────────────────────────────────────────────┐
│ DEFAULT HEADER │
│ ┌────────┬────────────────────────────────┬───────────────────┐ │
│ │ LOGO │ Home About Services Blog │ Search CTA BTN │ │
│ └────────┴────────────────────────────────┴───────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ HAMBURGER HEADER │
│ ┌────────┬───────────────────────────────┬────────────────────┐ │
│ │ ☰ MENU │ LOGO │ Search CTA │ │
│ └────────┴───────────────────────────────┴────────────────────┘ │
│ ↓ (expanded menu) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Home │ About │ Services │ Blog │ Contact │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ SALES TWO HEADER (E-commerce) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Top bar: Phone | Email | Currency | Language │ │
│ ├─────────────────────────────────────────────────────────────┤ │
│ │ LOGO [ Search Bar ] Account Cart 🛒 │ │
│ ├─────────────────────────────────────────────────────────────┤ │
│ │ Category 1 │ Category 2 │ Category 3 │ All Products │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────┐
│ VERTICAL/SIDEBAR HEADER │
│ ┌──────────────┬──────────────────────────────────────────────┐│
│ │ │ ││
│ │ LOGO │ ││
│ │ │ ││
│ │ ─────────── │ PAGE CONTENT ││
│ │ │ ││
│ │ Home │ ││
│ │ About │ ││
│ │ Services │ ││
│ │ Blog │ ││
│ │ Contact │ ││
│ │ │ ││
│ │ ─────────── │ ││
│ │ [Social] │ ││
│ └──────────────┴──────────────────────────────────────────────┘│
└────────────────────────────────────────────────────────────────┘
📋 FOOTER TEMPLATES (9 Options)
All footers inherit from
. Only ONE primary footer can be active per website.
| XML ID | Name | Description | Best For |
|---|
| Default | Customizable default footer | General use |
website.template_footer_descriptive
| Descriptive | Detailed company description | Corporate sites |
website.template_footer_centered
| Centered | Center-aligned minimal | Landing pages |
website.template_footer_links
| Links | Multiple link columns | Large sites |
website.template_footer_minimalist
| Minimalist | Ultra-minimal footer | Clean designs |
website.template_footer_contact
| Contact | Contact info focused | Service businesses |
website.template_footer_call_to_action
| CTA | Newsletter/action focused | Marketing sites |
website.template_footer_headline
| Headline | Large headline text | Brand statements |
website.template_footer_slideout
| Slideout | Slides out on scroll | Modern/trendy |
| XML ID | Option | Description |
|---|
website.footer_no_copyright
| Remove copyright | Hides copyright line |
website.footer_language_selector_inline
| Inline language | Language selector style |
┌─────────────────────────────────────────────────────────────────┐
│ DEFAULT FOOTER │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ LOGO │ │
│ │ Company description text here... │ │
│ │ │ │
│ │ Links Services Contact │ │
│ │ · About · Web Dev 123 Street │ │
│ │ · Blog · Design City, Country │ │
│ │ · Careers · Support +1 234 567 890 │ │
│ │ │ │
│ │ [Social Icons] │ │
│ ├─────────────────────────────────────────────────────────────┤ │
│ │ © 2024 Company Name. All rights reserved. │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ MINIMALIST FOOTER │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ © 2024 Company · Privacy · Terms │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ CONTACT FOOTER │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ┌──────────────┬───────────────┬────────────────────────┐ │ │
│ │ │ 📍 Address │ 📞 Phone │ ✉️ Email │ │ │
│ │ │ 123 Street │ +1 234 567 │ hello@company.com │ │ │
│ │ │ City │ │ │ │ │
│ │ └──────────────┴───────────────┴────────────────────────┘ │ │
│ │ [Social Icons] │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ CALL-TO-ACTION FOOTER │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Subscribe to our newsletter │ │
│ │ ┌─────────────────────────────────┬─────────────────────┐ │ │
│ │ │ Enter your email... │ [Subscribe Now] │ │ │
│ │ └─────────────────────────────────┴─────────────────────┘ │ │
│ │ │ │
│ │ © 2024 Company · [Social Icons] │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
📋 SHOP PAGE TEMPLATES (website_sale module)
| XML ID | Feature | Default | Description |
|---|
website_sale.products_design_card
| Card design | Inactive | Card-style product items |
website_sale.products_design_thumbs
| Thumbnails | Inactive | Thumbnail layout |
website_sale.products_design_grid
| Grid design | Inactive | Grid layout |
website_sale.products_thumb_4_3
| 4:3 ratio | Inactive | 4:3 image aspect ratio |
website_sale.products_thumb_4_5
| 4:5 ratio | Inactive | 4:5 image aspect ratio |
website_sale.products_thumb_2_3
| 2:3 ratio | Inactive | 2:3 image aspect ratio |
website_sale.products_thumb_cover
| Cover fill | Active | Image fills container |
Shop Categories & Filters
| XML ID | Feature | Default | Description |
|---|
website_sale.products_categories
| Left sidebar categories | Inactive | Categories in left sidebar |
website_sale.products_categories_top
| Top categories | Active | Categories in top nav |
website_sale.products_attributes
| Attribute filters | Active | Product attribute filters |
website_sale.filter_products_price
| Price filter | Inactive | Price range slider |
website_sale.filter_products_tags
| Tags filter | Active | Filter by product tags |
| Search box | Active | Product search |
| Sort dropdown | Active | Sort products |
website_sale.add_grid_or_list_option
| Grid/List toggle | Active | View toggle button |
| XML ID | Feature | Default | Description |
|---|
website_sale.products_description
| Description | Inactive | Show description in listing |
website_sale.products_add_to_cart
| Add to Cart | Inactive | Add to cart button in listing |
┌─────────────────────────────────────────────────────────────────┐
│ SHOP PAGE (Categories Top - Default) │
├─────────────────────────────────────────────────────────────────┤
│ All │ Category 1 │ Category 2 │ Category 3 │
├─────────────────────────────────────────────────────────────────┤
│ [Search...] [Sort: Featured ▼] [☷ Grid] [☰ List] │
├─────────────────────────────────────────────────────────────────┤
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ [IMG] │ │ [IMG] │ │ [IMG] │ │ [IMG] │ │
│ │ │ │ │ │ │ │ │ │
│ │ Product 1│ │ Product 2│ │ Product 3│ │ Product 4│ │
│ │ $99.00 │ │ $149.00 │ │ $79.00 │ │ $199.00 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ [IMG] │ │ [IMG] │ │ [IMG] │ │ [IMG] │ │
│ │ ... │ │ ... │ │ ... │ │ ... │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ [1] [2] [3] ... [Next →] │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ SHOP PAGE (Categories Left Sidebar) │
├────────────────┬────────────────────────────────────────────────┤
│ CATEGORIES │ [Search...] [Sort ▼] [☷] [☰] │
│ ───────────── ├────────────────────────────────────────────────┤
│ □ All │ ┌────────┐ ┌────────┐ ┌────────┐ │
│ ▸ Category 1 │ │ [IMG] │ │ [IMG] │ │ [IMG] │ │
│ · Sub 1.1 │ │ Prod 1 │ │ Prod 2 │ │ Prod 3 │ │
│ · Sub 1.2 │ │ $99 │ │ $149 │ │ $79 │ │
│ ▸ Category 2 │ └────────┘ └────────┘ └────────┘ │
│ ▸ Category 3 │ │
│ │ ┌────────┐ ┌────────┐ ┌────────┐ │
│ PRICE │ │ ... │ │ ... │ │ ... │ │
│ ───────────── │ └────────┘ └────────┘ └────────┘ │
│ $0 ─●────── $500│ │
│ │ │
│ TAGS │ │
│ ───────────── │ │
│ [New] [Sale] │ │
└────────────────┴────────────────────────────────────────────────┘
📋 PRODUCT DETAIL PAGE TEMPLATES
| XML ID | Feature | Default | Description |
|---|
website_sale.product_tags
| Product tags | Active | Display product tags |
website_sale.product_comment
| Reviews | Inactive | Discussion/rating section |
website_sale.product_custom_text
| Terms block | Active | Terms & conditions |
website_sale.product_share_buttons
| Share buttons | Active | Social share buttons |
website_sale.product_quantity
| Quantity selector | Active | Qty input field |
website_sale.product_buy_now
| Buy Now | Inactive | Quick buy button |
website_sale.product_variants
| Variants list | Inactive | List view of variants |
website_sale.alternative_products
| Alternatives | Active | Alternative products carousel |
website_sale.carousel_product_indicators_bottom
| Carousel bottom | Active | Image indicators at bottom |
website_sale.carousel_product_indicators_left
| Carousel left | Inactive | Image indicators on left |
Product Page Visual Reference
┌─────────────────────────────────────────────────────────────────┐
│ PRODUCT DETAIL PAGE │
├─────────────────────────────────────────────────────────────────┤
│ Home > Category > Product Name │
├───────────────────────────────┬─────────────────────────────────┤
│ │ │
│ ┌─────────────────────────┐ │ Product Name │
│ │ │ │ ★★★★☆ (24 reviews) │
│ │ [MAIN IMAGE] │ │ │
│ │ │ │ $199.00 │
│ │ │ │ ̶$̶2̶4̶9̶.̶0̶0̶ -20% │
│ └─────────────────────────┘ │ │
│ [○] [○] [●] [○] │ Color: [Blue ▼] │
│ │ Size: [M ▼] │
│ ┌──────┐ ┌──────┐ ┌──────┐ │ │
│ │thumb1│ │thumb2│ │thumb3│ │ Qty: [- 1 +] │
│ └──────┘ └──────┘ └──────┘ │ │
│ │ [Add to Cart] [Buy Now] │
│ │ │
│ │ [♡ Wishlist] [🔗 Share] │
│ │ │
│ │ Tags: [New] [Bestseller] │
├───────────────────────────────┴─────────────────────────────────┤
│ DESCRIPTION │ SPECIFICATIONS │ REVIEWS (24) │
├─────────────────────────────────────────────────────────────────┤
│ Full product description text goes here... │
│ │
├─────────────────────────────────────────────────────────────────┤
│ ALTERNATIVE PRODUCTS │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ Alt 1 │ │ Alt 2 │ │ Alt 3 │ │ Alt 4 │ │
│ └────────┘ └────────┘ └────────┘ └────────┘ │
└─────────────────────────────────────────────────────────────────┘
📋 BLOG PAGE TEMPLATES (website_blog module)
| XML ID | Feature | Default | Description |
|---|
website_blog.opt_blog_cover_post
| Latest post banner | Active | Show latest post as banner |
website_blog.opt_blog_cover_post_fullwidth_design
| Fullwidth banner | Active | Banner spans full width |
website_blog.opt_blog_list_view
| List view | Inactive | Posts as list vs grid |
website_blog.opt_blog_cards_design
| Cards design | Inactive | Bootstrap card components |
website_blog.opt_blog_readable
| Readability | Active | Larger, readable text |
website_blog.opt_blog_sidebar_show
| Sidebar | Inactive | Show blog sidebar |
Blog Sidebar Components (when enabled)
| XML ID | Feature | Default | Description |
|---|
website_blog.opt_sidebar_blog_index_archives
| Archives | Active | Date-based archive |
website_blog.opt_sidebar_blog_index_follow_us
| Follow Us | Active | Social media links |
website_blog.opt_sidebar_blog_index_tags
| Tags | Active | Tag cloud |
| XML ID | Feature | Default | Description |
|---|
website_blog.opt_posts_loop_show_cover
| Cover image | Active | Featured image |
website_blog.opt_posts_loop_show_author
| Author | Active | Author name/avatar |
website_blog.opt_posts_loop_show_stats
| Stats | Inactive | Comment/view counts |
website_blog.opt_posts_loop_show_teaser
| Teaser | Active | Preview text and tags |
| XML ID | Feature | Default | Description |
|---|
website_blog.opt_blog_post_readable
| Readability | Active | Larger, readable text |
website_blog.opt_blog_post_sidebar
| Sidebar | Inactive | Show post sidebar |
website_blog.opt_blog_post_regular_cover
| Regular cover | Inactive | Title above cover |
website_blog.opt_blog_post_breadcrumb
| Breadcrumbs | Active | Navigation breadcrumbs |
website_blog.opt_blog_post_read_next
| Read next | Active | Next article banner |
website_blog.opt_blog_post_comment
| Comments | Inactive | Enable comments |
website_blog.opt_blog_post_select_to_tweet
| Tweet selection | Inactive | Highlight-to-tweet |
┌─────────────────────────────────────────────────────────────────┐
│ BLOG LISTING (Grid View - Default) │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ [FEATURED POST BANNER IMAGE] ││
│ │ ││
│ │ Latest Article Title ││
│ │ Short teaser text for the featured post... ││
│ │ [Read More →] ││
│ └─────────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────────┤
│ All Posts │ Category 1 │ Category 2 │ [Search...] │
├─────────────────────────────────────────────────────────────────┤
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ [IMAGE] │ │ [IMAGE] │ │ [IMAGE] │ │
│ │ │ │ │ │ │ │
│ │ Post Title 1 │ │ Post Title 2 │ │ Post Title 3 │ │
│ │ By Author │ │ By Author │ │ By Author │ │
│ │ Jan 15, 2024 │ │ Jan 10, 2024 │ │ Jan 5, 2024 │ │
│ │ │ │ │ │ │ │
│ │ Teaser text... │ │ Teaser text... │ │ Teaser text... │ │
│ │ [Tag1] [Tag2] │ │ [Tag1] │ │ [Tag2] [Tag3] │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ BLOG POST DETAIL (Fullwidth Cover - Default) │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ [FULL WIDTH COVER IMAGE] ││
│ │ ││
│ │ Article Title Goes Here ││
│ │ By Author Name · January 15, 2024 ││
│ └─────────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────────┤
│ │
│ Full article content with readable typography. │
│ │
│ Multiple paragraphs of content... │
│ │
│ [Share: Facebook | Twitter | LinkedIn] │
│ │
│ Tags: [Technology] [Tutorial] [Odoo] │
│ │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ READ NEXT: Next Article Title ││
│ │ [Banner Image] ││
│ └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
📋 CART & CHECKOUT TEMPLATES
| XML ID | Feature | Default | Description |
|---|
website_sale.suggested_products_list
| Suggested products | Active | Accessory products in cart |
website_sale.reduction_code
| Promo code | Active | Coupon code input |
| B2B fields | Inactive | Business address fields |
website_sale.accept_terms_and_conditions
| T&C checkbox | Inactive | Require T&C acceptance |
Design Workflow: Figma to Odoo
When converting a Figma design to an Odoo theme, follow this workflow:
┌─────────────────────────────────────────────────────────────────┐
│ DESIGN WORKFLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. ANALYZE DESIGN │
│ ↓ │
│ Extract: Colors, Fonts, Layout, Components │
│ │
│ 2. COMPARE TO ODOO TEMPLATES │
│ ↓ │
│ Match: Header style, Footer style, Page layouts │
│ │
│ 3. CHOOSE CLOSEST TEMPLATE │
│ ↓ │
│ Select: Best matching header + footer + features │
│ │
│ 4. CONFIGURE VIA VARIABLES │
│ ↓ │
│ Set: $o-website-values-palettes configuration │
│ │
│ 5. ENHANCE WITH CUSTOM CSS │
│ ↓ │
│ Add: Only what templates can't provide │
│ │
│ 6. CREATE CUSTOM SNIPPETS (if needed) │
│ ↓ │
│ Build: Components not available in Odoo │
│ │
└─────────────────────────────────────────────────────────────────┘
Step 1: Analyze the Figma Design
Extract these key elements:
| Element | What to Look For | Maps To |
|---|
| Primary Color | Main brand color (buttons, links, CTAs) | |
| Secondary Color | Accent color, secondary buttons | |
| Light Background | Section backgrounds, cards | |
| White/Base | Main content background | |
| Dark/Text | Headings, footer, dark sections | |
| Font Family | Body text, headings | |
| Header Style | Navigation layout | |
| Footer Style | Footer layout | |
Step 2: Match Header Style
| If Design Has... | Use Template |
|---|
| Standard horizontal nav | |
| Hidden menu (hamburger icon) | template_header_hamburger
|
| Full-width stretched nav | |
| Vertical sidebar navigation | |
| Prominent search bar | |
| E-commerce with categories | template_header_sales_two
|
| Top bar + main nav | template_header_sales_one
|
| Sidebar with content | |
| Rounded/boxed container | |
Step 3: Match Footer Style
| If Design Has... | Use Template |
|---|
| Multi-column with logo | (default) |
| Detailed company info | template_footer_descriptive
|
| Center-aligned minimal | |
| Multiple link columns only | |
| Ultra-minimal copyright only | template_footer_minimalist
|
| Contact info focus | |
| Newsletter/CTA focus | template_footer_call_to_action
|
| Large headline text | |
| Modern slide-out effect | |
Step 4: Generate Theme Configuration
Based on analysis, create the configuration:
scss
// primary_variables.scss - Generated from Figma Analysis
$o-theme-font-configs: (
'Poppins': (
'family': ('Poppins', sans-serif),
'url': 'Poppins:300,400,500,600,700',
),
);
$o-website-values-palettes: (
(
'color-palettes-name': 'default-1',
// Typography (from Figma)
'font': 'Poppins',
'headings-font': 'Poppins',
// Header (matched to closest template)
'header-template': 'hamburger', // Figma shows hamburger menu
'header-links-style': 'pills', // Rounded pill-style links
'logo-height': 48px,
// Footer (matched to closest template)
'footer-template': 'contact', // Figma shows contact-focused footer
'footer-scrolltop': true,
// Buttons (from Figma measurements)
'btn-padding-y': 0.75rem,
'btn-padding-x': 1.5rem,
'btn-border-radius': 8px,
// Layout
'link-underline': 'never',
)
);
Step 5: Create theme.utils Implementation
models/theme_yourtheme.py
from odoo import models
class ThemeYourTheme(models.AbstractModel):
_inherit = 'theme.utils'
def _theme_yourtheme_post_copy(self, mod):
# Enable matched header template
self.enable_view('website.template_header_hamburger')
self.enable_view('website.template_header_hamburger_mobile_align_center')
# Enable matched footer template
self.enable_view('website.template_footer_contact')
# Enable desired header components
self.enable_view('website.option_header_brand_logo')
self.enable_view('website.header_search_box')
# Configure visibility effect
self.disable_view('website.header_visibility_standard')
self.enable_view('website.header_visibility_fixed')
Decision Flowchart: Header Selection
START: Analyze header design
│
├─ Is navigation hidden by default?
│ │
│ ├─ YES → template_header_hamburger
│ │
│ └─ NO → Is there a vertical sidebar?
│ │
│ ├─ YES → Is it full-page sidebar?
│ │ │
│ │ ├─ YES → template_header_sidebar
│ │ └─ NO → template_header_vertical
│ │
│ └─ NO → Is it e-commerce focused?
│ │
│ ├─ YES → Does it have category mega-menu?
│ │ │
│ │ ├─ YES → template_header_sales_two
│ │ └─ NO → template_header_sales_one
│ │
│ └─ NO → Is search prominent?
│ │
│ ├─ YES → template_header_search
│ │
│ └─ NO → Is it boxed/contained?
│ │
│ ├─ YES → template_header_boxed
│ │
│ └─ NO → Is it full-width?
│ │
│ ├─ YES → template_header_stretch
│ └─ NO → template_header_default
Decision Flowchart: Footer Selection
START: Analyze footer design
│
├─ Is it minimal (just copyright)?
│ │
│ ├─ YES → template_footer_minimalist
│ │
│ └─ NO → Is it center-aligned?
│ │
│ ├─ YES → template_footer_centered
│ │
│ └─ NO → Is there a newsletter/CTA?
│ │
│ ├─ YES → template_footer_call_to_action
│ │
│ └─ NO → Is it contact info focused?
│ │
│ ├─ YES → template_footer_contact
│ │
│ └─ NO → Is it primarily links?
│ │
│ ├─ YES → template_footer_links
│ │
│ └─ NO → Has detailed description?
│ │
│ ├─ YES → template_footer_descriptive
│ │
│ └─ NO → footer_custom (default)
Website Snippets Complete Reference
This section documents ALL available snippets in Odoo, how they work, and how to create custom ones. Use this when building website pages, creating custom snippets, or understanding the website builder.
📚 SNIPPET ARCHITECTURE OVERVIEW
Snippets are reusable building blocks for Odoo website pages, enabling drag-and-drop page construction.
┌─────────────────────────────────────────────────────────────────┐
│ ODOO SNIPPET SYSTEM │
├─────────────────────────────────────────────────────────────────┤
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ STATIC SNIPPETS │ │ DYNAMIC SNIPPETS │ │
│ ├──────────────────┤ ├──────────────────┤ │
│ │ • Pre-built HTML │ │ • Data-driven │ │
│ │ • 81+ templates │ │ • ir.filters │ │
│ │ • Drag & drop │ │ • Display temps │ │
│ └──────────────────┘ └──────────────────┘ │
│ │ │
│ ┌───────────────────────────┴────────────────────────────────┐ │
│ │ SNIPPET OPTIONS SYSTEM │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ we-select | we-button | we-colorpicker | we-input | etc. │ │
│ │ data-selector | data-select-class | data-js | data-css │ │
│ └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
📋 STATIC SNIPPETS INVENTORY (81+ Templates)
Odoo provides 81+ static snippet templates organized into 6 main categories:
| Category | Count | Purpose |
|---|
| Structure | 14 | Page sections, layouts |
| Gallery/Media | 3 | Image galleries, carousels |
| Features | 11 | Feature showcases |
| Dynamic Content | 15 | Maps, forms, embeds |
| Inner Content | 16 | Cards, quotes, text blocks |
| Mega Menus | 9 | Navigation menus |
| Snippet ID | Name | Description | Best For |
|---|
| Banner | Hero section with background | Landing pages |
| Cover | Full-width cover image | Headers |
| Text - Image | Two-column: text left, image right | Features |
| Image - Text | Two-column: image left, text right | Features |
| Title | Section title with subtitle | Section headers |
| Text Block | Multi-column text content | Content |
| Numbers | Statistics/counters display | Achievements |
| Picture | Single large image | Visual focus |
| Columns | Three-column layout | Content grids |
| Big Boxes | Large feature boxes | Services |
| Features | Feature grid with icons | Benefits |
| Masonry Block | Masonry-style grid | Galleries |
| Image Gallery | Multi-image gallery | Portfolios |
| Images Wall | Wall-style display | Media |
| Snippet ID | Name | Description | Best For |
|---|
| Comparisons | Side-by-side comparison | Product comparison |
| Company Team | Team member cards | About pages |
| Call to Action | CTA section with button | Conversions |
| References | Client logos/references | Social proof |
| Accordion | Collapsible content | FAQs |
| Features Grid | Grid of feature icons | Benefits |
| Table of Content | Scrollspy navigation | Long pages |
| Pricelist | Pricing table | Products |
| Product List | Product showcase | E-commerce |
| FAQ | Frequently asked questions | Support |
| Tabs | Tabbed content | Organization |
Dynamic Content Snippets (15)
| Snippet ID | Name | Description | Best For |
|---|
| Google Map | Google Maps embed | Contact pages |
| Map | Leaflet/OpenStreetMap | Locations |
| Embed Code | Custom HTML/embed | Third-party |
| Website Form | Contact/custom forms | Lead capture |
| Searchbar | Search functionality | Navigation |
| Social Media | Social links | Engagement |
| Share | Share buttons | Content sharing |
| Dynamic Snippet | Base dynamic content | Data display |
s_dynamic_snippet_carousel
| Dynamic Carousel | Dynamic carousel | Featured content |
| Chart | Data visualization | Reports |
| Countdown | Timer/countdown | Events |
| Popup | Modal popup | Promotions |
| Newsletter | Email subscription | Marketing |
| Newsletter Popup | Popup subscription | Lead capture |
s_newsletter_subscribe_form
| Newsletter Form | Inline subscription | Footer |
Inner Content Snippets (16)
| Snippet ID | Name | Description | Best For |
|---|
| Horizontal Rule | Divider line | Section breaks |
| Alert | Alert/notification box | Notices |
| Card | Content card | Items |
| Three Cards | Three-card layout | Services |
| Four Cards | Four-card layout | Features |
| Timeline | Timeline display | History |
| Process Steps | Step-by-step guide | Tutorials |
| Quotes Carousel | Testimonial slider | Social proof |
| Quotes Grid | Testimonial grid | Reviews |
| Rating | Star rating display | Reviews |
| Progress Bar | Progress indicator | Statistics |
| Blockquote | Styled quote | Emphasis |
| Badge | Badge/label | Labels |
| Button | Styled button | CTAs |
| Separator | Section separator | Visual breaks |
| Text Highlight | Highlighted text box | Emphasis |
| Snippet ID | Name | Description |
|---|
| Multi Menus | Multiple menu columns |
s_mega_menu_menu_image_menu
| Menu Image Menu | Three-section with image |
| Little Icons | Icon-based menu |
s_mega_menu_images_subtitles
| Images Subtitles | Images with subtitles |
| Cards | Card-style menu |
| Big Icons | Large icon menu |
| Thumbnails | Thumbnail gallery menu |
| Odoo Menu | Odoo-style menu |
s_mega_menu_no_extra_info
| No Extra Info | Simple menu |
📋 DYNAMIC SNIPPETS SYSTEM
Dynamic snippets fetch data from the database and render using templates.
┌─────────────────────────────────────────────────────────────────┐
│ DYNAMIC SNIPPET FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ │
│ │ DATA SOURCE │ ← ir.filters / ir.actions.server │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ DYNAMIC FILTER │ ← website.snippet.filter model │
│ │ (Data Fetcher) │ │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ DISPLAY TEMPLATE │ ← dynamic_filter_template_* │
│ │ (Renderer) │ │
│ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Product Dynamic Snippets (website_sale)
Main Snippet:
s_dynamic_snippet_products
Display Templates (15 variants):
| Template Key | Name | Style |
|---|
dynamic_filter_template_product_product_add_to_cart
| Add to Cart | With purchase button |
dynamic_filter_template_product_product_banner
| Banner | Large banner format |
dynamic_filter_template_product_product_borderless_1/2/3
| Borderless | Clean borderless |
dynamic_filter_template_product_product_card_style
| Card Style | Card-based |
dynamic_filter_template_product_product_centered
| Centered | Center-aligned |
dynamic_filter_template_product_product_horizontal_card
| Horizontal Card | Horizontal layout |
dynamic_filter_template_product_product_mini
| Mini | Compact display |
dynamic_filter_template_product_product_minimalist_1/2/3/4
| Minimalist | Minimal designs |
dynamic_filter_template_product_product_picture
| Picture | Image-focused |
Dynamic Filters (6 data sources):
| Filter ID | Name | Logic |
|---|
dynamic_filter_newest_products
| Newest Products | Sorted by create_date desc |
dynamic_filter_recently_sold_products
| Recently Sold | Products with recent sales |
dynamic_filter_recently_viewed_products
| Recently Viewed | User's browsing history |
dynamic_filter_accessories
| Accessories | Related accessories |
dynamic_filter_products_sold_with
| Sold With | Frequently bought together |
dynamic_filter_alternative_products
| Alternative | Similar products |
Blog Dynamic Snippets (website_blog)
Display Templates (4 layouts):
| Template Key | Name |
|---|
dynamic_filter_template_blog_post_big_picture
| Big Picture |
dynamic_filter_template_blog_post_card
| Card |
dynamic_filter_template_blog_post_horizontal
| Horizontal |
dynamic_filter_template_blog_post_vertical
| Vertical |
Filters:
dynamic_filter_latest_posts
,
dynamic_filter_most_read_posts
Event Dynamic Snippets (website_event)
Display Templates:
dynamic_filter_template_event_event_card
,
dynamic_filter_template_event_event_list
Filter:
dynamic_filter_upcoming_events
The options system allows users to customize snippets in the website editor.
| Element | Purpose | Key Attributes |
|---|
| Dropdown selection | , |
| Toggle button | , |
| Color picker | , |
| Text/number input | , |
| Slider | , , |
| Checkbox toggle | |
| Grouped buttons | For alignment, etc. |
| Option row | Groups related inputs |
| Paginated selection | For large option sets |
Data Attributes Reference
| Attribute | Purpose | Example |
|---|
| Target CSS selector | data-selector=".s_banner"
|
| Toggle CSS class | data-select-class="shadow-lg"
|
| Enable style editing | |
| CSS property to modify | data-css-property="padding"
|
| JavaScript handler class | data-js="BackgroundImage"
|
| Show based on other options | data-dependencies="image_opt"
|
| Hide for certain elements | data-exclude=".no-shadow"
|
| Disable live preview | |
| HTML attribute to set | data-attribute-name="data-speed"
|
Built-in JavaScript Handlers
| Handler | Purpose |
|---|
| Background image management |
| Image positioning |
| Toggle background type |
| Color palette backgrounds |
| Decorative shapes |
| Image editing |
| Media replacement |
| Icon management |
| Carousel controls |
| Dynamic content options |
Complete Options Template Example
xml
<template id="s_my_snippet_options" inherit_id="website.snippet_options">
<xpath expr="." position="inside">
<div data-js="MySnippetHandler"
data-selector=".s_my_snippet"
data-drop-in=".oe_structure"
data-drop-near="section">
<!-- Layout Selection -->
<we-select string="Layout" data-name="layout_opt">
<we-button data-select-class="layout-grid">Grid</we-button>
<we-button data-select-class="layout-list">List</we-button>
</we-select>
<!-- Color Options -->
<we-colorpicker string="Background"
data-name="bg_color_opt"
data-select-style="true"
data-css-property="background-color"/>
<!-- Spacing -->
<we-range string="Spacing"
data-name="spacing_opt"
data-select-style="true"
data-css-property="gap"
data-min="0"
data-max="100"
data-step="5"
data-unit="px"/>
<!-- Conditional Option -->
<we-select string="Shadow Size"
data-name="shadow_size_opt"
data-dependencies="shadow_opt">
<we-button data-select-class="shadow-sm">Small</we-button>
<we-button data-select-class="shadow-lg">Large</we-button>
</we-select>
</div>
</xpath>
</template>
📋 CREATING CUSTOM SNIPPETS (VERSION-AWARE)
Odoo 14-17: Simple Registration
xml
<!-- 1. Snippet Template -->
<template id="s_my_snippet" name="My Snippet">
<section class="s_my_snippet pt48 pb48 o_cc o_cc1">
<div class="container">
<div class="row">
<div class="col-lg-12 text-center">
<h2>My Custom Snippet</h2>
<p>Content goes here...</p>
</div>
</div>
</div>
</section>
</template>
<!-- 2. Snippet Registration -->
<template id="s_my_snippet_insert" inherit_id="website.snippets">
<xpath expr="//div[@id='snippet_structure']//t[@t-snippet][last()]" position="after">
<t t-snippet="my_module.s_my_snippet"
t-thumbnail="/my_module/static/src/img/snippets/s_my_snippet.svg">
<keywords>my, custom, snippet</keywords>
</t>
</xpath>
</template>
Odoo 18-19: With Snippet Groups
xml
<!-- 1. Snippet Template (same as above) -->
<!-- 2. Optional: Custom Snippet Group -->
<template id="snippet_group_custom" inherit_id="website.snippets">
<xpath expr="//div[@id='snippet_groups']" position="inside">
<t snippet-group="custom"
t-snippet="website.s_snippet_group"
string="Custom Snippets"/>
</xpath>
</template>
<!-- 3. Snippet Registration with Group -->
<template id="s_my_snippet_insert" inherit_id="website.snippets">
<xpath expr="//div[@id='snippet_structure']/*[1]" position="before">
<t t-snippet="my_module.s_my_snippet"
string="My Snippet"
group="custom"
t-thumbnail="/my_module/static/src/img/snippets/s_my_snippet.svg"/>
</xpath>
</template>
| Panel ID | Category | XPath Target |
|---|
| Mega Menu | //div[@id='snippet_mega_menu']
|
| Structure | //div[@id='snippet_structure']
|
| Gallery | //div[@id='snippet_media']
|
| Features | //div[@id='snippet_feature']
|
| Dynamic Content | //div[@id='snippet_dynamic']
|
| Inner Content | //div[@id='snippet_inner_content']
|
📋 SNIPPET JAVASCRIPT INTEGRATION
publicWidget Pattern for Snippets
javascript
import publicWidget from "@web/legacy/js/public/public_widget";
publicWidget.registry.MySnippet = publicWidget.Widget.extend({
selector: '.s_my_snippet',
disabledInEditableMode: false, // Allow in website builder
events: {
'click .load-more': '_onLoadMore',
},
start: function () {
// CRITICAL: Check editableMode for builder compatibility
if (!this.editableMode) {
this._initializeAnimations();
}
return this._super(...arguments);
},
_initializeAnimations: function () {
// Animation code that should NOT run in edit mode
this.$el.addClass('animated');
},
_onLoadMore: function (ev) {
ev.preventDefault();
if (this.editableMode) return; // Don't run in edit mode
// Handler logic
},
destroy: function () {
// CRITICAL: Clean up event listeners
$(window).off('.mySnippet');
this._super(...arguments);
},
});
export default publicWidget.registry.MySnippet;
Snippet Options JavaScript Handler
javascript
import options from "@web_editor/js/editor/snippets.options";
options.registry.MySnippetOption = options.Class.extend({
selectDataAttribute: function(previewMode, widgetValue, params) {
this._super(...arguments);
if (params.attributeName === 'layout') {
this._applyLayout(widgetValue);
}
},
_applyLayout: function(layout) {
this.$target.removeClass('layout-grid layout-list');
this.$target.addClass(`layout-${layout}`);
},
_computeWidgetVisibility: function(methodName, params) {
if (methodName === 'showAdvanced') {
return this.$target.hasClass('advanced-mode');
}
return this._super(...arguments);
},
});
📋 VERSION DIFFERENCES FOR SNIPPETS
| Feature | Odoo 14-15 | Odoo 16-17 | Odoo 18-19 |
|---|
| Snippet Count | ~40 | 81+ | 155+ |
| Registration | Simple XPath | Simple XPath | Groups required |
| Asset System | Template inherit | ir.asset model | ir.asset model |
| JavaScript | | ES6 modules | Plugin-based |
| Bootstrap | 4.x | 5.1.3 | 5.1.3 |
| Dynamic Snippets | Basic | Full | Full + Categories |
| Editor | Legacy | Legacy | Plugin architecture |
Odoo 19 Plugin Pattern (New)
javascript
import { Plugin } from "@html_editor/plugin";
import { registry } from "@web/core/registry";
export class MySnippetPlugin extends Plugin {
static id = "mySnippet";
static dependencies = ["builderOptions", "builderActions"];
resources = {
builder_options: [{
template: "my_module.MySnippetOption",
selector: "section",
applyTo: ".s_my_snippet",
}],
builder_actions: {
MyAction: { /* action definition */ },
},
};
}
registry.category("website-plugins").add("mySnippet", MySnippetPlugin);
📋 CREATING DYNAMIC SNIPPETS
Step 1: Define the Filter
xml
<record id="dynamic_filter_my_items" model="website.snippet.filter">
<field name="name">My Items</field>
<field name="model_name">my.model</field>
<field name="limit">12</field>
<field name="filter_id" ref="ir_filter_my_items"/>
</record>
<record id="ir_filter_my_items" model="ir.filters">
<field name="name">Latest Items</field>
<field name="model_id">my.model</field>
<field name="domain">[('is_published', '=', True)]</field>
<field name="sort">create_date desc</field>
</record>
Step 2: Create Display Template
xml
<template id="dynamic_filter_template_my_model_card" name="My Model Card">
<t t-foreach="records" t-as="record">
<div class="col-lg-4 mb-4">
<div class="card h-100 shadow-sm">
<img t-att-src="record.image_url" class="card-img-top"/>
<div class="card-body">
<h5 class="card-title" t-esc="record.name"/>
<p class="card-text" t-esc="record.description"/>
</div>
</div>
</div>
</t>
</template>
Step 3: Create Dynamic Snippet
xml
<template id="s_dynamic_my_items" name="Dynamic My Items">
<section class="s_dynamic_snippet s_dynamic_my_items pt48 pb48"
data-snippet="s_dynamic_my_items"
data-name="Dynamic My Items"
data-filter-id="my_module.dynamic_filter_my_items"
data-template-key="my_module.dynamic_filter_template_my_model_card"
data-number-of-elements="6"
data-number-of-elements-small-devices="2">
<div class="container">
<div class="row">
<h2 class="col-12 text-center mb-4">Featured Items</h2>
</div>
<div class="dynamic_snippet_template row"/>
</div>
</section>
</template>
Updated /create-theme Command (v6.0)
The
command now automatically generates the
file with template activation.
theme_<name>/
├── __init__.py # Imports models
├── __manifest__.py # Updated with models/ import
├── models/
│ ├── __init__.py # Imports theme_<name>
│ └── theme_<name>.py # theme.utils implementation (NEW!)
├── security/
│ └── ir.model.access.csv
├── data/
│ ├── assets.xml
│ ├── menu.xml
│ └── pages/
│ ├── home_page.xml
│ ├── aboutus_page.xml
│ └── contactus_page.xml
├── views/
│ ├── layout/
│ │ └── templates.xml
│ └── snippets/
│ └── custom_snippets.xml
└── static/src/
├── scss/
│ ├── primary_variables.scss
│ └── theme.scss
├── js/
│ └── theme.js
└── img/
Generated theme_<name>.py
python
from odoo import models
class Theme<Name>(models.AbstractModel):
_inherit = 'theme.utils'
def _theme_<name>_post_copy(self, mod):
"""
Configure theme defaults when installed on a website.
This method is called automatically when the theme is applied.
Use enable_view() and disable_view() to configure templates.
"""
# === HEADER CONFIGURATION ===
# Enable desired header template (only one can be active)
self.enable_view('website.template_header_<detected>')
# Configure header visibility
self.disable_view('website.header_visibility_standard')
self.enable_view('website.header_visibility_fixed')
# Enable header components
self.enable_view('website.option_header_brand_logo')
# === FOOTER CONFIGURATION ===
# Enable desired footer template (only one can be active)
self.enable_view('website.template_footer_<detected>')
-
v7.0.0: Website Snippets Complete Reference (MAJOR)
- NEW: Complete Static Snippets Inventory (81+ Templates)
- Structure snippets (s_banner, s_cover, s_parallax, etc.)
- Feature snippets (s_features, s_comparisons, s_image_text, etc.)
- Dynamic content snippets (s_dynamic_snippet_*, products, blog, events)
- Inner content snippets (s_hr, s_badge, s_card, s_blockquote, etc.)
- Mega menu snippets (s_mega_menu_*, multi_menus, odoo_menu)
- NEW: Dynamic Snippets System Documentation
- website.snippet.filter model architecture
- 15 product display templates (dynamic_filter_template_*)
- 6 built-in product snippet filters
- Blog and event dynamic snippet patterns
- NEW: Snippet Options System Reference
- Complete we-* elements (we-select, we-button, we-colorpicker, we-input, we-range, we-checkbox)
- Data attributes reference (data-selector, data-select-class, data-js, data-css-property, data-dependencies)
- Built-in JavaScript handlers (BackgroundImage, Carousel, ImageTools, etc.)
- Complete snippet options XML example
- NEW: Version-Aware Custom Snippet Creation
- Odoo 14-17 simple t-snippet registration
- Odoo 18-19 snippet groups pattern
- XPath insertion techniques
- NEW: Odoo 19 Plugin Pattern Documentation
- @html_editor/plugin based architecture
- 130+ plugin files reference
- SnippetOption class pattern
- NEW: Creating Dynamic Snippets Guide
- Define filter (website.snippet.filter)
- Create display template (dynamic_filter_template_*)
- Create dynamic snippet with data-filter-id
-
v6.0.0: Theme Feature Activation System & Dynamic Page Reference (MAJOR)
- NEW: Theme Feature Activation System
- Complete model documentation
_theme_{module}_post_copy()
- and method reference
- Mutual exclusivity rules for headers/footers
- Complete working examples
- NEW: Complete Dynamic Page Reference
- 11 header templates with XML IDs and visual diagrams
- 9 footer templates with XML IDs and visual diagrams
- All shop page templates (categories, filters, layout)
- All product detail page templates
- All blog templates (listing, detail, sidebar)
- Cart and checkout templates
- NEW: Design Workflow Methodology
- Figma analysis extraction guide
- Template matching decision flowcharts
- Configuration generation from design
- Step-by-step workflow documentation
- UPDATED: /create-theme command v6.0
- Now generates automatically
- Template activation based on configuration
- Complete module structure with all required files
-
v5.1.0: Comprehensive Variable Reference Enhancement (MAJOR)
- Complete $o-theme-font-configs reference:
- 'family': CSS font-family list (tuple format)
- 'url': Google Fonts parameter ONLY (not full URL)
- 'properties': Per-context CSS overrides (base, headings, navbar, buttons)
- Font aliases documentation: 'base', 'headings', 'h2'-'h6', 'navbar', 'buttons'
- Arabic/RTL font support examples
- Complete $o-color-palettes reference:
- 5 core colors semantic meanings (o-color-1 through o-color-5)
- Color combinations (o_cc1 - o_cc5) presets and usage
- Override syntax for color combinations ()
- Component assignments (menu, footer, copyright)
- HTML usage examples with color classes
- Complete $o-website-values-palettes reference (115+ keys):
- Typography & Fonts (13 keys): font family configuration
- Font Sizes (13 keys): base and heading sizes
- Line Heights & Margins (33 keys): spacing configuration
- Buttons (17 keys): padding, radius, style options
- Inputs (12 keys): form field styling
- Header (13 keys): templates, link styles, logo, hamburger
- Footer (3 keys): templates, effects, scrolltop
- Links (1 key): underline behavior
- Layout (3 keys): full/boxed, background
- Colors & Gradients (5 keys): palette selection, gradients
- Google Fonts (2 keys): additional fonts
- Restored full theme structure: header.xml, footer.xml, snippets (OPTIONAL but present in hierarchy)
- Removed redundant documentation sections: Cleaned up duplicate content
-
v5.0.0: Major enhancement based on comprehensive variable system analysis
- Variables can control header/footer templates without custom XML
- Configure via and variables
- Bootstrap control via
$o-website-values-palettes
-
v4.0.0: CRITICAL fixes based on real-world theme development issues
- ⚠️ SCSS Load Order Documentation: Documented that theme SCSS loads BEFORE core variables
- Removed map-merge() patterns: Fixed examples that used with core variables (causes "Undefined variable" errors)
- Font loading fix: Use as standalone, NOT via records
- XPath simplification: Use simple expressions (//header) not complex ones (//header//nav)
- Enhanced troubleshooting: Added SCSS debugging, asset cache clearing, silent compilation failures
- Corrected all templates: command now generates working code without map-merge issues
-
v3.1.0: Added
command for complete theme generation based on 40+ real implementations
- Complete
$o-website-values-palettes
- Semantic color system ( to )
- Individual page files pattern (best practice)
- publicWidget patterns with handling
- Version-specific snippet registration (14-19)
- Windows console encoding fix for script output
-
v3.0.0: Enhanced theme system with $o-website-values-palettes reference and mirror model architecture
-
v2.0.0: Added PWA support, TypeScript, testing frameworks, performance optimization, accessibility, real-time features, and modern build tools
-
v1.0.0: Initial release with full Odoo 14-19 support, Figma/DevTools MCP integration