آموزش استفاده از کلاس HTMLHelper در جوملا

کلاس Joomla\CMS\HTML\HTMLHelper در جوملا (که در نسخه‌های قدیمی‌تر به صورت JHtml شناخته می‌شد)، یکی از مهم‌ترین و پرکاربردترین کلاس‌های هسته جوملا برای توسعه‌دهندگان است.

به طور خلاصه، این کلاس یک «کارخانه تولید کدهای HTML» است که به شما کمک می‌کند کدهای HTML تکراری و پیچیده را به صورت استاندارد، بهینه و امن تولید کنید.

در اینجا بررسی می‌کنیم که چرا و چگونه از آن استفاده می‌شود.

۱. هدف اصلی: استانداردسازی و امنیت

به جای اینکه به صورت دستی تگ‌های HTML (مثل <select> یا <script>) را در فایل‌های PHP خود بنویسید، از HTMLHelper استفاده می‌کنید. مزایای این کار عبارتند از:

  • امنیت: بسیاری از متدهای این کلاس به طور خودکار داده‌ها را برای جلوگیری از حملات XSS (Cross-Site Scripting) پاکسازی می‌کنند.
  • سادگی: کارهای پیچیده (مثل ایجاد یک لیست کشویی بر اساس دیتابیس) را با یک خط کد انجام می‌دهید.
  • قابلیت اطمینان (Reliability): از آنجایی که این متدها هسته جوملا هستند، با هر آپدیت جوملا، کدهای شما نیز با استانداردهای جدید سازگار باقی می‌مانند.

۲. کاربردهای رایج

این کلاس شامل متدهای بسیار زیادی است که در دسته‌بندی‌های مختلف قرار می‌گیرند:

الف) فراخوانی کتابخانه‌های جاوا اسکریپت و CSS

این رایج‌ترین استفاده است. برای اینکه مطمئن شوید یک کتابخانه (مثل jQuery یا Bootstrap) فقط یک بار و در جای درست بارگذاری می‌شود:

use Joomla\CMS\HTML\HTMLHelper;

// بارگذاری بوت‌استرپ
HTMLHelper::_('bootstrap.framework');

// بارگذاری فریم‌ورک jQuery
HTMLHelper::_('jquery.framework');

ب) تولید فیلدهای فرم (Form Fields)

برای ایجاد لیست‌های کشویی (Select list) بر اساس داده‌های دیتابیس:

// ایجاد یک لیست کشویی از کاربران
echo HTMLHelper::_('select.genericlist', $userOptions, 'my_user_field', null, 'value', 'text', $selectedId);

ج) مدیریت زمان و تاریخ

برای نمایش تاریخ به فرمت‌های استاندارد جوملا:

echo HTMLHelper::_('date', '2026-05-24 10:00:00', 'Y-m-d H:i:s');

د) توابع کمکی دیگر (Behavior)

  • Tooltip: اضافه کردن افکت تول‌تیپ به یک عنصر HTML.
  • Formvalidator: فعال‌سازی اعتبار‌سنجی فرم‌ها.
  • Sidebar: ایجاد منوهای کناری در بخش مدیریت جوملا.

۳. نحوه استفاده (سینتکس)

نحوه فراخوانی متدها در این کلاس کمی متفاوت از کلاس‌های معمولی است. از متد جادویی _ استفاده می‌شود:

HTMLHelper::_('method_name', aeguman1, arguman2, ...);

ساختار درونی آن به گونه‌ای است که به صورت Lazy Loading کار می‌کند؛ یعنی اگر متدی را فراخوانی کنید که در یک فایل جداگانه تعریف شده باشد، جوملا فقط در همان لحظه فایل مربوطه را include می‌کند که باعث افزایش سرعت سایت می‌شود.

۴. چرا به جای نوشتن مستقیم HTML از آن استفاده کنیم؟

فرض کنید می‌خواهید یک فایل CSS را اضافه کنید. اگر مستقیم تگ <link> بنویسید، ممکن است در جای نامناسبی قرار بگیرد یا با افزونه‌های دیگر تداخل پیدا کند. اما با استفاده از:

HTMLHelper::_('stylesheet', 'path/to/style.css');

جوملا مدیریت می‌کند که این فایل در بخش <head> و با اولویت مناسب قرار گیرد.

متدهای رایج که از طریق HTMLHelper::_() فراخوانی می‌شوند:

متدهای کلاس Joomla\CMS\HTML\HTMLHelper (که قبلاً JHtml نام داشت) بسیار متنوع هستند و برای تولید انواع مختلف کدهای HTML و انجام وظایف کمکی به کار می‌روند.

الگوی نوشتن متن های HTMLHelper به شکل زیر است:

HTMLHelper::_('methodName', $args...)

یعنی در ابتدا، نام متد methodName و سپس آرگومان های متناسب با آن متد نوشته می شوند.

در اینجا برخی از مهم‌ترین و پرکاربردترین متدهای HTMLHelper را به همراه توضیحات آرگومان‌هایشان آورده‌ام:

متد image

HTMLHelper::_('image', 'file-name:string', 'alt:string', attribs:string|array, relative:boolean, return_path:integer);

کاربرد: 

تولید تگ Html <img>

آرگومان‌ها:

  • file-name (string، اجباری): اسم عکس یا آدرس منبع تصویر (بناب بر اینکه در آرگومان relative مسیر از پوشه media خوانده می شود یا مسیر نسبی است).
  • alt (string، اختیاری): متن جایگزین تصویر (alt attribute). اگر خالی باشد، از $src یا $altAsTitle استفاده می‌شود.
  • attribs (string یا array، اختیاری): سایر ویژگی‌های تگ <img> (مانند class, id, width, height). اینها به صورت رشته‌ای از ویژگی‌ها  (مثلاً 'class="my-image" id="logo"' ) یا آرایه ( مثلا ( 'class' => 'logo d-inline-block', 'loading' => 'eager' ) وارد می‌شوند.
  • relative (bool، اختیاری): اگر true باشد، در پوشه media ی قالب به دنبال تصویر می گردد.
  • return_path (int، اختیاری، پیش‌فرض: false): 
    • اگر 0 باشد: دنبال عکس در پوشه media می گردد و اطلاعات عکس رو داخل تگ img خروجی می دهد.
    • اگر 1 باشد: دنبال عکس در پوشه media می گرده و صرفا مسیر عکس را خروجی می دهد و تگ img نمی سازد، بنابراین نیازی به alt و attribs نیز نمی باشد.
    • اگر -1 باشد: هر مسیری در آرگومان filename وارد کنید قبول می کند و کاری به پوشه media ندارد و اطلاعات عکس را داخل تگ img بر می گرداند.

ادامه دارد

توضیحات
نوشته شده توسط: مسعود نیک صفت
دسته: مفاهیم برنامه نویسی و توسعه جوملا
بازدید: 12