در Odoo 19، پیادهسازی یک کامپوننت سفارشی برای POS همیشه به این معنا نیست که باید یک کامپوننت OWL کاملاً جدید را از صفر بسازید. در بسیاری از سناریوهای واقعی، اودوو توسعهدهندگان را تشویق میکند که کامپوننتهای موجود POS را با استفاده از ابزار patch توسعه دهند. این روش به شما اجازه میدهد رفتار جدیدی را اضافه کنید، در حالی که ساختار اصلی، چیدمان و پایداری رابط POS حفظ میشود.
بخش دکمههای کنترلی POS خودش توسط یک کامپوننت OWL به نام ControlButtons مدیریت میشود. با توسعه این کامپوننت و اضافه کردن اکشنهای جدید به آن، در واقع یک کامپوننت سفارشی POS را پیادهسازی میکنیم که بهصورت یکپارچه با معماری موجود POS هماهنگ میشود. این همان رویکردی است که خود اودوو نیز بهصورت داخلی برای قابلیتهایی مانند تخفیفها و اکشنهای قیمتگذاری استفاده میکند.
در این مقاله نشان میدهیم چگونه میتوان در Odoo 19 با توسعه کامپوننت موجود ControlButtons و اتصال یک اکشن popup جدید، یک کامپوننت سفارشی POS پیادهسازی کرد.
ساختار ماژول برای دکمه سفارشی POS
برای شروع، یک ماژول سفارشی ایجاد کنید تا منطق فرانتاند POS داخل آن قرار بگیرد. از آنجا که این سفارشیسازی کاملاً سمت کلاینت است، ماژول فقط به فایلهای JavaScript و XML نیاز دارد.
یک ساختار حداقلی و تمیز میتواند به این شکل باشد:
pos_custom_popup/
¦-- __manifest__.py
¦-- static/
¦ +-- src/
¦ +-- js/
¦ ¦ +-- control_button.js
¦ +-- xml/
¦ +-- control_button.xml
پیادهسازی کامپوننت سفارشی POS از طریق Control Buttons
در Odoo 19، بیشتر اکشنهای POS در صفحه محصول از طریق کامپوننت ControlButtons مدیریت میشوند. به جای اینکه یک کامپوننت کاملاً جدید از صفر بسازیم، میتوانیم با استفاده از ابزار patch اودوو، رفتار موجود را بهصورت امن توسعه دهیم. این رویکرد از همان الگویی پیروی میکند که خود اودوو نیز بهصورت داخلی استفاده میکند.
JavaScript؛ مدیریت اکشن دکمه
یک فایل JavaScript در مسیر زیر ایجاد کنید:
static/src/js/control_button.js
سپس کد زیر را داخل آن قرار دهید:
/** @odoo-module **/
import { patch } from "@web/core/utils/patch";
import { ControlButtons } from
"@point_of_sale/app/screens/product_screen/control_buttons/control_buttons";
import { AlertDialog } from
"@web/core/confirmation_dialog/confirmation_dialog";
import { _t } from "@web/core/l10n/translation";
patch(ControlButtons.prototype, {
clickCustomAction() {
this.dialog.add(AlertDialog, {
title: _t("Custom Action"),
body: _t("This popup is triggered from a custom Control Button."),
});
},
});
این کد چه کاری انجام میدهد؟
patch(ControlButtons.prototype, ...) منطق موجود دکمههای کنترلی POS را توسعه میدهد.
clickCustomAction() یک متد جدید تعریف میکند که هنگام کلیک روی دکمه ما اجرا میشود.
AlertDialog یک کامپوننت dialog داخلی اودوو است و برای تأییدهای ساده یا popupهای اطلاعرسانی گزینه مناسبی محسوب میشود.
popup با استفاده از this.dialog.add باز میشود که روش پیشنهادی برای نمایش dialogها در Odoo 19 است.
تعریف رابط کاربری دکمه با XML
در مرحله بعد، مشخص میکنیم که دکمه در رابط POS چگونه نمایش داده شود. این کار با توسعه template موجود ControlButtons و اضافه کردن دکمه خودمان به container مورد انتظار انجام میشود.
یک فایل XML در مسیر زیر ایجاد کنید:
static/src/xml/control_button.xml
سپس کد زیر را داخل آن قرار دهید:
<?xml version="1.0" encoding="UTF-8"?>
<templates xml:space="preserve">
<t t-inherit="point_of_sale.ControlButtons" t-inherit-mode="extension">
<xpath expr="//div[hasclass('control-buttons')]" position="inside">
<button class="button-action btn btn-secondary" t-on-click="clickCustomAction">
<i class="fa fa-cog"/> Custom Action
</button>
</xpath>
</t>
</templates>
این template:
- layout موجود POS ControlButtons را به ارث میبرد.
- یک دکمه جدید به container مربوط به control-buttons اضافه میکند.
- کلیک روی دکمه را مستقیماً به متد JavaScript یعنی clickCustomAction متصل میکند.
این دکمه بدون نیاز به فایل CSS اضافی، بهصورت یکپارچه داخل رابط کاربری قرار میگیرد؛ چون از کلاسهای آماده دکمههای POS استفاده میکنیم.
بارگذاری Assetها در Manifest
در نهایت، فایلهای JavaScript و XML باید داخل asset bundle مربوط به POS بارگذاری شوند. این کار از طریق manifest ماژول انجام میشود.
فایل __manifest__.py را مانند نمونه زیر بهروزرسانی کنید:
{
"name": "POS Action Popup Button",
"version": "1.0",
"category": "Point of Sale",
"depends": ["point_of_sale"],
"assets": {
"point_of_sale._assets_pos": [
"pos_custom_popup/static/src/js/control_button.js",
"pos_custom_popup/static/src/xml/control_button.xml",
],
},
"installable": True,
"application": False,
"license": "LGPL-3",
}بعد از نصب یا ارتقای ماژول و پاک کردن cache مرورگر، دکمه جدید Custom Action در بخش دکمههای کنترلی POS نمایش داده میشود. وقتی روی آن کلیک کنید، یک alert dialog box باز میشود و نشان میدهد که integration بهدرستی کار میکند.
جمعبندی
وقتی درک کنید که OWL و سیستم registry چگونه با یکدیگر تعامل دارند، ساخت کامپوننتهای سفارشی POS در Odoo 19 بسیار دستیافتنیتر میشود. یک popup در واقع فقط کامپوننتی است که توسط popup service فعال میشود، و یک دکمه نیز کامپوننت دیگری در همین ساختار است. هم کد و هم جریان کار، تمیز و قابل مدیریت باقی میمانند.
با استفاده از مثال بالا، میتوانید رابط POS را بر اساس نیازهای مختلف کسبوکار سفارشیسازی کنید؛ از اکشنهای اضافی، هشدارها و تأییدیهها گرفته تا صفحههای کاملاً جدید.
مانند هر مهارت دیگری، وقتی اصول پایه را درک کنید، امکانات بیشتری پیش روی شما باز میشود. این دکمه و popup کوچک، با وجود ظاهر سادهشان، اولین قدمها برای ساخت قابلیتهای پیشرفتهتر در POS هستند.
سؤالات متداول
نه همیشه. در بسیاری از موارد، مخصوصاً زمانی که میخواهید رفتار یا دکمهای به بخشهای موجود POS اضافه کنید، بهتر است کامپوننتهای فعلی را با استفاده از patch توسعه دهید. این روش ساختار اصلی POS را حفظ میکند و باعث میشود سفارشیسازی شما با معماری داخلی اودوو هماهنگتر باشد.
ابزار patch به شما اجازه میدهد رفتار یک کامپوننت موجود را بدون بازنویسی کامل آن تغییر یا گسترش دهید. این روش باعث میشود کد شما سبکتر، پایدارتر و سازگارتر با ساختار اصلی اودوو باشد. همچنین در مقایسه با ساخت کامپوننت جدید از صفر، ریسک بههمریختن رابط POS را کاهش میدهد.
زیرا بخش دکمههای کنترلی در صفحه محصول POS توسط کامپوننت ControlButtons مدیریت میشود. اگر هدف اضافه کردن یک دکمه جدید به این بخش باشد، توسعه همین کامپوننت منطقیترین و تمیزترین روش است.
چند دلیل رایج وجود دارد: ممکن است فایلهای JavaScript یا XML در asset bundle مربوط به POS اضافه نشده باشند، ماژول بعد از تغییرات upgrade نشده باشد، cache مرورگر پاک نشده باشد یا مسیر فایلها در __manifest__.py اشتباه وارد شده باشد. همچنین باید مطمئن شوید template بهدرستی inherit شده و xpath به عنصر درست اشاره میکند.
بله، کاملاً. فریمورک OWL امکان ساخت popupهای کاملاً سفارشی و قابل استفاده مجدد را فراهم میکند. AlertDialog برای پیامهای ساده و تأییدهای اولیه مناسب است، اما برای نیازهای پیچیدهتر میتوانید popup اختصاصی خودتان را با template، state و logic سفارشی طراحی کنید.
