نخستین ماژول شما

بررسی اجمالی

این فصل به شما کمک می‌کند نخستین ماژول Odoo خود را ایجاد و در پروژهٔ Odoo.sh خود مستقر کنید.

این آموزش نیازمند آن است که یک پروژه در Odoo.sh ایجاد کرده و URL مخزن GitHub خود را بدانید.

استفادهٔ پایه از Git و GitHub توضیح داده شده است.

فرض‌های زیر در نظر گرفته شده است:

• ~/src دایرکتوری‌ای است که مخازن Git مربوط به پروژه‌های Odoo شما در آن قرار دارند،

• odoo کاربر گیت‌هاب است،

• odoo-addons مخزن گیت‌هاب است،

• feature-1 نام یک شاخهٔ توسعه است،

• master نام شاخهٔ تولید است،

• my_module نام ماژول است.

این موارد را با مقادیر دلخواه خود جایگزین کنید.

ایجاد شاخهٔ توسعه

از Odoo.sh

در نمای شاخه‌ها:

• دکمهٔ + کنار مرحلهٔ توسعه را بزنید،

• در بخش Fork شاخهٔ master را انتخاب کنید،

• در ورودی To عبارت feature-1 را تایپ کنید.

  

پس از ایجاد ساخت، می‌توانید به ویرایشگر دسترسی پیدا کنید و به پوشهٔ ~/src/user بروید تا به کد شاخهٔ توسعهٔ خود دسترسی داشته باشید.

از رایانهٔ خود

مخزن گیت‌هاب خود را روی رایانه‌تان clone کنید:

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

یک شاخهٔ جدید ایجاد کنید:

$ git checkout -b feature-1 master

ایجاد ساختار ماژول

ایجاد اسکلت ماژول

اگرچه ضروری نیست، scaffolding خستگی تنظیم ساختار پایهٔ ماژول Odoo را برطرف می‌کند. می‌توانید با استفاده از فایل اجرایی odoo-bin یک ماژول جدید را scaffold کنید.

از ویرایشگر Odoo.sh، در یک ترمینال:

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

یا، از رایانهٔ خود اگر 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

هشدار

برای نام ماژول خود از کاراکترهای ویژهٔ غیر از underscore ( _ ) استفاده نکنید، حتی hyphen ( - ). این نام برای کلاس‌های Python ماژول شما استفاده می‌شود و داشتن نام کلاس‌ها با کاراکترهای ویژهٔ غیر از underscore در Python معتبر نیست.

محتوای فایل‌ها را از حالت کامنت خارج کنید:

• models/models.py، نمونه‌ای از یک مدل به همراه فیلدهای آن،

• views/views.xml، یک نمای درختی و یک نمای فرم، به همراه منوهایی که آن‌ها را باز می‌کنند،

• demo/demo.xml، رکوردهای نمایشی برای مدل نمونهٔ بالا،

• controllers/controllers.py، نمونه‌ای از یک کنترلر که چند مسیر را پیاده‌سازی می‌کند،

• views/templates.xml، دو نمای نمونهٔ qweb که توسط مسیرهای کنترلر بالا استفاده می‌شوند،

• __manifest__.py، manifest ماژول شما، شامل برای مثال عنوان، توضیحات و فایل‌های داده برای بارگذاری. فقط لازم است فایل داده فهرست کنترل دسترسی را از حالت کامنت خارج کنید:

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

دستی

اگر می‌خواهید ساختار ماژول خود را به‌صورت دستی ایجاد کنید، می‌توانید آموزش Server framework 101 را برای درک ساختار یک ماژول و محتوای هر فایل دنبال کنید.

Push کردن شاخهٔ توسعه

تغییرات را برای commit در حالت مرحله قرار دهید

$ git add my_module

تغییرات خود را commit کنید

$ git commit -m "My first module"

تغییرات خود را به مخزن راه‌دور push کنید

از یک ترمینال ویرایشگر Odoo.sh:

$ git push https HEAD:feature-1

دستور بالا در بخش Commit and push changes از صفحهٔ Online editor توضیح داده شده است. این بخش توضیح می‌دهد که از شما خواسته می‌شود نام کاربری و رمز عبور خود را تایپ کنید و اگر از two-factor authentication استفاده می‌کنید چه باید کرد.

یا، از ترمینال رایانهٔ خود:

$ git push -u origin feature-1

فقط برای اولین push باید -u origin feature-1 را مشخص کنید. از آن نقطه به بعد، برای push کردن تغییرات آتی خود از رایانه‌تان، می‌توانید به‌سادگی از این استفاده کنید

$ git push

ماژول خود را آزمایش کنید

شاخهٔ شما باید در شاخه‌های توسعهٔ پروژهٔ شما ظاهر شود.

در نمای شاخه‌های پروژهٔ شما، می‌توانید روی نام شاخه در پنل ناوبری سمت چپ کلیک کنید تا به تاریخچهٔ آن دسترسی پیدا کنید.

