فصل ۲: مفاهیم اصلی و پایه

این فصل به بررسی عمیق‌تر اجزای اصلی PrestaSDK می‌پردازد. درک این مفاهیم به شما کمک می‌کند تا از تمام ظرفیت‌های SDK برای ساخت ماژول‌های پیچیده و قدرتمند استفاده کنید.

۲.۱. کلاس PrestaSDKModule

این کلاس، نقطه شروع هر ماژول مبتنی بر SDK است و با ارث‌بری از کلاس Module پرستاشاپ، قابلیت‌های فراوانی را به آن اضافه می‌کند. شما با تعریف چند پراپرتی در کلاس ماژول خود، می‌توانید فرآیندهای نصب و پیکربندی را به طور کامل به SDK بسپارید.

پراپرتی‌های کلیدی:

• $moduleTabs (آرایه): برای تعریف تمام تب‌های (منوهای) بخش مدیریت که ماژول شما به آن نیاز دارد. TabsInstaller به صورت خودکار این تب‌ها را هنگام نصب ماژول ایجاد می‌کند.
• $moduleConfigs (آرایه): لیستی از تمام کلیدهای پیکربندی (Configuration) که ماژول شما استفاده می‌کند. مقادیر پیش‌فرض آن‌ها در این آرایه تعریف شده و هنگام نصب به صورت خودکار در دیتابیس ذخیره می‌شوند.
• $configsAdminController (رشته یا آرایه): نام کنترلر اصلی ماژول را مشخص می‌کند. با این کار، دکمه “پیکربندی” (Configure) در لیست ماژول‌ها به صورت خودکار به صفحه این کنترلر لینک داده می‌شود.
• $moduleGrandParentTab (رشته): اگر می‌خواهید تب‌های ماژول شما زیرمجموعه یک تب اصلی دیگر (مثلاً “فروش”) قرار گیرند، نام کلاس آن تب را در این پراپرتی وارد کنید.
• $pathFileSqlInstall / $pathFileSqlUninstall (رشته): مسیر فایل‌های SQL برای ایجاد یا حذف جداول دیتابیس هنگام نصب/حذف ماژول را مشخص می‌کند. به طور پیش‌فرض، SDK به دنبال فایل‌های install.sql و uninstall.sql در پوشه sql/ ماژول می‌گردد.

  چرخه حیات ماژول

متدهای install() و uninstall() در PrestaSDKModule بازنویسی (override) شده‌اند تا فرآیندهای لازم را به صورت خودکار اجرا کنند. زمانی که شما parent::install() را فراخوانی می‌کنید، SDK به ترتیب کارهای زیر را انجام می‌دهد:

• نصب تب‌ها: بر اساس آرایه $moduleTabs.
• ثبت هوک‌ها: با بررسی تمام متدهای hook... در کلاس ماژول شما.
• اجرای SQL: با استفاده از فایل تعریف شده در $pathFileSqlInstall.
• ذخیره تنظیمات: مقادیر اولیه از $moduleConfigs در دیتابیس ذخیره می‌شوند.
• انتشار Asset ها: فایل‌های CSS/JS مربوط به SDK در پوشه views ماژول شما کپی می‌شوند.

بنابراین، شما دیگر نیازی به نوشتن منطق تکراری برای این کارها ندارید.

۲.۲. ساختار پنل مدیریت

PrestaSDK یک سیستم قدرتمند برای ساخت پنل‌های مدیریت مدرن و چندبخشی ارائه می‌دهد.

AdminController و PanelCore

برای ساخت یک صفحه در بخش مدیریت، کافی است یک کنترلر ایجاد کنید که از کلاس PrestaSDK\V070\Controller\AdminController ارث‌بری کند. این کلاس به طور خودکار Trait ی به نام PanelCore را به کار می‌گیرد که تمام منطق رندر کردن پنل، مدیریت بخش‌ها و قالب‌بندی را در خود جای داده است.

مفهوم بخش‌ها (Sections)

یکی از قابلیت‌های کلیدی AdminController، مدیریت صفحات از طریق “بخش‌ها” است. به جای ساخت چندین کنترلر برای صفحات مختلف (مانند تنظیمات، لیست‌ها، افزودن آیتم جدید)، شما می‌توانید تمام منطق را در یک کنترلر واحد و در متدهایی با الگوی section<Name> پیاده‌سازی کنید.

