[MOV] tutorials/getting_started/*: promote advanced chapters to independent tutorials

task-2991663

Part-of: odoo/documentation#3629
This commit is contained in:
Antoine Vandevenne (anv) 2023-02-20 16:48:19 +00:00
parent 433e5607ac
commit 052a51b068
30 changed files with 161 additions and 243 deletions

View File

@ -9,6 +9,11 @@ Tutorials
:titlesonly:
tutorials/getting_started
tutorials/define_module_data
tutorials/restrict_data_access
tutorials/unit_tests
tutorials/pdf_reports
tutorials/dashboards
.. raw:: html
@ -20,9 +25,9 @@ Tutorials
<div class="card-body pb-0">
<h4 class="card-title text-primary mb-1">Getting started</h4>
<p class="card-text text-dark fw-normal">
Learn how to develop your own module with the Odoo framework. This
step-by-step tutorial is crafted for newcomers and any other individual
curious about Odoo development.
Develop your own module with the Odoo framework. This step-by-step tutorial
is crafted for newcomers and any other individual curious about Odoo
development.
</p>
</div>
<div class="card-footer border-0">
@ -31,4 +36,75 @@ Tutorials
</div>
</a>
<a class="o_toctree_card col" href="tutorials/define_module_data.html">
<div class="card h-100">
<div class="card-body pb-0">
<h4 class="card-title text-primary mb-1">Define module data</h4>
<p class="card-text text-dark fw-normal">
Define master and demo data for an Odoo module, leveraging the strengths of
the CSV and XML file formats to accommodate specific data requirements.
</p>
</div>
<div class="card-footer border-0">
<span class="badge rounded-pill bg-dark mt-auto mb-2">Beginner</span>
</div>
</div>
</a>
<a class="o_toctree_card col" href="tutorials/restrict_data_access.html">
<div class="card h-100">
<div class="card-body pb-0">
<h4 class="card-title text-primary mb-1">Restrict access to data</h4>
<p class="card-text text-dark fw-normal">
Implement security measures to restrict access to sensitive data with the
help of groups, access rights, and record rules.
</p>
</div>
<div class="card-footer border-0">
<span class="badge rounded-pill bg-dark mt-auto mb-2">Beginner</span>
</div>
</div>
</a>
<a class="o_toctree_card col" href="tutorials/unit_tests.html">
<div class="card h-100">
<div class="card-body pb-0">
<h4 class="card-title text-primary mb-1">Safeguard your code with unit tests</h4>
<p class="card-text text-dark fw-normal">
Write effective unit tests in Python to ensure the resilience of your code
and safeguard it against unexpected behaviors and regressions.
</p>
</div>
<div class="card-footer border-0">
<span class="badge rounded-pill bg-dark mt-auto mb-2">Beginner</span>
</div>
</div>
</a>
<a class="o_toctree_card col" href="tutorials/pdf_reports.html">
<div class="card h-100">
<div class="card-body pb-0">
<h4 class="card-title text-primary mb-1">Build PDF reports</h4>
<p class="card-text text-dark fw-normal">
Use QWeb, Odoo's powerful templating engine, to create custom PDF reports for
your documents.
</p>
</div>
<div class="card-footer border-0"></div>
</div>
</a>
<a class="o_toctree_card col" href="tutorials/dashboards.html">
<div class="card h-100">
<div class="card-body pb-0">
<h4 class="card-title text-primary mb-1">Visualize data in dashboards</h4>
<p class="card-text text-dark fw-normal">
Create data visualization dashboards using the enterprise edition "Dashboard"
view and so-called "SQL views".
</p>
</div>
<div class="card-footer border-0"></div>
</div>
</a>
</div>

View File

@ -1,18 +1,11 @@
.. _tutorials/getting_started/K_dashboard:
============================
Visualize data in dashboards
============================
======================
Advanced K: Dashboards
======================
.. warning::
This tutorial assumes you have completed the :ref:`Core Training <tutorials/getting_started>`
and have access to Odoo Enterprise features.
To follow the exercise, it is recommended that you fetch the branch
{CURRENT_MAJOR_BRANCH}-core from the repository XXX, it
contains a version of the module created during the core training we can use
as a starting point.
.. important::
This tutorial is an extension of the :doc:`getting_started` tutorial. Make sure you have
completed it and use the `estate` module you have built as a base for the exercises in this
tutorial.
The term "Dashboard" is used in Odoo for objects that display data, but involves different
implementations. This tutorial will only focus on the Enterprise view that is used to provide
@ -55,8 +48,8 @@ is also common to include "report" in the name of the SQL view's files. You may
wondering why do we put the files in a report directory? We saw earlier that the dashboard is
for data visualization, therefore it is not editable. You can think of dashboards as interactive
reports where you can click on statistics, graphs, and charts to see the specific data contributing
to them. Note it is also standard to store the xml code for
:ref:`PDF report templates <tutorials/getting_started/J_reports>` in the report directory.
to them. Note it is also standard to store the xml code for :doc:`PDF report templates
<pdf_reports>` in the report directory.
It is expected that your work tree will look something like:
@ -86,7 +79,7 @@ Dashboard View
**Goal**: at the end of this section, we will have a new dashboard view that displays
different property statistics.
.. image:: K_dashboard/simple_dashboard.png
.. image:: dashboards/simple_dashboard.png
:align: center
:alt: Basic Dashboard view
@ -116,8 +109,8 @@ minimum, and maximum statistics, therefore a good representation set for our das
If you don't have a set of data like this already, you can either:
* Complete :ref:`tutorials/getting_started/C_data` (if you haven't done so already) and add the
extra cases to your demo data (you may need to create a new database to load in the demo data).
* Complete :doc:`define_module_data` (if you haven't done so already) and add the extra cases to
your demo data (you may need to create a new database to load in the demo data).
* Manually create the data in your database.
* Copy this `data file <https://github.com/odoo/technical-training-solutions/blob/{CURRENT_MAJOR_BRANCH}-K_dashboard/estate/data/estate_demo.xml>`__
into a new directory called ``data`` in your estate module and copy
@ -197,9 +190,7 @@ Subviews
Similar to how we can use the list view within the form view (we saw this automatically happen for
One2many relationships in :ref:`tutorials/getting_started/08_relations`), we can add other views
within our dashboard view. The most commonly added are the pivot and graph views, but the cohort
view is also an option. These views are covered in more depth in
:ref:`tutorials/getting_started/H_adv_views`. For this topic, you are only required to know their
names. A dashboard with only subviews is:
view is also an option. A dashboard with only subviews is:
.. code-block:: xml
@ -238,7 +229,7 @@ SQL Views
**Goal**: at the end of this section, we will have a new SQL view that displays different
property statistics.
.. image:: K_dashboard/report_dashboard.png
.. image:: dashboards/report_dashboard.png
:align: center
:alt: SQL view
@ -349,7 +340,7 @@ are still looking at all the offers per property, so any property with more than
counted per offer. This example is easily double-checked by clicking on the pie chart to see its
list view:
.. image:: K_dashboard/report_list_detail.png
.. image:: dashboards/report_list_detail.png
:align: center
:alt: Pie chart list view

View File

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 22 KiB

View File

Before

Width:  |  Height:  |  Size: 45 KiB

After

Width:  |  Height:  |  Size: 45 KiB

View File

@ -1,13 +1,11 @@
.. _tutorials/getting_started/C_data:
==================
Define module data
==================
================================
Advanced C: Master and Demo Data
================================
.. tip:: This tutorial assumes you followed the Core Training.
To do the exercise, fetch the branch {CURRENT_MAJOR_BRANCH}-core from the repository XXX.
It contains a basic module we will use as a starting point
.. important::
This tutorial is an extension of the :doc:`getting_started` tutorial. Make sure you have
completed it and use the `estate` module you have built as a base for the exercises in this
tutorial.
Data Types
==========
@ -19,9 +17,8 @@ Master data is usually part of the technical or business requirements for the mo
words, such data is often necessary for the module to work properly. This data will always be
installed when installing the module.
We already met technical data previously since we have defined
:ref:`security rules <tutorials/getting_started/N_security>`, :ref:`views<reference/views>` and
:ref:`actions<reference/actions>`. Those are one kind of master data.
We already met technical data previously since we have defined :ref:`views <reference/views>` and
:ref:`actions <reference/actions>`. Those are one kind of master data.
On top of technical data, business data can be defined: countries, currencies, units of measure but
also complete country localization (legal reports, tax definitions, chart of account), and much

View File

@ -6,45 +6,29 @@
Getting started
===============
.. toctree::
:titlesonly:
:glob:
getting_started/*
Welcome to the Getting Started Odoo tutorial! If you reached this page that means you are
interested in the development of your own Odoo module. It might also mean that you recently
joined the Odoo company for a rather technical position. In any case, your journey to the
technical side of Odoo starts here.
This training is split in two parts:
- The first part is the :ref:`core training <tutorials/getting_started/core_training>`. Its
objective is to give you an insight of the most important parts of the Odoo development framework.
The chapters should be followed in their given order since they cover the development of a new
Odoo application from scratch in an incremental way. In other words, each chapter depends on the
previous one.
- The second part covers a set of :ref:`advanced topics
<tutorials/getting_started/advanced_topics>`. Each topic can be followed independently, but
requires the :ref:`core training <tutorials/getting_started/core_training>`.
The goal of this tutorial is for you to get an insight of the most important parts of the Odoo
development framework while developing your own Odoo module to manage real estate assets. The
chapters should be followed in their given order since they cover the development of a new Odoo
application from scratch in an incremental way. In other words, each chapter depends on the previous
one.
.. attention::
Are you following this training as part of your technical onboarding as an Odoo employee? Then,
we ask you to complete the first part of the training before joining your new team and the second
part the month after.
All topics are built around a business case we will enhance along the way. The reader is expected
to actively take part in the training by writing the solution for each exercise.
Are you following this tutorial as part of your technical onboarding as an Odoo employee? Then,
we ask you to complete all the chapters before joining your new team.
Ready? Let's get started!
.. _tutorials/getting_started/core_training:
Core training
=============
.. toctree::
:caption: Advanced Topics
:titlesonly:
:glob:
getting_started/0*
getting_started/1*
* :doc:`getting_started/01_architecture`
* :doc:`getting_started/02_setup`
* :doc:`getting_started/03_newapp`
@ -61,24 +45,3 @@ Core training
* :doc:`getting_started/14_other_module`
* :doc:`getting_started/15_qwebintro`
* :doc:`getting_started/16_guidelines_pr`
.. _tutorials/getting_started/advanced_topics:
Advanced topics
===============
.. toctree::
:caption: Advanced Topics
:titlesonly:
getting_started/B_acl_irrules
getting_started/C_data
getting_started/E_unittest
getting_started/J_reports
getting_started/K_dashboard
* :doc:`getting_started/B_acl_irrules`
* :doc:`getting_started/C_data`
* :doc:`getting_started/E_unittest`
* :doc:`getting_started/J_reports`
* :doc:`getting_started/K_dashboard`

View File

@ -78,8 +78,6 @@ Static web data
None of these elements are mandatory. Some modules may only add data files (e.g. country-specific
accounting configuration), while others may only add business objects. During this training, we will
create business objects, object views and data files.
:ref:`Web controllers <tutorials/getting_started/G_website>` and
:ref:`static web data <tutorials/getting_started/I_jswidget>` are advanced topics.
Module structure
----------------

View File

@ -9,8 +9,8 @@ intended to store business data. In a business application such as Odoo, one of
to consider is who\ [#who]_ can access the data. Odoo provides a security mechanism to allow access
to the data for specific groups of users.
The topic of security is covered in more detail in :ref:`tutorials/getting_started/B_acl_irrules`.
This chapter aims to cover the minimum required for our new module.
The topic of security is covered in more detail in :doc:`../restrict_data_access`. This chapter aims
to cover the minimum required for our new module.
Data Files (CSV)
================
@ -104,9 +104,7 @@ Here is an example for our previous ``test.model``:
- ``model_id/id`` refers to the model which the access right applies to. The standard way to refer
to the model is ``model_<model_name>``, where ``<model_name>`` is the ``_name`` of the model
with the ``.`` replaced by ``_``. Seems cumbersome? Indeed it is...
- ``group_id/id`` refers to the group which the access right applies to. We will cover the concept
of groups in the :ref:`advanced topic <tutorials/getting_started/N_security>` dedicated to the
security.
- ``group_id/id`` refers to the group which the access right applies to.
- ``perm_read,perm_write,perm_create,perm_unlink``: read, write, create and unlink permissions
.. exercise:: Add access rights.

View File

@ -1,9 +0,0 @@
:orphan:
.. _tutorials/getting_started/A_i18n:
================================
Advanced A: Internationalization
================================
Hopefully, this topic will be written soon :-)

View File

@ -1,9 +0,0 @@
:orphan:
.. _tutorials/getting_started/D_mixins:
==================
Advanced D: Mixins
==================
Hopefully, this topic will be written soon :-)

View File

@ -1,9 +0,0 @@
:orphan:
.. _tutorials/getting_started/F_jstour:
====================
Advanced F: JS Tours
====================
Hopefully, this topic will be written soon :-)

View File

@ -1,9 +0,0 @@
:orphan:
.. _tutorials/getting_started/G_website:
=================================
Advanced G: Controllers & Website
=================================
Hopefully, this topic will be written soon :-)

View File

@ -1,9 +0,0 @@
:orphan:
.. _tutorials/getting_started/H_adv_views:
==========================
Advanced H: Advanced Views
==========================
Hopefully, this topic will be written soon :-)

View File

@ -1,9 +0,0 @@
:orphan:
.. _tutorials/getting_started/I_jswidget:
============================
Advanced I: Custom JS Widget
============================
Hopefully, this topic will be written soon :-)

View File

@ -1,9 +0,0 @@
:orphan:
.. _tutorials/getting_started/L_cron:
======================================
Advanced L: Scheduled & Server Actions
======================================
Hopefully, this topic will be written soon :-)

View File

@ -1,9 +0,0 @@
:orphan:
.. _tutorials/getting_started/M_migration:
======================
Advanced M: Migrations
======================
Hopefully, this topic will be written soon :-)

View File

@ -1,9 +0,0 @@
:orphan:
.. _tutorials/getting_started/N_security:
====================
Advanced N: Security
====================
Hopefully, this topic will be written soon :-)

View File

@ -1,9 +0,0 @@
:orphan:
.. _tutorials/getting_started/O_perf:
========================
Advanced O: Performances
========================
Hopefully, this topic will be written soon :-)

View File

@ -1,21 +1,14 @@
.. _tutorials/getting_started/J_reports:
=================
Build PDF Reports
=================
=======================
Advanced J: PDF Reports
=======================
.. warning::
This tutorial assumes you have completed the :ref:`Core Training <tutorials/getting_started>`
and have installed :ref:`wkhtmltopdf <setup/install/source/linux/prepare>`.
To follow the exercise, it is recommended that you fetch the branch
{CURRENT_MAJOR_BRANCH}-core from the repository XXX, it
contains a version of the module created during the core training we can use
as a starting point.
.. important::
This tutorial is an extension of the :doc:`getting_started` tutorial. Make sure you have
completed it and use the `estate` module you have built as a base for the exercises in this
tutorial.
We were previously :ref:`introduced to QWeb <tutorials/getting_started/15_qwebintro>`
in the Core Training where it was used to build a kanban view. Now we will expand on one of QWeb's
where it was used to build a kanban view. Now we will expand on one of QWeb's
other main uses: creating PDF reports. A common business requirement is the ability to create documents
to send to customers and to use internally. These reports can be used to summarize and display
information in an organized template to support the business in different ways. Odoo
@ -57,8 +50,8 @@ Therefore, it is expected that your work tree will look something like this:
Note that you will often see other non-QWeb and non-XML files containing "report" in their name also within
the report folder. These are unrelated to the reports covered in this tutorial and are covered in
:ref:`another advanced topic <tutorials/getting_started/K_dashboard>`. For now you can think of them
as customized views that use direct SQL queries (sometimes referred to as SQL Views).
the :doc:`dashboards` tutorial. For now you can think of them as customized views that use direct
SQL queries (sometimes referred to as SQL Views).
Don't forget to add whatever files your template and action view will be into to your ``__manifest__.py``.
In this case, you will want to add the files to the ``data`` list and remember that the files listed in a manifest
@ -72,7 +65,7 @@ Basic Report
**Goal**: at the end of this section, we will can print a report that displays all offers for a
property.
.. image:: J_reports/simple_report.png
.. image:: pdf_reports/simple_report.png
:align: center
:alt: Simple PDF report
@ -92,8 +85,8 @@ or all of your expected use cases. A good representation set for our simple repo
If you don't have a set of data like this already, you can either:
* Complete :ref:`tutorials/getting_started/C_data` (if you haven't done so already) and add the
extra cases to your demo data (you may need to create a new database to load in the demo data).
* Complete the :doc:`define_module_data` tutorial (if you haven't done so already) and add the extra
cases to your demo data (you may need to create a new database to load in the demo data).
* Manually create the data in your database.
* Copy this `data file <https://github.com/odoo/technical-training-solutions/blob/{CURRENT_MAJOR_BRANCH}-J_reports/estate/data/estate_demo.xml>`__
into a new directory (data) in your estate module and copy
@ -194,7 +187,7 @@ that only make sense under specific conditions. For example, if we wanted to mak
report, then we can link it to a "Print Sale Info" button that appears in the form view only when
the property is "Sold".
.. image:: J_reports/print_menu.png
.. image:: pdf_reports/print_menu.png
:align: center
:alt: Print Menu Button
@ -228,7 +221,7 @@ Sub-templates
**Goal**: at the end of this section, we will have a sub-template that we use in 2 reports.
.. image:: J_reports/report_subtemplate.png
.. image:: pdf_reports/report_subtemplate.png
:align: center
:alt: Report using a subtemplate
@ -264,7 +257,7 @@ Report Inheritance
**Goal**: at the end of this section, we will inherit the property report in the ``estate_account``
module.
.. image:: J_reports/inherited_report.png
.. image:: pdf_reports/inherited_report.png
:align: center
:alt: An inherited report

View File

Before

Width:  |  Height:  |  Size: 33 KiB

After

Width:  |  Height:  |  Size: 33 KiB

View File

Before

Width:  |  Height:  |  Size: 37 KiB

After

Width:  |  Height:  |  Size: 37 KiB

View File

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 46 KiB

View File

@ -1,17 +1,11 @@
.. _tutorials/getting_started/B_acl_irrules:
=======================
Restrict access to data
=======================
================================
Advanced B: ACL and Record Rules
================================
.. warning::
This tutorial assumes you have completed the :ref:`Core Training <tutorials/getting_started>`.
To follow the exercise, it is recommended that you fetch the branch
{CURRENT_MAJOR_BRANCH}-core from the repository XXX, it
contains a version of the module created during the core training we can use
as a starting point.
.. important::
This tutorial is an extension of the :doc:`getting_started` tutorial. Make sure you have
completed it and use the `estate` module you have built as a base for the exercises in this
tutorial.
So far we have mostly concerned ourselves with implementing useful features.
However in most business scenarios *security* quickly becomes a concern:
@ -82,8 +76,8 @@ This baseline seems sufficient for us:
which are not specifically under the care of any agent.
In keeping with Odoo's data-driven nature, a group is no more than a record of
the ``res.groups`` model. They are normally part of a module's :ref:`master data
<tutorials/getting_started/C_data>`, defined in one of the module's data files.
the ``res.groups`` model. They are normally part of a module's :doc:`master data
<define_module_data>`, defined in one of the module's data files.
As simple example `can be found here <https://github.com/odoo/odoo/blob/532c083cbbe0ee6e7a940e2bdc9c677bd56b62fa/addons/hr/security/hr_security.xml#L9-L14>`_.
@ -117,7 +111,7 @@ As simple example `can be found here <https://github.com/odoo/odoo/blob/532c083c
If you go to :menuselection:`Settings --> Manage Users` and open the
``admin`` user ("Mitchell Admin"), you should see a new section:
.. figure:: B_acl_irrules/groups.png
.. figure:: restrict_data_access/groups.png
Set the admin user to be a *Real Estate manager*.
@ -130,7 +124,7 @@ As simple example `can be found here <https://github.com/odoo/odoo/blob/532c083c
a password), as the real-estate agent you should only see the real estate
application, and possibly the Discuss (chat) application:
.. figure:: B_acl_irrules/agent.png
.. figure:: restrict_data_access/agent.png
Access Rights
=============
@ -280,7 +274,7 @@ Bypassing Security
If you try to mark a property as "sold" as the real estate agent, you should get
an access error:
.. figure:: B_acl_irrules/error.png
.. figure:: restrict_data_access/error.png
This happens because ``estate_account`` tries to create an invoice during the
process, but creating an invoice requires the right to all invoice management.
@ -379,7 +373,7 @@ Explicit security checks can be performed by:
Re-run the bypass script, check that the error occurs before the print.
.. _tutorials/getting_started/B_acl_irrules/multicompany:
.. _tutorials/restrict_data_access/multicompany:
Multi-company security
======================
@ -476,7 +470,7 @@ or a *visibility* feature before using it:
* *Visibility* features mean a user can still access the model or record
otherwise, either through an other part of the interface or by :doc:`perform
operations remotely using RPC <../../api/external_api>`, things might just not be
operations remotely using RPC <../api/external_api>`, things might just not be
visible in the web interface in some contexts.
* *Security* features mean a user can not access records, fields or operations.

View File

Before

Width:  |  Height:  |  Size: 9.9 KiB

After

Width:  |  Height:  |  Size: 9.9 KiB

View File

Before

Width:  |  Height:  |  Size: 8.2 KiB

After

Width:  |  Height:  |  Size: 8.2 KiB

View File

Before

Width:  |  Height:  |  Size: 9.7 KiB

After

Width:  |  Height:  |  Size: 9.7 KiB

View File

@ -1,13 +1,11 @@
.. _tutorials/getting_started/E_unittest:
===================================
Safeguard your code with unit tests
===================================
=============================
Advanced E: Python Unit Tests
=============================
.. tip:: This tutorial assumes you followed the Core Training.
To do the exercise, fetch the branch {CURRENT_MAJOR_BRANCH}-core from the repository XXX.
It contains a basic module we will use as a starting point
.. important::
This tutorial is an extension of the :doc:`getting_started` tutorial. Make sure you have
completed it and use the `estate` module you have built as a base for the exercises in this
tutorial.
**Reference**:
`Odoo's Test Framework: Learn Best Practices <https://www.youtube.com/watch?v=JEIscps0OOQ>`__

View File

@ -56,11 +56,11 @@ developer/howtos/rdtraining/13_inheritance.rst developer/tutorials/getting_start
developer/howtos/rdtraining/14_other_module.rst developer/tutorials/getting_started/14_other_module.rst # reorganize the developer doc
developer/howtos/rdtraining/15_qwebintro.rst developer/tutorials/getting_started/15_qwebintro.rst # reorganize the developer doc
developer/howtos/rdtraining/16_guidelines_pr.rst developer/tutorials/getting_started/16_guidelines_pr.rst # reorganize the developer doc
developer/howtos/rdtraining/B_acl_irrules.rst developer/tutorials/getting_started/B_acl_irrules.rst # reorganize the developer doc
developer/howtos/rdtraining/C_data.rst developer/tutorials/getting_started/C_data.rst # reorganize the developer doc
developer/howtos/rdtraining/E_unittest.rst developer/tutorials/getting_started/E_unittest.rst # reorganize the developer doc
developer/howtos/rdtraining/J_reports.rst developer/tutorials/getting_started/J_reports.rst # reorganize the developer doc
developer/howtos/rdtraining/K_dashboard.rst developer/tutorials/getting_started/K_dashboard.rst # reorganize the developer doc
developer/howtos/rdtraining/B_acl_irrules.rst developer/tutorials/restrict_data_access.rst # reorganize the developer doc
developer/howtos/rdtraining/C_data.rst developer/tutorials/define_module_data.rst # reorganize the developer doc
developer/howtos/rdtraining/E_unittest.rst developer/tutorials/unit_tests.rst # reorganize the developer doc
developer/howtos/rdtraining/J_reports.rst developer/tutorials/pdf_reports.rst # reorganize the developer doc
developer/howtos/rdtraining/K_dashboard.rst developer/tutorials/dashboards.rst # reorganize the developer doc
# developer/misc