8000 [ADD] tutorials/website_theme: Add tutorials to build a website theme · odoo/documentation@ee982d5 · GitHub
[go: up one dir, main page]
Skip to content

Commit ee982d5

Browse files
bram-odoobram-odoo
committed
[ADD] tutorials/website_theme: Add tutorials to build a website theme
closes #13202 Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com> Signed-off-by: Céline de Lannoy (cede) <cede@odoo.com>
1 parent d6e4aef commit ee982d5

29 files changed

+1160
-1
lines changed

‎conf.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,7 @@
8282
'CURRENT_MAJOR_VERSION': current_major_version,
8383
'GITHUB_PATH': f'https://github.com/odoo/odoo/blob/{version}',
8484
'GITHUB_ENT_PATH': f'https://github.com/odoo/enterprise/blob/{version}',
85+
'GITHUB_TUTO_PATH': f'https://github.com/odoo/tutorials/blob/{current_major_branch}',
8586
'OWL_PATH': f'https://github.com/odoo/owl/blob/master',
8687
}
8788

‎content/developer/tutorials.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Tutorials
1616
tutorials/importable_modules
1717
tutorials/mixins
1818
tutorials/pdf_reports
19+
tutorials/website_theme
1920

2021
.. tip::
2122
If you are new to Odoo development, we recommend starting with the :doc:`setup guide
@@ -89,3 +90,9 @@ Expand your knowledge on the server framework
8990
:target: tutorials/pdf_reports
9091

9192
Use QWeb, Odoo's powerful templating engine, to create custom PDF reports for your documents.
93+
94+
.. card:: Build a website theme
95+
:target: tutorials/website_theme
96+
97+
Create a tailored website from scratch fully integrated with Odoo and editable via the Website
98+
Builder.

‎content/developer/tutorials/web.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Customizing the web client
1313

1414
This guide is about creating modules for Odoo's web client.
1515

16-
To create websites with Odoo, see :doc:`website`; to add business capabilities
16+
To create websites with Odoo, see :doc:`website_theme`; to add business capabilities
1717
or extend existing business systems of Odoo, see :doc:`backend`.
1818

1919
.. warning::

‎content/developer/tutorials/website_theme.rst

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
:show-content:
2+
:show-toc:
3+
:hide-page-toc:
4+
5+
=====================
6+
Build a website theme
7+
=====================
8+
9+
| For this project, we'll collaborate on creating a custom website theme fully integrated with Odoo.
10+
| Our client, Airproof, has provided their latest design for their waterproof drone e-commerce,
11+
which we'll replicate.
12+
13+
To start, you must have :doc:`installed Odoo locally </administration/on_premise/source>`.
14+
You will also need some knowledge in:
15+
16+
- XML
17+
- JavaScript (not mandatory)
18+
- Bootstrap 5.1.3
19+
- SCSS
20+
- QWeb (Odoo's own templating system)
21+
- OWL (JavaScript framework, not mandatory)
22+
23+
| **Goal**
24+
| Replicate the Airproof design.
25+
26+
.. image:: website_theme/airproof-home.png
27+
:alt: Airproof homepage.
28+
:align: center
29+
30+
| In the :file:`README.md` of the `Airproof module <{GITHUB_TUTO_PATH}/website_airproof>`_, you can
31+
find the various Airproof designs that you will replicate throughout the different exercises in
32+
this tutorial.
33+
| You can also find all the code necessary for creating the Airproof website there. You should also
34+
obtain this by the end of the tutorial. It is recommended to try solving the exercices first
35+
without looking at the solution!
36+
37+
| **Don't go too fast!**
38+
| Follow the exercises step by step and you will reach the final design at the end of the tutorial.
39+
40+
Throughout this tutorial, you will find "See also" sections leading to parts of the :doc:`How-to
41+
guide: Website themes <../howtos/website_themes>` documentation. Be sure to read this documentation
42+
thoroughly each time! With it, you will find the solution to every exercise.
43+
44+
Ready? Let's get started!
45+
46+
.. toctree::
47+
:maxdepth: 2
48+
49+
website_theme/01_theming
50+
website_theme/02_build_website
51+
website_theme/03_customisation_part1
52+
website_theme/04_customisation_part2
53+
website_theme/05_dynamic_templates
54+
website_theme/06_going_live

‎content/developer/tutorials/website_theme/01_theming.rst

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
===================
2+
Chapter 1 - Theming
3+
===================
4+
5+
Now that you have Odoo installed and your server is running locally, it's time to create your own
6+
theme module for your website.
7+
8+
.. _tutorials/website_theme/theming/setup:
9+
10+
Setup
11+
=====
12+
13+
| The first step is to ensure that Odoo is running correctly locally. To do this, use a Shell script
14+
to run the server.
15+
| In this script, define the database name and install only the `website` module.
16+
17+
.. seealso::
18+
See reference documentation on how to :ref:`run Odoo <website_themes/setup/getting_started>`.
19+
20+
.. _tutorials/website_theme/theming/module:
21+
22+
Build your module structure
23+
===========================
24+
25+
Now that we know everything is working properly, let's start building our module.
26+
27+
Based on the following structure, start creating your module that will be used as a theme. This is
28+
where you are going to add your XML pages, SCSS, JS, …
29+
30+
.. seealso::
31+
See reference documentation on how to structure your :ref:`theming/module`.
32+
33+
| Start with the basics : :file:`/data`, :file:`/img`, :file:`/scss`, :file:`/js`.
34+
| Don't forget to add the :file:`__init__.py` and :file:`__manifest__.py` files.
35+
36+
In your :file:`__manifest__.py` file, you can declare your module with the following information:
37+
38+
- name (required)
39+
- description
40+
- category
41+
- version
42+
- author
43+
- license
44+
- depends
45+
46+
.. _tutorials/website_theme/theming/odoo_variables:
47+
48+
Declare Odoo variables
49+
======================
50+
51+
In the :file:`primary_variables.scss` file, you can override the default Odoo SCSS variables to
52+
match your design.
53+
54+
Based on the Airproof design, create your :file:`primary_variables.scss` file and define the
55+
following elements:
56+
57+
- Headings font family : Space Grotesk
58+
- Content font family : Lato
59+
- The color palette name and the 5 main colors that compose it: `#000000`, `#BBE1FA`, `#CEF8A1`,
60+
`#FFFFFF`, `#0B8EE6`
61+
- Header & Footer : Use one of the default templates for the moment, we will create a custom header
62+
later.
63+
64+
.. seealso::
65+
See reference documentation on how to use :ref:`primary variables <theming/module/variables>`, as
66+
well as a list of all `primary variables
67+
<{GITHUB_PATH}/addons/website/static/src/scss/primary_variables.scss>`_ available.
68+
69+
| Restart your script to immediately see the application of your changes.
70+
| Don't forget to add the path to your manifest in the script and set your module as the app
71+
to install.
72+
73+
To ensure your changes are applied correctly, log in to your website and check that your
74+
color palette includes your specified colors.
75+
76+
.. tip::
77+
You will need to override more variables to replicate the Airproof design. Remember to add them
78+
throughout the creation of your website.
79+
80+
.. note::
81+
The font families are from `Google fonts <https://fonts.google.com/>`_.
82+
83+
.. spoiler:: Solutions
84+
85+
To complete this exercise, you need to:
86+
87+
#. Create your :file:`primary_variables.scss` file. You can find all the necessary information in
88+
the `primary_variables.scss
89+
<{GITHUB_TUTO_PATH}/website_airproof/static/src/scss/primary_variables.scss>`_ file from our
90+
example module.
91+
#. Declare your file in the :file:`__manifest__.py` as indicated in the documentation.
92+
#. Install your module via your script. In our example, it looks like this:
93+
94+
.. code-block:: xml
95+
96+
./odoo-bin --addons-path=../enterprise,addons,../myprojects --db-filter=theming -d theming
97+
--without-demo=all -i website_airproof --dev=xml
98+
99+
.. _tutorials/website_theme/theming/bootstrap_variab 1241 les:
100+
101+
Declare Bootstrap variables
102+
===========================
103+
104+
On top of the default Odoo variables, you can also redefine the Bootstrap variables. Bootstrap is a
105+
front-end framework which is included by default in Odoo.
106+
107+
Based on the Airproof design, define the following elements:
108+
109+
- Headings font sizes :
110+
111+
- h1 : 3.125rem
112+
- h2 : 2.5rem
113+
- h3 : 2rem
114+
- h4 : 1.75rem
115+
- h5 : 1.5rem
116+
- h6 : 1.25rem
117+
118+
- Inputs border radius : 10px
119+
- Inputs border color : black
120+
- Inputs border width : 1px
121+
- Large buttons border radius : 0px 10px 10px 10px
122+
123+
.. seealso::
124+
- See reference documentation on how to use :ref:`theming/module/bootstrap`.
125+
- A list of all `Bootstrap variables
126+
<{GITHUB_PATH}/addons/web/static/lib/bootstrap/scss/_variables.scss>`_ used by Odoo.
127+
- And `Bootstrap framework <https://getbootstrap.com/docs/4.6/getting-started/introduction/>`_
128+
official documentation.
129+
130+
.. tip::
131+
- You will need to override more variables to replicate the Airproof design. Remember to add them
132+
throughout the creation of your website.
133+
- Make it a habit to regularly check locally that your changes have been successfully applied
134+
and have not caused any errors.
135+
136+
.. spoiler:: Solutions
137+
138+
To complete this exercise, you need to:
139+
140+
#. Create your :file:`bootstrap_overridden.scss` file. You can find all the necessary information
141+
in the `bootstrap_overridden.scss
142+
<{GITHUB_TUTO_PATH}/website_airproof/static/src/scss/bootstrap_overridden.scss>`_ file from
143+
our example module.
144+
#. Declare your file in the :file:`__manifest__.py` as indicated in the documentation.
145+
146+
.. _tutorials/website_theme/theming/presets:
147+
148+
Define presets
149+
==============
150+
151+
In addition to the variables we have just covered, you can also activate specific views to modify
152+
the design.
153+
154+
Add your :file:`presets.xml` file and based on the Airproof design, activate the appropriate views
155+
to meet the following client requests:
156+
157+
- Deactivate the Call-to-action in the header.
158+
- Deactivate the wishlist feature in the shop but activate it on the product page.
159+
- On the shop page, activate the filtering by categories only on the left side.
160+
161+
.. seealso::
162+
| See how you can define your :ref:`presets <theming/module/views/presets>`.
163+
| To start writing your file, follow the instructions for any Odoo XML page described in
164+
:doc:`/developer/howtos/website_themes/layout`.
165+
166+
.. tip::
167+
- To complete the exercise, you need to install the **eCommerce** (`website_sale`) and
168+
**wishlist** (`website_sale_whishlist`) applications. **Be careful!** Referencing an
169+
application in your code that hasn't been installed will result in an error.
170+
- | In order to find the templates to activate or not, go to the source code:
171+
`odoo/addons/website/views/**`.
172+
| For example, you can find all the templates for the header in
173+
`website_templates.xml <{GITHUB_PATH}/addons/website/views/website_templates.xml>`_.
174+
- To see the effect of your presets, add some **products** (*Airproof Mini*, *Airproof Robin*,
175+
*Warranty*, *Charger cable*) and create **eCommerce categories** (*Warranties*, *Accessories*,
176+
and *Drones* with *Camera drones* and *Waterproof drones*) in the database. You will find the
177+
`product images here <{GITHUB_TUTO_PATH}/website_airproof/static/src/img/content>`_.
178+
- You will need to activate more views to replicate the Airproof design. Remember to add them
179+
throughout the creation of your website.
180+
181+
.. spoiler:: Solutions
182+
183+
To deactivate the Call-to-action:
184+
185+
#. The view you have to find is in :file:`odoo/addons/website/views/website_templates.xml l:2113`
186+
#. Create your :file:`presets.xml` file with the right records
187+
188+
.. code-block:: xml
189+
:caption: ``/website_airproof/data/presets.xml``
190+
191+
<?xml version="1.0" encoding="utf-8"?>
192+
<odoo>
193+
<!-- Disable Call-to-action in header -->
194+
<record id="website.header_call_to_action" model="ir.ui.view">
195+
<field name="active" eval="False"/>
196+
</record>
197+
</odoo>
198+
#. In the manifest, add the 2 apps and declare your file.
199+
200+
.. code-block:: python
201+
:caption: ``/website_airproof/__manifest__.py``
202+
203+
'depends': ['website_sale', 'website_sale_wishlist'],
204+
'data': [
205+
# Options
206+
'data/presets.xml',
207+
]

0 commit comments

Comments
 (0)
0