• مثال: اگر URL شما ...&section=settings باشد، SDK به صورت خودکار متد sectionSettings() را در کنترلر شما فراخوانی و محتوای آن را نمایش می‌دهد.
• بخش پیش‌فرض: اگر پارامتر section در URL وجود نداشته باشد، متد sectionIndex() اجرا خواهد شد.

این رویکرد، کد شما را بسیار تمیزتر و سازمان‌یافته‌تر می‌کند.

سیستم Layout و جایگاه‌ها (Positions)

پنل مدیریت SDK از یک فایل layout.tpl اصلی تشکیل شده که دارای جایگاه‌های (Positions) مختلفی مانند Sidebar, Header, TopContent و Footer است. شما می‌توانید از داخل کنترلر خود، محتوای HTML را به هر یک از این جایگاه‌ها تزریق کنید.

برای مثال، برای افزودن منوی کناری به پنل، کافیست HTML منو را رندر کرده و با متد زیر آن را به جایگاه Sidebar اضافه کنید:

$sidebarHtml = $this->renderPanelTemplate('_partials/sidebar.tpl', $vars);
$this->appendToPanel('Sidebar', $sidebarHtml);

این قابلیت به شما اجازه می‌دهد تا یک رابط کاربری یکپارچه و در عین حال کاملاً سفارشی ایجاد کنید.

۲.۳. مدیریت نسخه‌ها، Namespace و Factory

Namespace نسخه‌بندی شده

یک چالش مهم در اکوسیستم پرستاشاپ، احتمال تداخل بین ماژول‌های مختلف است. اگر دو ماژول از یک کتابخانه مشترک (مانند PrestaSDK) استفاده کنند، اما نسخه‌های متفاوتی از آن کتابخانه را نیاز داشته باشند، ممکن است با خطاهای Fatal Error به دلیل تعریف مجدد کلاس‌ها یا توابع مواجه شوند.

برای حل این مشکل، تمام کلاس‌های PrestaSDK در یک Namespace نسخه‌بندی شده قرار دارند. برای مثال، در نسخه 0.4.0، تمام کلاس‌ها زیر PrestaSDK\V070 قرار دارند:

namespace PrestaSDK\V070;

class PrestaSDKModule extends \Module
{
    // ...
}

این ساختار تضمین می‌کند که اگر در آینده نسخه 0.5.0 با namespace PrestaSDK\V070 منتشر شود، کدهای آن با نسخه‌های قدیمی‌تر تداخلی نخواهند داشت.

مسئولیت توسعه‌دهنده

هنگام استفاده از SDK، این وظیفه شما به عنوان توسعه‌دهنده است که از Namespace صحیح و متناسب با نسخه SDK نصب شده در ماژول خود استفاده کنید.

// استفاده صحیح برای نسخه 0.4.0
use PrestaSDK\V070\PrestaSDKModule;
use PrestaSDK\V070\Controller\AdminController;

class MyModule extends PrestaSDKModule 
{
    //...
}

اگر در آینده تصمیم گرفتید نسخه SDK را در ماژول خود ارتقا دهید، باید به صورت دستی use statement های خود را نیز به نسخه جدید (مثلاً PrestaSDK\V070\...) بروزرسانی کنید.

PrestaSDKFactory

کلاس PrestaSDKFactory یک ابزار کمکی برای ساده‌سازی فرآیند ساخت نمونه از کلاس‌های SDK در همان نسخه است. به جای فراخوانی مستقیم new \PrestaSDK\V070\Utility\Config(...)، می‌توانید از Factory استفاده کنید تا کد خواناتری داشته باشید.

use PrestaSDK\V070\PrestaSDKFactory;

// این Factory یک نمونه از کلاس Config در Namespace نسخه V070 ایجاد می‌کند
$config = PrestaSDKFactory::getUtility('Config', [$this->moduleConfigs]);

این الگو به خوانایی کد کمک می‌کند اما مسئولیت انتخاب نسخه صحیح Namespace همچنان بر عهده شماست.