می‌توانید تغییراتی را که هم‌اکنون push کرده‌اید، از جمله کامنتی که تنظیم کرده‌اید، در اینجا ببینید. پس از آماده شدن پایگاه داده، می‌توانید با کلیک روی دکمهٔ Connect به آن دسترسی پیدا کنید.

اگر پروژهٔ Odoo.sh شما برای نصب خودکار ماژولتان پیکربندی شده باشد، آن را مستقیماً در میان اپ‌های پایگاه داده خواهید دید. در غیر این صورت، در میان اپ‌های قابل نصب در دسترس خواهد بود.

سپس می‌توانید با ماژول خود کار کنید، رکوردهای جدید بسازید و ویژگی‌ها و دکمه‌های آن را آزمایش کنید.

آزمایش با داده‌های تولیدی

برای این مرحله باید یک پایگاه داده تولیدی داشته باشید. اگر هنوز آن را ندارید، می‌توانید ایجاد کنید.

پس از آنکه ماژول خود را در یک ساخت توسعه با داده‌های دمو آزمایش کردید و باور دارید که آماده است، می‌توانید آن را با داده‌های تولیدی با استفاده از یک شاخهٔ staging آزمایش کنید.

می‌توانید یکی از این کارها را انجام دهید:

• با drag-and-drop شاخهٔ توسعهٔ خود روی عنوان بخش staging، آن را به یک شاخهٔ staging تبدیل کنید.

  

• با drag-and-drop آن روی یک شاخهٔ staging موجود، آن را با آن شاخه merge کنید.

  

همچنین می‌توانید از دستور git merge برای merge کردن شاخه‌های خود استفاده کنید.

این کار یک ساخت staging جدید ایجاد می‌کند که پایگاه دادهٔ تولیدی را تکثیر می‌کند و آن را با یک سرور به‌روزرسانی‌شده با آخرین تغییرات شاخهٔ شما اجرا می‌کند.

پس از آماده شدن پایگاه داده، می‌توانید با استفاده از دکمهٔ Connect به آن دسترسی پیدا کنید.

ماژول خود را نصب کنید

ماژول شما به‌صورت خودکار نصب نخواهد شد، باید آن را از منوی apps نصب کنید. در واقع، هدف ساخت staging آزمایش رفتار تغییرات شما همانند تولید است، و در تولید نمی‌خواهید ماژول شما به‌صورت خودکار نصب شود، بلکه بر اساس درخواست نصب شود.

ممکن است ماژول شما مستقیماً در فهرست اپ‌های قابل نصب ظاهر نشود؛ ابتدا باید فهرست اپ‌های خود را به‌روزرسانی کنید:

• حالت توسعه‌دهنده را فعال‌سازی کنید

• در منوی اپلیکیشن‌ها، روی دکمهٔ به‌روزرسانی فهرست اپ‌ها کلیک کنید،

• در گفتگویی که ظاهر می‌شود، روی دکمهٔ به‌روزرسانی کلیک کنید.

  

سپس ماژول شما در فهرست اپ‌های در دسترس ظاهر می‌شود.

استقرار در تولید

پس از آنکه ماژول خود را در یک شاخهٔ staging با داده‌های تولیدی خود آزمایش کردید و باور دارید که برای تولید آماده است، می‌توانید شاخهٔ خود را در شاخهٔ تولید merge کنید.

شاخهٔ staging خود را با drag-and-drop روی شاخهٔ تولید بیندازید.

همچنین می‌توانید از دستور git merge برای merge کردن شاخه‌های خود استفاده کنید.

این کار آخرین تغییرات شاخهٔ staging شما را در شاخهٔ تولید merge می‌کند و سرور تولید شما را با این آخرین تغییرات به‌روزرسانی می‌کند.

پس از آماده شدن پایگاه داده، می‌توانید با استفاده از دکمهٔ Connect به آن دسترسی پیدا کنید.

ماژول خود را نصب کنید

ماژول شما به‌صورت خودکار نصب نخواهد شد، باید آن را به‌صورت دستی همان‌طور که در بخش بالا دربارهٔ نصب ماژول در پایگاه‌های دادهٔ staging توضیح داده شده نصب کنید.

افزودن یک تغییر

این بخش توضیح می‌دهد چگونه با افزودن یک فیلد جدید به یک مدل تغییری در ماژول خود اعمال و آن را مستقر کنید.

از ویرایشگر Odoo.sh،

• به پوشهٔ ماژول خود ~/src/user/my_module بروید،

• سپس فایل models/models.py را باز کنید.

یا، از رایانهٔ خود،

• از مرورگر فایل دلخواه خود برای رفتن به پوشهٔ ماژول ~/src/odoo-addons/my_module استفاده کنید،

• سپس فایل models/models.py را با ویرایشگر دلخواه خود مانند Atom، Sublime Text، PyCharm، vim و ... باز کنید.

