您的第一个模块

Overview

本章将帮助您创建第一个 Odoo 模块,并将其部署到您的 Odoo.sh 项目中。

This tutorial requires you created a project on Odoo.sh, and you know your Github repository’s URL.

Git 和 GitHub 的基本用法已进行说明。

以下假设被采用:

  • ~/src 是存放与您的 Odoo 项目相关的 Git 仓库的目录,

  • Odoo 是 GitHub 用户,

  • odoo-addons 是 GitHub 仓库,

  • feature-1 是一个开发分支的名称,

  • master 是生产分支的名称,

  • my_module 是模块的名称。

将这些替换为您的选择值。

创建开发分支

来自 Odoo.sh

在分支视图中:

  • 点击开发阶段旁边的 + 按钮,

  • 在“Fork”选择中选择分支 master

  • 在“收件人”输入框中输入 feature-1

    |图片1| |图片2|

一旦构建完成,您就可以访问编辑器并导航到文件夹 ~/src/user 以查看您的开发分支的代码。

../../../_images/firstmodule-development-editor.png ../../../_images/firstmodule-development-editor-interface.png

从您的计算机

在您的计算机上克隆您的 GitHub 仓库:

$ mkdir ~/src
$ cd ~/src
$ git clone https://github.com/odoo/odoo-addons.git
$ cd ~/src/odoo-addons

创建新分支:

$ git checkout -b feature-1 master

创建模块结构

模块搭建

虽然不是必须的,但代码模板可以避免设置基本 Odoo 模块结构的繁琐工作。你可以使用可执行文件 odoo-bin 来生成一个新的模块。

通过 Odoo.sh 编辑器,在终端中:

$ odoo-bin scaffold my_module ~/src/user/

或者,如果您在自己的计算机上安装了 Odoo(详见 Odoo 安装指南):

$ ./odoo-bin scaffold my_module ~/src/odoo-addons/

如果你不想麻烦地在自己的电脑上安装 Odoo,你也可以 下载这个模块结构模板,并将其中所有 my_module 的出现替换为你选择的名称。

将生成以下结构:

my_module
├── __init__.py
├── __manifest__.py
├── controllers
│   ├── __init__.py
│   └── controllers.py
├── demo
│   └── demo.xml
├── models
│   ├── __init__.py
│   └── models.py
├── security
│   └── ir.model.access.csv
└── views
    ├── templates.xml
    └── views.xml

警告

不要在模块名称中使用下划线(_)以外的特殊字符,甚至不能使用连字符(-)。此名称用于你的模块的 Python 类,而在 Python 中,类名包含下划线以外的特殊字符是无效的。

取消注释文件内容:

  • models/models.py,模型及其字段的示例,

  • views/views.xml,包含一个树视图和一个表单视图,以及打开它们的菜单,

  • 演示/演示.xml,上述示例模型的演示记录,

  • controllers/controllers.py,一个实现一些路由的控制器示例,

  • views/templates.xml,上述控制器路由使用的两个示例 QWeb 视图,

  • __manifest__.py,您的模块的清单文件,包括其标题、描述和要加载的数据文件。您只需取消注释访问控制列表数据文件即可:

    # 'security/ir.model.access.csv',
    

手动地

如果你想手动创建你的模块结构,可以参考 服务器框架 101 教程来了解模块的结构以及每个文件的内容。

推送开发分支

暂存要提交的更改

$ git add my_module

提交您的更改

$ git commit -m "My first module"

将您的更改推送到远程仓库

从 Odoo.sh 编辑器终端中:

$ git push https HEAD:feature-1

The above command is explained in the section Commit & Push your changes of the Online Editor chapter. It includes the explanation regarding the fact you will be prompted to type your username and password, and what to do if you use the two-factor authentication.

或者,从您的计算机终端:

$ git push -u origin feature-1

您只需要在第一次推送时指定 -u origin feature-1。从那时起,要将您计算机上的后续更改推送到远程仓库,只需使用即可

$ git push

测试您的模块

您的分支应在项目中的开发分支列表中显示。

../../../_images/firstmodule-test-branch.png

在项目的分支视图中,您可以点击左侧导航面板中的分支名称以访问其历史记录。

../../../_images/firstmodule-test-branch-history.png

你可以在这里看到你刚刚推送的更改,包括你设置的评论。数据库准备就绪后,可以通过点击 连接 按钮访问它。

../../../_images/firstmodule-test-database.png

如果您的 Odoo.sh 项目已配置为自动安装您的模块,您将直接在数据库应用中看到它。否则,它将在应用列表中可供安装。

你可以随后对你的模块进行测试,创建新的记录,并测试你的功能和按钮。

使用生产数据进行测试

您需要一个生产数据库才能进行此步骤。如果您尚未拥有,可以创建一个。

在您使用演示数据在开发版本中测试完模块并认为其已准备就绪后,可以使用预发布分支使用生产数据进行测试。

你可以选择以下方式之一:

  • 通过将你的开发分支拖放到“staging”部分标题上,将其变为暂存分支。

    ../../../_images/firstmodule-test-devtostaging.png
  • 将其合并到现有的暂存分支中,通过将它拖放到给定的暂存分支上。

    ../../../_images/firstmodule-test-devinstaging.png

你也可以使用 git merge 命令来合并你的分支。

这将创建一个新的暂存构建,该构建将复制生产数据库,并使用包含您分支最新更改的服务器来运行。

../../../_images/firstmodule-test-mergedinstaging.png

数据库准备就绪后,您可以使用“连接”按钮访问它。

