|
1 | | -============================ |
2 | | -Chapter 2: A New Application |
3 | | -============================ |
| 1 | +.. todo: merge with chap 3? |
| 2 | +.. todo: update title? |
4 | 3 |
|
5 | | -The purpose of this chapter is to lay the foundation for the creation of a completely new Odoo module. |
6 | | -We will start from scratch with the minimum needed to have our module recognized by Odoo. |
7 | | -In the upcoming chapters, we will progressively add features to build a realistic business case. |
| 4 | +============================== |
| 5 | +Chapter 2: Lay the foundations |
| 6 | +============================== |
8 | 7 |
|
9 | | -The Real Estate Advertisement module |
10 | | -==================================== |
| 8 | +.. todo introduction text |
11 | 9 |
|
12 | | -Our new module will cover a business area which is very specific and therefore not included in the |
13 | | -standard set of modules: real estate. It is worth noting that before |
14 | | -developing a new module, it is good practice to verify that Odoo doesn't already provide a way |
15 | | -to answer the specific business case. |
| 10 | +Install the app |
| 11 | +=============== |
16 | 12 |
|
17 | | -Here is an overview of the main list view containing some advertisements: |
| 13 | +If you followed the :doc:`setup guide <../setup_guide>` carefully, you should now have a running |
| 14 | +Odoo server with the `odoo/tutorials` repository in the `addons-path`, and be logged in as an |
| 15 | +administrator. |
18 | 16 |
|
19 | | -.. image:: 02_newapp/overview_list_view_01.png |
20 | | - :align: center |
21 | | - :alt: List view 01 |
| 17 | +**Let's install our real estate app!** In your browser, open Odoo and navigate to |
| 18 | +:menuselection:`Apps`. Search for :guilabel:`Real Estate` and click :guilabel:`Activate`. |
22 | 19 |
|
23 | | -The top area of the form view summarizes important information for the property, such as the name, |
24 | | -the property type, the postcode and so on. The first tab contains information describing the |
25 | | -property: bedrooms, living area, garage, garden... |
| 20 | +Nothing has changed? That's normal; the `real_estate` module we just installed is currently an empty |
| 21 | +shell. It only contains two files: |
26 | 22 |
|
27 | | -.. image:: 02_newapp/overview_form_view_01.png |
28 | | - :align: center |
29 | | - :alt: Form view 01 |
| 23 | +- An empty :file:`__init__.py` file to make Python treat the :file:`real_estate` directory as a |
| 24 | + package. |
| 25 | +- The :file:`__manifest__.py` file that declares the :file:`real_estate` Python package as an Odoo |
| 26 | + module. |
30 | 27 |
|
31 | | -The second tab lists the offers for the property. We can see here that potential buyers can make |
32 | | -offers above or below the expected selling price. It is up to the seller to accept an offer. |
| 28 | +Those two files are the minimum requirements for a directory to be considered as an Odoo module. |
33 | 29 |
|
34 | | -.. image:: 02_newapp/overview_form_view_02.png |
35 | | - :align: center |
36 | | - :alt: Form view 02 |
| 30 | +.. exercise:: |
| 31 | + Search for each key of our :file:`__manifest__.py` file in the :ref:`reference documentation |
| 32 | + <reference/module/manifest>` and understand the base metadata that defines our module. |
37 | 33 |
|
38 | | -Here is a quick video showing the workflow of the module. |
| 34 | +.. seealso:: |
| 35 | + `The manifest of the Sales app <{GITHUB_PATH}/addons/sale/__manifest__.py>`_ |
39 | 36 |
|
40 | | -Hopefully, this video will be recorded soon :-) |
| 37 | +Create the first model |
| 38 | +====================== |
41 | 39 |
|
42 | | -Prepare the addon directory |
43 | | -=========================== |
| 40 | +Now that our module is recognized by Odoo, it's time to build towards the business features. Data is |
| 41 | +essential for any real-world application, and our real estate module won't be an exception. |
44 | 42 |
|
45 | | -**Reference**: the documentation related to this topic can be found in |
46 | | -:ref:`manifest <reference/module/manifest>`. |
| 43 | +To store data effectively, we need two things: a way to define the structure of that data, and a |
| 44 | +system to store and manipulate it. Fortunately, the server framework of Odoo comes equipped with the |
| 45 | +perfect tool: the :abbr:`ORM (Object Relational Mapper)` layer. |
47 | 46 |
|
48 | | -.. note:: |
| 47 | +The ORM simplifies data access and manipulation by allowing you to define **models**. Models act as |
| 48 | +blueprints for your data; they define the structure and organization of information within your |
| 49 | +module. You can see them as templates that specify what kind of data your module will handle. For |
| 50 | +example, real estate properties, owners, or tenants. |
49 | 51 |
|
50 | | - **Goal**: the goal of this section is to have Odoo recognize our new module, which will |
51 | | - be an empty shell for now. It will be listed in the Apps: |
| 52 | +Each model is made of smaller components called **fields**. You can see them as the individual |
| 53 | +characteristics that describe your data. Fields allow you to define the relevant data your |
| 54 | +application needs to capture and manage. In the case of real estate properties, some example fields |
| 55 | +could be: the property name, the type (house, apartment, etc.), the floor area... |
52 | 56 |
|
53 | | - .. image:: 02_newapp/app_in_list.png |
54 | | - :align: center |
55 | | - :alt: The new module appears in the list |
| 57 | +In Odoo, models are represented by Python classes that inherit from the `models.Model` class |
| 58 | +provided by the ORM. Within these model classes, fields are defined as class attributes. Fields come |
| 59 | +in a variety of types like `String`, `Float`, `Boolean`, and more. |
56 | 60 |
|
57 | | -The first step of module creation is to create its directory. In the `tutorials` |
58 | | -directory, add a new directory :file:`estate`. |
| 61 | +.. todo: add example with a fake product model |
| 62 | +.. todo: add exercise to create the real.estate.property model |
| 63 | +.. todo: show the impact on SQL: table, columns |
59 | 64 |
|
60 | | -A module must contain at least 2 files: the ``__manifest__.py`` file and a ``__init__.py`` file. |
61 | | -The ``__init__.py`` file can remain empty for now and we'll come back to it in the next chapter. |
62 | | -On the other hand, the ``__manifest__.py`` file must describe our module and cannot remain empty. |
63 | | -Its only required field is the ``name``, but it usually contains much more information. |
| 65 | +---- |
64 | 66 |
|
65 | | -Take a look at the |
66 | | -`CRM file <https://github.com/odoo/odoo/blob/fc92728fb2aa306bf0e01a7f9ae1cfa3c1df0e10/addons/crm/__manifest__.py#L1-L67>`__ |
67 | | -as an example. In addition to providing the description of the module (``name``, ``category``, |
68 | | -``summary``, ``website``...), it lists its dependencies (``depends``). A dependency means that the |
69 | | -Odoo framework will ensure that these modules are installed before our module is installed. Moreover, if |
70 | | -one of these dependencies is uninstalled, then our module and **any other that depends on it will also |
71 | | -be uninstalled**. Think about your favorite Linux distribution package manager |
72 | | -(``apt``, ``dnf``, ``pacman``...): Odoo works in the same way. |
73 | | - |
74 | | -.. exercise:: Create the required addon files. |
75 | | - |
76 | | - Create the following folders and files: |
77 | | - |
78 | | - - ``/home/$USER/src/tutorials/estate/__init__.py`` |
79 | | - - ``/home/$USER/src/tutorials/estate/__manifest__.py`` |
80 | | - |
81 | | - The ``__manifest__.py`` file should only define the name and the dependencies of our modules. |
82 | | - The only necessary framework module for now is ``base``. |
83 | | - |
84 | | - |
85 | | -Restart the Odoo server and go to Apps. Click on Update Apps List, search for ``estate`` and... |
86 | | -tadaaa, your module appears! Did it not appear? Maybe try removing the default 'Apps' filter ;-) |
87 | | - |
88 | | -.. warning:: |
89 | | - Remember to enable the :ref:`developer mode <developer-mode>` as explained in the previous |
90 | | - chapter. You won't see the :guilabel:`Update Apps List` button otherwise. |
91 | | - |
92 | | -.. exercise:: Make your module an 'App'. |
93 | | - |
94 | | - Add the appropriate key to your ``__manifest__.py`` so that the module appears when the 'Apps' |
95 | | - filter is on. |
96 | | - |
97 | | -You can even install the module! But obviously it's an empty shell, so no menu will appear. |
98 | | - |
99 | | -All good? If yes, then let's :doc:`create our first model <03_basicmodel>`! |
| 67 | +.. todo: add incentive to move to the next chapter |
0 commit comments