سپس، بعد از فیلد description

description = fields.Text()

یک فیلد datetime اضافه کنید

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

سپس فایل views/views.xml را باز کنید.

بعد

<field name="value2"/>

افزودن

<field name="start_datetime"/>

این تغییرات ساختار پایگاه داده را با افزودن یک ستون به یک جدول تغییر می‌دهند و یک نما ذخیره‌شده در پایگاه داده را اصلاح می‌کنند.

برای اعمال در پایگاه‌های داده موجود، مانند پایگاه دادهٔ تولیدی شما، این تغییرات نیازمند به‌روزرسانی ماژول است.

اگر می‌خواهید به‌روزرسانی به‌صورت خودکار توسط پلتفرم Odoo.sh هنگام push کردن تغییرات شما انجام شود، نسخهٔ ماژول خود را در manifest آن افزایش دهید.

manifest ماژول یعنی __manifest__.py را باز کنید.

جایگزینی

'version': '0.1',

با

'version': '0.2',

پلتفرم تغییر نسخه را تشخیص می‌دهد و به‌روزرسانی ماژول را هنگام استقرار revision جدید آغاز می‌کند.

به پوشهٔ Git خود بروید.

سپس، از یک ترمینال Odoo.sh:

$ cd ~/src/user/

یا، از ترمینال رایانهٔ خود:

$ cd ~/src/odoo-addons/

سپس تغییرات خود را برای commit در حالت مرحله قرار دهید

$ git add my_module

تغییرات خود را commit کنید

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

تغییرات خود را push کنید:

از یک ترمینال Odoo.sh:

$ git push https HEAD:feature-1

یا، از ترمینال رایانهٔ خود:

$ git push

سپس پلتفرم یک ساخت جدید برای شاخهٔ feature-1 ایجاد می‌کند.

پس از آزمایش تغییرات خود، می‌توانید تغییرات خود را در شاخهٔ تولید merge کنید، برای مثال با drag-and-drop شاخه روی شاخهٔ تولید در رابط Odoo.sh. از آنجا که نسخهٔ ماژول را در manifest افزایش داده‌اید، پلتفرم ماژول را به‌صورت خودکار به‌روزرسانی می‌کند و فیلد جدید شما مستقیماً در دسترس خواهد بود. در غیر این صورت می‌توانید ماژول را به‌صورت دستی در فهرست اپ‌ها به‌روزرسانی کنید.

استفاده از یک کتابخانهٔ Python بیرونی

اگر می‌خواهید از یک کتابخانهٔ Python بیرونی که به‌صورت پیش‌فرض نصب نشده استفاده کنید، می‌توانید یک فایل requirements.txt تعریف کنید که کتابخانه‌های بیرونی موردنیاز ماژول‌های شما را فهرست کند.

توجه

• نصب یا ارتقای بسته‌های سیستم روی یک پایگاه دادهٔ Odoo.sh امکان‌پذیر نیست (مثلاً بسته‌های apt). با این حال، در شرایط خاص، بسته‌ها می‌توانند برای نصب در نظر گرفته شوند. این موضوع همچنین برای ماژول‌های Python که برای کامپایل خود به بسته‌های سیستم نیاز دارند و ماژول‌های Odoo شخص ثالث نیز اعمال می‌شود.

• افزونه‌های PostgreSQL در Odoo.sh پشتیبانی نمی‌شوند.

• برای اطلاعات بیشتر، FAQ ما را ببینید.

پلتفرم از این فایل برای نصب خودکار کتابخانه‌های Python مورد نیاز پروژهٔ شما استفاده می‌کند.

این ویژگی در این بخش با استفاده از Unidecode library در ماژول شما توضیح داده شده است.

یک فایل requirements.txt در پوشهٔ ریشهٔ مخزن خود ایجاد کنید

از ویرایشگر Odoo.sh، فایل ~/src/user/requirements.txt را ایجاد و باز کنید.

یا، از رایانهٔ خود، فایل ~/src/odoo-addons/requirements.txt را ایجاد و باز کنید.

افزودن

unidecode

سپس از کتابخانه در ماژول خود استفاده کنید، برای مثال برای حذف accent‌ها از کاراکترهای فیلد name مدل خود.

فایل 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, vals_list):
    for vals in vals_list:
        if 'name' in vals:
            vals['name'] = unidecode(vals['name'])
    return super().create(vals_list)

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

افزودن یک وابستگی Python نیازمند افزایش نسخهٔ ماژول است تا پلتفرم بتواند آن را نصب کند.

manifest ماژول یعنی __manifest__.py را ویرایش کنید

جایگزینی

'version': '0.2',

با

'version': '0.3',

تغییرات خود را مرحله و commit کنید:

$ 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"

سپس تغییرات خود را push کنید:

در یک ترمینال Odoo.sh:

$ git push https HEAD:feature-1

در ترمینال رایانهٔ خود:

$ git push