安装您的模块

您的模块将不会自动安装,您需要从应用菜单中手动安装它。实际上,预发布构建的目的是测试您的更改在生产环境中的行为,而在生产环境中,您不希望模块自动安装,而是按需安装。

您的模块可能不会直接出现在要安装的应用列表中,您需要先更新应用列表:

  • 启用 开发者模式

  • 在应用菜单中,点击 更新应用列表 按钮,

  • 在出现的对话框中,点击 更新 按钮。

    ../../../_images/firstmodule-test-updateappslist.png

您的模块将随后出现在可用应用列表中。

../../../_images/firstmodule-test-mymoduleinapps.png

在生产环境中部署

在您使用生产数据在预发布分支中测试完模块,并认为其已准备好用于生产环境后,可以将您的分支合并到生产分支中。

将您的暂存分支拖放到生产分支上。

../../../_images/firstmodule-test-mergeinproduction.png

你也可以使用 git merge 命令来合并你的分支。

这将合并您的测试分支的最新更改到生产分支,并使用这些最新更改更新您的生产服务器。

../../../_images/firstmodule-test-mergedinproduction.png

数据库准备就绪后,您可以使用“连接”按钮访问它。

安装您的模块

您的模块将不会自动安装,您需要按照以下说明手动安装:关于在测试数据库中安装您的模块的上述部分

添加更改

本节说明如何通过在模型中添加新字段来在您的模块中进行更改并将其部署。

从 Odoo.sh 编辑器中,
  • 浏览到您的模块文件夹 ~/src/user/my_module

  • 然后,打开文件 models/models.py

或者从您的计算机,
  • 使用你喜欢的文件浏览器浏览到你的模块文件夹 ~/src/odoo-addons/my_module

  • 然后,使用您选择的编辑器(如 AtomSublime TextPyCharmvim 等)打开文件 models/models.py

然后,在描述字段之后

description = fields.Text()

添加日期时间字段

start_datetime = fields.Datetime('Start time', default=lambda self: fields.Datetime.now())

然后,打开文件 views/views.xml

之后

<field name="value2"/>

添加

<field name="start_datetime"/>

这些更改通过在表中添加一列来修改数据库结构,并修改存储在数据库中的视图。

为了在现有数据库(如您的生产数据库)中应用这些更改,需要更新该模块。

如果您希望在您推送更改时由 Odoo.sh 平台自动执行更新,请在模块的清单文件中提高模块版本。

打开模块清单文件 __manifest__.py

Replace

'version': '0.1',

'version': '0.2',

平台将检测版本的变化,并在新修订版部署时触发模块的更新。

浏览到你的 Git 文件夹。

然后,在 Odoo.sh 终端中:

$ cd ~/src/user/

或者,从您的计算机终端:

$ cd ~/src/odoo-addons/

然后,将您的更改添加到提交中

$ git add my_module

提交您的更改

$ git commit -m "[ADD] my_module: add the start_datetime field to the model my_module.my_module"

推送您的更改:

从 Odoo.sh 终端中:

$ git push https HEAD:feature-1

或者,从您的计算机终端:

$ git push

平台将为分支 feature-1 创建一个新的构建。

../../../_images/firstmodule-test-addachange-build.png

在您测试完更改后,可以通过将分支拖放到 Odoo.sh 界面中的生产分支上,将您的更改合并到生产分支中。由于您已在清单文件中增加了模块版本,平台将自动更新该模块,您的新字段将立即可用。否则,您也可以在应用列表中手动更新该模块。

使用外部 Python 库

如果您想使用默认未安装的外部 Python 库,可以定义一个 requirements.txt 文件,列出您的模块所依赖的外部库。

注解

  • 无法在 Odoo.sh 数据库上安装或升级系统包(例如 apt 包)。然而,在特定条件下,可以考虑安装某些包。这同样适用于需要系统包进行编译的 Python 模块 以及 第三方 Odoo 模块

  • PostgreSQL 扩展 在 Odoo.sh 中不受支持。

  • 如需更多信息,请查阅我们的 FAQ

该平台将使用此文件自动安装项目所需的 Python 库。

该功能在本节中通过在您的模块中使用 Unidecode 库 进行说明。

在仓库根目录中创建一个文件 requirements.txt

从 Odoo.sh 编辑器中,创建并打开文件 ~/src/user/requirements.txt。

或者,从您的计算机上创建并打开文件 ~/src/odoo-addons/requirements.txt。

添加

unidecode

然后在你的模块中使用这个库,例如用于去除你的模型名称字段中的重音符号。

打开文件 models/models.py

在之前

from odoo import models, fields, api

添加

from unidecode import unidecode

之后

start_datetime = fields.Datetime('Start time', default=lambda self: fields.Datetime.now())

添加

@api.model
def create(self, values):
    if 'name' in values:
        values['name'] = unidecode(values['name'])
    return super(my_module, self).create(values)

def write(self, values):
    if 'name' in values:
        values['name'] = unidecode(values['name'])
    return super(my_module, self).write(values)

添加一个 Python 依赖项需要提高模块版本,以便平台可以安装它。

编辑模块清单 __manifest__.py

Replace

'version': '0.2',

'version': '0.3',

提交您的更改:

$ git add requirements.txt
$ git add my_module
$ git commit -m "[IMP] my_module: automatically remove special chars in my_module.my_module name field"

然后,提交您的更改:

在 Odoo.sh 终端中:

$ git push https HEAD:feature-1

在您的电脑终端中:

$ git push