ماژول اول شما¶
نمای کلی¶
این فصل به شما کمک می‌کند اولین ماژول Odoo خود را ایجاد کرده و آن را در پروژه Odoo.sh خود مستقر کنید.
این آموزش نیاز دارد: شما یک پروژه در Odoo.sh ایجاد کرده‌اید و آدرس URL مخزن Github خود را می‌دانید.
استفاده‌ی پایه‌ای از گیت و گیت‌هاب توضیح داده شده است.
فرضیات زیر در نظر گرفته شده‌اند:
~/src دایرکتوری است که مخازن گیت مرتبط با پروژه‌های Odoo شما در آن قرار دارند،
odoo کاربر گیت‌هاب است،
odoo-addons مخزن گیت‌هاب است،
feature-1 نام یک شاخه توسعه است،
master نام شاخه تولید است،
my_module نام ماژول است.
این‌ها را با مقادیر دلخواه خود جایگزین کنید.
ایجاد شاخه توسعه¶
از Odoo.sh¶
در نمای شعب:
دکمه
+کنار مرحله توسعه را فشار دهید،شاخه master را در انتخاب Fork انتخاب کنید.
در ورودی به، ویژگی-1 را وارد کنید.
پس از ایجاد بیلد، می‌توانید به ویرایشگر دسترسی پیدا کنید و به پوشه ~/src/user بروید تا به کد شاخه توسعه خود دسترسی داشته باشید.
از رایانه شما¶
مخزن گیت‌هاب خود را روی رایانه‌تان کلون کنید:
$ mkdir ~/src
$ cd ~/src
$ git clone https://github.com/odoo/odoo-addons.git
$ cd ~/src/odoo-addons
ایجاد یک شعبه جدید:
$ git checkout -b feature-1 master
ایجاد ساختار ماژول¶
داربست‌بندی ماژول¶
اگرچه ضروری نیست، اسکافلدینگ از یکنواختی تنظیم ساختار پایه ماژول اودو جلوگیری می‌کند. شما می‌توانید یک ماژول جدید را با استفاده از فایل اجرایی odoo-bin اسکافلد کنید.
از ویرایشگر Odoo.sh، در یک ترمینال:
$ odoo-bin scaffold my_module ~/src/user/
یا، از رایانه خود، اگر یک نصب اودوو دارید:
$ ./odoo-bin scaffold my_module ~/src/odoo-addons/
اگر نمی‌خواهید خودتان اودو را روی کامپیوتر نصب کنید، می‌توانید این قالب ساختار ماژول را دانلود کنید و در آن، هر مورد از 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
هشدار
برای نام ماژول خود از کاراکترهای خاص به جز زیرخط ( _ ) استفاده نکنید، حتی خط تیره ( - ). این نام برای کلاس‌های پایتون ماژول شما استفاده می‌شود و داشتن نام کلاس‌ها با کاراکترهای خاص به جز زیرخط در پایتون معتبر نیست.
محتوای فایل‌ها را از حالت توضیح خارج کنید:
models/models.py، یک نمونه از مدل با فیلدهای آن
views/views.xml، یک نمای درختی و یک نمای فرمی، همراه با منوهایی که آنها را باز می‌کنند،
demo/demo.xml، رکوردهای نمایشی برای مدل مثال فوق،
controllers/controllers.py، یک مثال از کنترلر که برخی مسیرها را پیاده‌سازی می‌کند،
views/templates.xml، دو نمونه از نماهای qweb که توسط مسیرهای کنترلر بالا استفاده می‌شوند،
__manifest__.py، فایل مانیفست ماژول شما که شامل عنوان، توضیحات و فایل‌های داده‌ای برای بارگذاری است. شما فقط نیاز دارید فایل داده لیست کنترل دسترسی را از حالت کامنت خارج کنید:
# 'security/ir.model.access.csv',
به صورت دستی¶
اگر می‌خواهید ساختار ماژول خود را به صورت دستی ایجاد کنید، می‌توانید آموزش Server framework 101 را دنبال کنید تا ساختار یک ماژول و محتوای هر فایل را درک کنید.
شاخه توسعه را فشار دهید¶
مرحله‌بندی تغییراتی که باید ثبت شوند
$ git add my_module
تغییرات خود را ثبت کنید
$ git commit -m "My first module"
تغییرات خود را به مخزن راه دور ارسال کنید
از یک ترمینال ویرایشگر Odoo.sh:
$ git push https HEAD:feature-1
دستور بالا در بخش تعهد و ارسال تغییرات شما از فصل ویرایشگر آنلاین توضیح داده شده است. این شامل توضیحاتی درباره این است که از شما خواسته می‌شود نام کاربری و رمز عبور خود را وارد کنید و همچنین اقداماتی که در صورت استفاده از احراز هویت دو مرحله‌ای باید انجام دهید.
یا از طریق ترمینال کامپیوتر خود:
$ git push -u origin feature-1
شما باید فقط برای اولین بار -u origin feature-1 را مشخص کنید. از آن نقطه به بعد، برای ارسال تغییرات آینده خود از کامپیوترتان، می‌توانید به سادگی استفاده کنید.
$ git push
ماژول خود را آزمایش کنید¶
شاخه شما باید در شاخه‌های توسعه در پروژه شما ظاهر شود.
در نمای شاخه‌های پروژه شما، می‌توانید روی نام شاخه خود در پنل ناوبری سمت چپ کلیک کنید تا به تاریخچه آن دسترسی پیدا کنید.
شما می‌توانید تغییراتی که به‌تازگی اعمال کرده‌اید، از جمله توضیحاتی که وارد کرده‌اید، در اینجا مشاهده کنید. پس از آماده شدن پایگاه داده، می‌توانید با کلیک بر روی دکمه اتصال به آن دسترسی پیدا کنید.
اگر پروژه Odoo.sh شما به گونه‌ای تنظیم شده باشد که ماژول شما به‌صورت خودکار نصب شود، آن را مستقیماً در میان برنامه‌های پایگاه داده مشاهده خواهید کرد. در غیر این صورت، در میان برنامه‌های قابل نصب در دسترس خواهد بود.
سپس می‌توانید با ماژول خود کار کنید، رکوردهای جدید ایجاد کنید و ویژگی‌ها و دکمه‌های خود را آزمایش کنید.
آزمایش با داده‌های تولیدی¶
شما باید برای این مرحله یک پایگاه داده تولید داشته باشید. اگر هنوز آن را ندارید، می‌توانید آن را ایجاد کنید.
پس از اینکه ماژول خود را در یک نسخه توسعه با داده‌های نمایشی آزمایش کردید و معتقدید آماده است، می‌توانید آن را با داده‌های تولیدی با استفاده از شاخه مرحله‌بندی آزمایش کنید.
شما می‌توانید:
شاخه توسعه خود را به شاخه آزمایشی تبدیل کنید، با کشیدن و رها کردن آن روی عنوان بخش آزمایشی.
آن را در یک شاخه مرحله‌بندی موجود ادغام کنید، با کشیدن و رها کردن آن بر روی شاخه مرحله‌بندی مشخص شده.
شما همچنین می‌توانید از دستور git merge برای ادغام شاخه‌های خود استفاده کنید.
این کار یک نسخه آزمایشی جدید ایجاد می‌کند که پایگاه داده تولید را کپی کرده و آن را با استفاده از سروری که با آخرین تغییرات شاخه شما به‌روزرسانی شده است، اجرا می‌کند.
پس از آماده شدن پایگاه داده، می‌توانید با استفاده از دکمه اتصال به آن دسترسی پیدا کنید.
ماژول خود را نصب کنید¶
ماژول شما به صورت خودکار نصب نخواهد شد، شما باید آن را از منوی برنامه‌ها نصب کنید. در واقع، هدف از ساخت نسخه آزمایشی این است که رفتار تغییرات شما همان‌طور که در محیط تولید شما خواهد بود، آزمایش شود و در محیط تولید شما نمی‌خواهید ماژول شما به صورت خودکار نصب شود، بلکه بر اساس نیاز نصب شود.
ماژول شما ممکن است مستقیماً در برنامه‌های قابل نصب شما ظاهر نشود، ابتدا باید لیست برنامه‌های خود را به‌روزرسانی کنید:
حالت توسعه‌دهنده را فعال کنید developer mode
در منوی برنامه‌ها، روی دکمه به‌روزرسانی لیست برنامه‌ها کلیک کنید.
در کادری که ظاهر می‌شود، روی دکمه به‌روزرسانی کلیک کنید.
ماژول شما سپس در لیست برنامه‌های موجود ظاهر خواهد شد.
استقرار در محیط تولید¶
پس از آزمایش ماژول خود در یک شاخه آزمایشی با داده‌های تولیدی و اطمینان از آماده بودن آن برای تولید، می‌توانید شاخه خود را در شاخه تولید ادغام کنید.
شاخه مرحله‌بندی خود را بر روی شاخه تولید بکشید و رها کنید.
شما همچنین می‌توانید از دستور git merge برای ادغام شاخه‌های خود استفاده کنید.
این عملیات آخرین تغییرات شاخه آزمایشی شما را با شاخه تولید ادغام کرده و سرور تولید شما را با این تغییرات به‌روز خواهد کرد.
پس از آماده شدن پایگاه داده، می‌توانید با استفاده از دکمه اتصال به آن دسترسی پیدا کنید.
ماژول خود را نصب کنید¶
ماژول شما به صورت خودکار نصب نخواهد شد، شما باید آن را به صورت دستی همان‌طور که در بخش بالا درباره نصب ماژول در پایگاه‌های داده مرحله‌بندی توضیح داده شده است، نصب کنید.
افزودن تغییر¶
این بخش توضیح می‌دهد که چگونه با افزودن یک فیلد جدید در یک مدل، تغییری را در ماژول خود اضافه کرده و آن را اجرا کنید.
- از ویرایشگر Odoo.sh،
به پوشه ماژول خود ~/src/user/my_module بروید،
سپس فایل models/models.py را باز کنید.
- یا از رایانه خود،
از مرورگر فایل دلخواه خود استفاده کنید تا به پوشه ماژول خود ~/src/odoo-addons/my_module بروید.
سپس فایل models/models.py را با استفاده از ویرایشگر دلخواه خود، مانند Atom، Sublime Text، PyCharm، vim، ... باز کنید.
سپس، بعد از فیلد توضیحات
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 را باز کنید.
جایگزین کردن
'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 ایجاد خواهد کرد.
پس از آزمایش تغییرات خود، می‌توانید تغییرات را در شاخه تولید ادغام کنید، به عنوان مثال با کشیدن و رها کردن شاخه روی شاخه تولید در رابط Odoo.sh. با توجه به اینکه نسخه ماژول را در فایل manifest افزایش داده‌اید، پلتفرم به‌طور خودکار ماژول را به‌روزرسانی می‌کند و فیلد جدید شما بلافاصله در دسترس خواهد بود. در غیر این صورت، می‌توانید ماژول را به صورت دستی در لیست برنامه‌ها به‌روزرسانی کنید.
استفاده از یک کتابخانه خارجی پایتون¶
اگر می‌خواهید از یک کتابخانه پایتون خارجی که به صورت پیش‌فرض نصب نشده است استفاده کنید، می‌توانید یک فایل requirements.txt تعریف کنید که کتابخانه‌های خارجی مورد نیاز ماژول‌های شما را فهرست می‌کند.
توجه
نصب یا ارتقاء بسته‌های سیستمی در یک پایگاه داده Odoo.sh (مانند بسته‌های apt) امکان‌پذیر نیست. با این حال، تحت شرایط خاص، بسته‌ها می‌توانند برای نصب مورد بررسی قرار گیرند. این موضوع همچنین شامل ماژول‌های پایتون که برای کامپایل نیاز به بسته‌های سیستمی دارند و ماژول‌های شخص ثالث Odoo نیز می‌شود.
افزونه‌های PostgreSQL در Odoo.sh پشتیبانی نمی‌شوند.
برای اطلاعات بیشتر، به سؤالات متداول مراجعه کنید.
این پلتفرم از این فایل برای نصب خودکار کتابخانه‌های پایتون مورد نیاز پروژه شما استفاده خواهد کرد.
ویژگی در این بخش با استفاده از کتابخانه 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)
افزودن یک وابستگی پایتون نیاز به افزایش نسخه ماژول دارد تا پلتفرم بتواند آن را نصب کند.
ویرایش فایل مانیفست ماژول __manifest__.py
جایگزین کردن
'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