پیاده سازی و استفاده از آژاکس در دروپال

آژاکس (AJAX) یا Asynchronous JavaScript and XML، روشی توانمند برای ایجاد تعامل پذیری در وب سایت ها بدون نیاز به بارگذاری مجدد کامل صفحه است. دروپال، به عنوان یک سیستم مدیریت محتوای قدرتمند، امکان پیاده سازی این قابلیت را به توسعه دهندگان می دهد تا تجربه ای پویا و سریع تر برای کاربران خود فراهم آورند. این ویژگی به سایت ها اجازه می دهد تا با سرور ارتباط برقرار کرده و تنها بخش های خاصی از صفحه را به روزرسانی کنند، که نتیجه آن افزایش چشمگیر سرعت و پاسخگویی وب سایت است. این مقاله، راهنمایی جامع برای توسعه دهندگان و مدیران سایت های دروپالی است تا بتوانند از این قابلیت به بهترین شکل استفاده کنند.

وقتی کاربران با یک وب سایت دروپالی تعامل می کنند، انتظاری برای سرعت و روان بودن دارند. بارگذاری های کامل صفحه، می تواند این تجربه را مختل کرده و کاربران را از ادامه کار منصرف سازد. اینجاست که آژاکس وارد میدان می شود. با استفاده از آژاکس، می توان بخش هایی از صفحه مانند فیلترهای جستجو، فرم های ورود اطلاعات، یا لیست های محتوا را بدون نیاز به رفرش کامل صفحه، به روزرسانی کرد.

توسعه دهندگان دروپال ۸، ۹ و ۱۰ می توانند با درک عمیق از API آژاکس در دروپال، سایت هایی بسازند که نه تنها از نظر بصری جذاب هستند، بلکه از نظر عملکردی نیز بی نظیر عمل می کنند. این قابلیت، به خصوص برای ایجاد فرم های پویا، فیلترهای پیشرفته در Viewها و به روزرسانی لحظه ای محتوا بسیار مفید است. با پیاده سازی صحیح آژاکس، می توان بار سرور را کاهش داد و در عین حال، کاربران را با یک رابط کاربری واکنش گرا و سریع شگفت زده کرد. این موضوع به طور مستقیم بر روی رتبه بندی سایت در موتورهای جستجو نیز تاثیر مثبتی خواهد گذاشت، زیرا سرعت و تجربه کاربری از فاکتورهای مهم سئو محسوب می شوند.

AJAX چیست و چرا در دروپال ضروری است؟

آژاکس، همان طور که از نامش پیداست، یک رویکرد برنامه نویسی برای ساخت برنامه های وب نامتقارن است. این رویکرد به مرورگر وب اجازه می دهد تا بدون دخالت کاربر و بدون بارگذاری مجدد صفحه، با سرور ارتباط برقرار کند. در واقع، یک ارتباط پشت پرده است که داده ها را بین کلاینت (مرورگر) و سرور مبادله می کند. این فلسفه، هسته اصلی وب سایت های مدرن و تعاملی است که امروزه تجربه می کنیم.

چرا AJAX در پروژه های مدرن دروپال حیاتی است؟

استفاده از آژاکس دروپال، مزایای بسیاری را به ارمغان می آورد که هر توسعه دهنده و مدیر سایت به دنبال آن ها است. این مزایا به طور مستقیم بر تجربه کاربری، عملکرد و حتی کارایی سرور تأثیر می گذارند:

• بهبود تجربه کاربری (UX): کاربران دیگر نیازی به انتظار برای بارگذاری کامل صفحه ندارند. این امر حس سرعت و پاسخگویی را افزایش می دهد و ناوبری را روان تر می کند.
• افزایش سرعت و کاهش بار سرور: با ارسال و دریافت تنها داده های مورد نیاز، حجم اطلاعات مبادله شده بین کلاینت و سرور کاهش می یابد. این به معنای بارگذاری سریع تر و کاهش فشار بر روی منابع سرور است.
• تعاملی بودن سایت: آژاکس به وب سایت ها این قابلیت را می دهد که به رویدادهای کاربر (مانند کلیک، تایپ یا تغییر فیلد) واکنش های لحظه ای نشان دهند، بدون اینکه کل صفحه رفرش شود.
• ایجاد صفحات پویا: با آژاکس، می توان محتوا را به صورت پویا و بر اساس ورودی کاربر یا داده های جدید از سرور، در بخش های مختلف صفحه نمایش داد.

کاربردهای رایج AJAX در دروپال

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

• فیلترها و جستجوهای پویا: یک View که نتایج را بر اساس فیلترهای انتخاب شده توسط کاربر، به صورت لحظه ای و بدون رفرش صفحه، به روزرسانی می کند.
• فرم های پویا: فرم هایی که بر اساس انتخاب کاربر در یک فیلد (مثلاً انتخاب استان)، فیلدهای دیگر (مثلاً لیست شهرها) را به روزرسانی می کنند.
• به روزرسانی محتوا: قابلیت هایی مانند بارگذاری بی نهایت (Infinite Scroll) برای لیست مقالات یا به روزرسانی خودکار نرخ ارز.
• سیستم های چت و اعلان: نمایش پیام های جدید چت یا اعلان ها بدون نیاز به رفرش دستی صفحه.
• عملیات مدیریتی: به روزرسانی وضعیت یک آیتم (مثلاً منتشر کردن یک محتوا) از طریق یک دکمه و بدون ترک صفحه فعلی.

پیش نیازها: آشنایی با دروپال، PHP و JavaScript

برای شروع سفر در دنیای آژاکس دروپال، داشتن دانش پایه در چند زمینه ضروری است. توسعه دهنده ای که قصد دارد از این قابلیت بهره ببرد، باید با موارد زیر آشنایی داشته باشد:

• دروپال: درک مفاهیم اصلی ماژول نویسی، ساختار تم ها و به خصوص Form API در دروپال.
• PHP: زبان سمت سرور دروپال است و توانایی نوشتن منطق Callbackها و کنترل کننده های آژاکس با PHP حیاتی است.
• JavaScript (و jQuery): آژاکس در سمت کلاینت با جاوااسکریپت پیاده سازی می شود. دروپال به شدت از jQuery استفاده می کند، بنابراین آشنایی با آن نیز کمک کننده است.

مفاهیم پایه و معماری AJAX دروپال

معماری آژاکس در دروپال به گونه ای طراحی شده که توسعه دهندگان بتوانند به راحتی تعاملات پویا ایجاد کنند. این معماری شامل یک تعامل دوطرفه بین Frontend (با استفاده از جاوااسکریپت) و Backend (با استفاده از PHP) است که توسط Drupal.Ajax API مدیریت می شود.

معماری کلی AJAX دروپال: تعامل Frontend (JS) و Backend (PHP)

وقتی یک رویداد آژاکس در دروپال رخ می دهد (مثلاً کلیک روی یک دکمه یا تغییر یک فیلد فرم)، مراحل زیر اتفاق می افتد:

1. درخواست از سمت کلاینت: یک رویداد جاوااسکریپت (مانند `click` یا `change`) توسط `Drupal.behaviors` یا مستقیماً توسط `Drupal.ajax` شناسایی می شود.
2. ارسال درخواست AJAX: مرورگر یک درخواست HTTP نامتقارن (معمولاً POST) را به یک مسیر (Route) تعریف شده در دروپال ارسال می کند.
3. پردازش در سمت سرور: کنترل کننده (Controller) یا Callback PHP مرتبط با آن مسیر، درخواست را دریافت و پردازش می کند. این Callback معمولاً یک شیء `AjaxResponse` را برمی گرداند.
4. بازگشت پاسخ AJAX: `AjaxResponse` حاوی یک سری دستورات آژاکس (Ajax Commands) است که به مرورگر می گوید چه کاری انجام دهد (مثلاً محتوایی را جایگزین کند، یک بلاک جدید اضافه کند یا یک پیام هشدار نمایش دهد).
5. اجرا در سمت کلاینت: `Drupal.Ajax` در سمت جاوااسکریپت، این دستورات را دریافت کرده و آن ها را اجرا می کند تا بخش های مربوطه از صفحه به روزرسانی شوند.

نقش مرکزی Drupal.Ajax API

Drupal.Ajax در هسته سیستم آژاکس دروپال قرار دارد. این API یک لایه انتزاعی فراهم می کند که تعاملات پیچیده آژاکس را ساده می سازد. توسعه دهندگان می توانند با استفاده از این API، بدون نیاز به نوشتن کدهای جاوااسکریپت پیچیده برای مدیریت درخواست ها و پاسخ های HTTP، قابلیت های آژاکس را به فرم ها و عناصر دیگر اضافه کنند.

فرآیند درخواست-پاسخ AJAX در دروپال (Callbacks و Commands)

قلب سیستم آژاکس دروپال، بر مبنای Callbackها و Commands بنا شده است:

• Callbackها: توابع PHP در سمت سرور هستند که پس از دریافت درخواست آژاکس فراخوانی می شوند. این توابع منطق اصلی پردازش داده ها را انجام داده و یک شیء `AjaxResponse` را برمی گردانند.
• Commands: دستورات آژاکس، کلاس های PHP هستند که یک عمل خاص را در سمت کلاینت تعریف می کنند. مثال هایی از این دستورات شامل `HtmlCommand` (برای جایگزینی محتوای HTML), `AlertCommand` (برای نمایش یک پیام هشدار) و `RemoveCommand` (برای حذف یک عنصر) هستند.

تفاوت AJAX در دروپال با پیاده سازی AJAX سنتی

تفاوت اصلی در این است که دروپال یک فریم ورک آماده برای آژاکس ارائه می دهد. در پیاده سازی سنتی (مانند استفاده مستقیم از `jQuery.ajax()`)، توسعه دهنده باید تمام جنبه های درخواست و پاسخ (از جمله ساختار داده ها، مدیریت خطاها و به روزرسانی DOM) را به صورت دستی مدیریت کند. اما در دروپال، با استفاده از #ajax در Form API یا برگرداندن AjaxResponse از یک کنترل کننده، بسیاری از این جزئیات به صورت خودکار توسط هسته دروپال مدیریت می شوند. این کار پیچیدگی ها را کاهش داده و فرآیند توسعه را سرعت می بخشد.

آماده سازی محیط توسعه

برای شروع کار با آژاکس، اطمینان حاصل کنید که یک ماژول سفارشی برای کدهای PHP خود دارید. همچنین، فایل های .libraries.yml و .module برای تعریف کتابخانه های جاوااسکریپت و پیاده سازی هوک ها آماده باشند.

آژاکس دروپال یک لایه انتزاعی قدرتمند است که به توسعه دهندگان اجازه می دهد تا با تمرکز بر منطق تجاری، تجربه های کاربری پویا و سریع تری خلق کنند و خود را از پیچیدگی های تعامل مستقیم با درخواست های HTTP رها سازند.

پیاده سازی AJAX در فرم های دروپال (Drupal Form API)

یکی از رایج ترین و قدرتمندترین کاربردهای آژاکس در دروپال، ادغام آن با Form API است. این قابلیت به توسعه دهندگان اجازه می دهد تا فرم هایی پویا و تعاملی بسازند که بدون نیاز به بارگذاری مجدد کامل صفحه، به ورودی های کاربر واکنش نشان دهند.

افزودن قابلیت AJAX به یک عنصر فرم

برای افزودن قابلیت آژاکس به یک عنصر فرم، می توان از خاصیت #ajax در آرایه فرم استفاده کرد. این خاصیت شامل تنظیماتی مانند callback (تابعی که پس از رویداد آژاکس فراخوانی می شود), wrapper (ID عنصری که محتوایش باید به روزرسانی شود), event (رویدادی که باید به آن گوش داده شود) و progress (تنظیمات مربوط به نمایش پیام بارگذاری) است.

مثال عملی 1: فیلد Select (استان) که با تغییر آن، فیلد Select دیگر (شهر) به صورت پویا به روزرسانی می شود.

در این مثال، می خواهیم با انتخاب یک استان، لیست شهرهای مرتبط با آن استان در یک فیلد Select دیگر به روزرسانی شود. فرض کنید ماژول سفارشی شما mymodule نام دارد.

// mymodule.module
use DrupalCoreFormFormStateInterface;
use DrupalCoreAjaxAjaxResponse;
use DrupalCoreAjaxReplaceCommand;

/**
 * Implements hook_form_FORM_ID_alter().
 */
function mymodule_form_test_ajax_form_alter(&$form, FormStateInterface $form_state, $form_id) {
  $form['#prefix'] = '<div id=ajax-form-wrapper>';
  $form['#suffix'] = '</div>';

  $form['province'] = [
    '#type' => 'select',
    '#title' => t('استان'),
    '#options' => [
      '0' => t('- انتخاب کنید -'),
      'tehran' => t('تهران'),
      'isfahan' => t('اصفهان'),
      'fars' => t('فارس'),
    ],
    '#ajax' => [
      'callback' => 'mymodule_province_callback',
      'wrapper' => 'city-wrapper', // ID of the element to be replaced
      'event' => 'change',
      'progress' => [
        'type' => 'throbber',
        'message' => t('در حال بارگذاری شهرها...'),
      ],
    ],
  ];

  $selected_province = $form_state->getValue('province');
  $cities = mymodule_get_cities($selected_province);

  $form['city'] = [
    '#type' => 'select',
    '#title' => t('شهر'),
    '#options' => $cities,
    '#prefix' => '<div id=city-wrapper>', // Wrapper for the city field
    '#suffix' => '</div>',
    '#disabled' => empty($selected_province) || $selected_province == '0',
  ];

  $form['submit'] = [
    '#type' => 'submit',
    '#value' => t('ارسال'),
  ];
}

/**
 * AJAX callback for the province field.
 */
function mymodule_province_callback(array &$form, FormStateInterface $form_state) {
  return $form['city']; // Return only the city element to be replaced.
}

/**
 * Helper function to get cities based on province.
 */
function mymodule_get_cities($province) {
  $all_cities = [
    'tehran' => ['tehran' => t('تهران'), 'karaj' => t('کرج')],
    'isfahan' => ['isfahan' => t('اصفهان'), 'kashan' => t('کاشان')],
    'fars' => ['shiraz' => t('شیراز'), 'marvdasht' => t('مرودشت')],
  ];

  if (isset($all_cities[$province])) {
    return ['0' => t('- انتخاب کنید -')] + $all_cities[$province];
  }
  return ['0' => t('- انتخاب کنید -')];
}

در این کد، با تغییر فیلد استان، تابع mymodule_province_callback فراخوانی شده و تنها فیلد شهر را برای به روزرسانی بازمی گرداند. خاصیت wrapper تضمین می کند که فقط بخش مربوط به شهر جایگزین شود.

اعتبارسنجی لحظه ای (Real-time Validation) با AJAX

یکی از کاربردهای مفید آژاکس، امکان اعتبارسنجی فیلدها بدون نیاز به سابمیت کامل فرم است. این کار به کاربر بازخورد لحظه ای می دهد.

مثال عملی 2: بررسی در دسترس بودن نام کاربری در فرم ثبت نام

فرض کنید می خواهیم در یک فرم ثبت نام، نام کاربری را بلافاصله پس از تایپ کاربر بررسی کنیم.

// mymodule.module (building on the previous example or a new form)

// ... inside a form definition function or hook_form_alter ...

  $form['username'] = [
    '#type' => 'textfield',
    '#title' => t('نام کاربری'),
    '#ajax' => [
      'callback' => '::validateUsernameCallback', // Use :: for class methods if in a form class
      'event' => 'blur', // Check when user leaves the field
      'wrapper' => 'username-message-wrapper',
      'progress' => [
        'type' => 'throbber',
        'message' => t('در حال بررسی نام کاربری...'),
      ],
    ],
    '#suffix' => '<div id=username-message-wrapper></div>', // Wrapper for validation message
  ];

// ... then define the callback function (e.g., in a custom form class)
// Or as a standalone function for hook_form_alter:
/**
 * AJAX callback for username validation.
 */
function mymodule_validate_username_callback(array &$form, FormStateInterface $form_state) {
  $response = new AjaxResponse();
  $username = $form_state->getValue('username');
  $message = '';
  $is_available = TRUE; // Assume available for now

  // In a real scenario, you would query the database to check availability
  if ($username == 'admin') { // Example: 'admin' is taken
    $message = t('این نام کاربری قبلاً رزرو شده است.');
    $is_available = FALSE;
  } elseif (strlen($username) < 3) {
    $message = t('نام کاربری باید حداقل 3 کاراکتر باشد.');
    $is_available = FALSE;
  } elseif (!empty($username)) {
    $message = t('نام کاربری %username در دسترس است.', ['%username' => $username]);
  }

  // Replace the content of the wrapper with the validation message.
  $response->addCommand(new HtmlCommand('#username-message-wrapper', $message));
  
  return $response;
}

در این مثال، با خروج کاربر از فیلد نام کاربری (رویداد blur)، یک Callback آژاکس فراخوانی شده و وضعیت نام کاربری را در یک عنصر `div` مجزا نمایش می دهد.

نمایش پیام های وضعیت و بارگذاری (Loading States/Messages)

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

در خاصیت #ajax، می توان از آرایه progress برای پیکربندی این پیام ها استفاده کرد:

    '#ajax' => [
      // ...
      'progress' => [
        'type' => 'throbber', // یا 'fullscreen'
        'message' => t('در حال انجام عملیات، لطفاً صبر کنید...'),
      ],
    ],

type می تواند throbber (یک انیمیشن کوچک بارگذاری) یا fullscreen (یک لایه مات با پیام در مرکز صفحه) باشد. message نیز متنی است که در کنار انیمیشن نمایش داده می شود. این بازخورد به کاربر اطمینان می دهد که سیستم در حال پردازش درخواست او است و از سردرگمی جلوگیری می کند.

پیاده سازی AJAX در ماژول های سفارشی (Custom Modules) با JS

گاهی اوقات، نیاز است که کنترل بیشتری بر روی فرآیند آژاکس داشته باشیم یا عملیات آژاکس را از طریق کدهای جاوااسکریپت سفارشی راه اندازی کنیم. در این موارد، می توانیم مسیرها و کنترل کننده های PHP خود را تعریف کرده و از AjaxResponse و AjaxCommandها برای برگرداندن پاسخ استفاده کنیم.

تعریف یک مسیر (Route) و کنترل کننده (Controller) برای پاسخ AJAX

اولین گام، تعریف یک مسیر سفارشی در فایل YOUR_MODULE.routing.yml است که درخواست های آژاکس به آن ارسال شوند.

# mymodule.routing.yml
mymodule.ajax_update_block:
  path: '/mymodule/ajax/update-block/{block_id}'
  defaults:
    _controller: 'DrupalmymoduleControllerMyAjaxController::updateBlock'
    _title: 'Ajax Block Update'
  requirements:
    _permission: 'access content'

سپس، یک کنترل کننده PHP می نویسیم که تابع updateBlock را پیاده سازی می کند. این کنترل کننده باید یک شیء AjaxResponse را برگرداند.

// src/Controller/MyAjaxController.php
namespace DrupalmymoduleController;

use DrupalCoreControllerControllerBase;
use DrupalCoreAjaxAjaxResponse;
use DrupalCoreAjaxHtmlCommand;
use SymfonyComponentHttpFoundationRequest;

class MyAjaxController extends ControllerBase {

  public function updateBlock(Request $request, $block_id) {
    $response = new AjaxResponse();

    // In a real scenario, you would load dynamic content based on $block_id
    $new_content = $this->t('این محتوا به صورت پویا و با استفاده از آژاکس به روزرسانی شد. زمان: @time', [
      '@time' => Drupal::time()->format('H:i:s')
    ]);

    // Replace the content of an HTML element with ID 'my-block-wrapper'
    $response->addCommand(new HtmlCommand('#my-block-wrapper-' . $block_id, $new_content));

    return $response;
  }
}

استفاده از AjaxResponse و AjaxCommandها

AjaxResponse یک کانتینر برای AjaxCommandها است. هر AjaxCommand یک دستورالعمل خاص برای مرورگر است. برخی از دستورات پرکاربرد عبارتند از:

• HtmlCommand($selector, $content): محتوای HTML یک عنصر را جایگزین می کند.
• ReplaceCommand($selector, $content): یک عنصر کامل را با محتوای جدید جایگزین می کند. (با HtmlCommand متفاوت است زیرا کل عنصر را جایگزین می کند، نه فقط محتوای داخلی آن را).
• AppendCommand($selector, $content): محتوای جدید را به انتهای محتوای موجود یک عنصر اضافه می کند.
• PrependCommand($selector, $content): محتوای جدید را به ابتدای محتوای موجود یک عنصر اضافه می کند.
• RemoveCommand($selector): یک عنصر را از DOM حذف می کند.
• AlertCommand($message): یک پیام هشدار جاوااسکریپت (alert()) نمایش می دهد.
• InvokeCommand($selector, $method, $arguments): یک تابع جاوااسکریپت را بر روی یک عنصر فراخوانی می کند.

مثال عملی 3: یک دکمه که با کلیک روی آن، محتوای یک بلاک خاص در صفحه بدون رفرش به روزرسانی می شود.

فرض کنید یک بلاک با ID my-dynamic-block در صفحه داریم. می خواهیم با کلیک روی یک دکمه، محتوای آن بلاک را به روزرسانی کنیم.

// src/Plugin/Block/MyCustomBlock.php (for displaying the block and button)
namespace DrupalmymodulePluginBlock;

use DrupalCoreBlockBlockBase;
use DrupalCoreFormFormStateInterface;

/**
 * Provides a 'MyCustomBlock'.
 *
 * @Block(
 *   id = my_custom_block,
 *   admin_label = @Translation(My Custom AJAX Block),
 *   category = @Translation(Custom)
 * )
 */
class MyCustomBlock extends BlockBase {

  /**
   * {@inheritdoc}
   */
  public function build() {
    $build = [];
    $build['#markup'] = $this->t('این محتوای اولیه بلاک است. زمان: @time', [
      '@time' => Drupal::time()->format('H:i:s')
    ]);

    $build['button'] = [
      '#type' => 'button',
      '#value' => $this->t('به روزرسانی بلاک'),
      '#attributes' => [
        'id' => 'ajax-update-button',
      ],
      // Attach the custom AJAX JavaScript library
      '#attached' => [
        'library' => ['mymodule/mymodule.ajax'],
      ],
    ];

    $build['#prefix'] = '<div id=my-block-wrapper-1>'; // Wrapper for content update
    $build['#suffix'] = '</div>';

    return $build;
  }
}

// mymodule.libraries.yml
mymodule.ajax:
  version: 1.x
  js:
    js/mymodule.ajax.js: {}
  dependencies:
    - core/jquery
    - core/drupal.ajax
    - core/drupal.dialog
    - core/drupal.message

// js/mymodule.ajax.js
(function ($, Drupal) {
  Drupal.behaviors.myAjaxBlockUpdater = {
    attach: function (context, settings) {
      $('#ajax-update-button', context).once('myAjaxBlockUpdater').each(function () {
        $(this).on('click', function (e) {
          e.preventDefault();
          var button = $(this);
          button.prop('disabled', true); // Disable button to prevent multiple clicks

          // Create a new Drupal.Ajax object.
          // The path should match the route defined in mymodule.routing.yml
          var ajaxObject = Drupal.ajax({
            url: Drupal.url('/mymodule/ajax/update-block/1'), // block_id=1 as example
            element: button.get(0), // Element that triggered the AJAX call
            // You can add a 'progress' setting here if needed for custom UI
            progress: {
              type: 'throbber',
              message: Drupal.t('در حال به روزرسانی...')
            }
          });

          // Execute the AJAX call.
          ajaxObject.execute();

          button.prop('disabled', false); // Re-enable button after AJAX call (success/error)
        });
      });
    }
  };
})(jQuery, Drupal);

در این مثال، دکمه با استفاده از جاوااسکریپت و Drupal.ajax یک درخواست به کنترل کننده PHP می فرستد و پاسخ آن (یک HtmlCommand) محتوای بلاک را به روزرسانی می کند.

فراخوانی AJAX از طریق JavaScript (Drupal.ajax و Drupal.behaviors)

برای مدیریت صحیح کدهای جاوااسکریپت در دروپال، باید از Drupal.behaviors استفاده شود. این الگو تضمین می کند که کدهای جاوااسکریپت پس از هر بارگذاری آژاکس (و همچنین در بارگذاری اولیه صفحه) به درستی اجرا شوند.

Drupal.behaviors یک شیء است که متد attach دارد. این متد دو پارامتر context و settings را می پذیرد. context به عنصری از DOM اشاره دارد که در حال پردازش است (در بارگذاری کامل صفحه، کل document است، و در بارگذاری آژاکس، بخشی است که توسط آژاکس به روزرسانی شده). .once() نیز یک متد jQuery است که تضمین می کند کد شما فقط یک بار بر روی یک عنصر خاص اجرا شود، حتی اگر attach چندین بار فراخوانی شود.

Drupal.ajax یک کلاس جاوااسکریپت است که مدیریت درخواست ها و پاسخ های آژاکس را از سمت کلاینت بر عهده دارد. با ایجاد یک نمونه از این کلاس و تنظیم url و element، می توان یک درخواست آژاکس را آغاز کرد.

مثال عملی 4: پیاده سازی قابلیت بارگذاری بی نهایت (Infinite Scroll) برای یک لیست محتوا.

برای پیاده سازی Infinite Scroll، نیاز داریم به رویداد اسکرول گوش دهیم و وقتی کاربر به انتهای صفحه رسید، محتوای جدید را از سرور درخواست کنیم.

// mymodule.routing.yml (example route for loading more content)
mymodule.load_more_content:
  path: '/mymodule/ajax/load-more'
  defaults:
    _controller: 'DrupalmymoduleControllerMyAjaxController::loadMoreContent'
    _title: 'Load More Content'
  requirements:
    _permission: 'access content'

// src/Controller/MyAjaxController.php (example loadMoreContent method)
namespace DrupalmymoduleController;

use DrupalCoreControllerControllerBase;
use DrupalCoreAjaxAjaxResponse;
use DrupalCoreAjaxAppendCommand;
use SymfonyComponentHttpFoundationRequest;

class MyAjaxController extends ControllerBase {
  // ... (previous methods)

  public function loadMoreContent(Request $request) {
    $response = new AjaxResponse();
    $page = $request->query->get('page', 0); // Get current page from query string

    // In a real scenario, load content from database based on $page
    $items_per_page = 5;
    $start_index = $page * $items_per_page;
    $new_items = []; // Example array of new content items

    for ($i = 0; $i < $items_per_page; $i++) {
      $new_items[] = '<div class=content-item>آیتم محتوا ' . ($start_index + $i + 1) . '</div>';
    }

    // Append new items to the content list.
    $response->addCommand(new AppendCommand('.infinite-scroll-container', implode('', $new_items)));

    // You might also want to send back the next page number
    $response->addCommand(new InvokeCommand('body', 'trigger', ['mymodule.infiniteScrollNextPage', $page + 1]));

    return $response;
  }
}

// js/mymodule.ajax.js (building on previous JS)
(function ($, Drupal) {
  Drupal.behaviors.infiniteScroll = {
    attach: function (context, settings) {
      var container = $('.infinite-scroll-container', context).once('infiniteScroll');
      if (container.length) {
        var loading = false;
        var currentPage = 0; // Initial page

        $(window).on('scroll', function () {
          if (!loading && $(window).scrollTop() + $(window).height() > $(document).height() - 300) { // 300px from bottom
            loading = true;
            
            var ajaxObject = Drupal.ajax({
              url: Drupal.url('/mymodule/ajax/load-more?page=' + currentPage),
              element: $('.infinite-scroll-container', context).get(0),
              progress: {
                type: 'throbber',
                message: Drupal.t('در حال بارگذاری محتوای بیشتر...')
              }
            });
            ajaxObject.execute();
          }
        });

        $('body').on('mymodule.infiniteScrollNextPage', function(event, nextPage) {
          currentPage = nextPage;
          loading = false;
        });
      }
    }
  };
})(jQuery, Drupal);

این مثال ترکیبی از کنترلر PHP برای ارائه محتوای جدید و جاوااسکریپت برای تشخیص اسکرول و فراخوانی آژاکس را نشان می دهد. AppendCommand محتوای جدید را به لیست اضافه می کند.

استفاده از AJAX در Views دروپال

ماژول Views دروپال یکی از قدرتمندترین ابزارهای نمایش محتوا است و قابلیت های آژاکس آن، ایجاد لیست ها و جداول تعاملی را بسیار ساده می کند. توسعه دهندگان می توانند بدون نوشتن حتی یک خط کد PHP یا جاوااسکریپت، فیلترها، Pagination و Sorting را به صورت آژاکس فعال کنند.

فعال سازی و پیکربندی AJAX برای یک View

برای فعال سازی آژاکس در یک View، مراحل زیر را دنبال می کنیم:

1. به صفحه مدیریت Viewها دروپال (/admin/structure/views) بروید و یک View جدید ایجاد یا View موجود را ویرایش کنید.
2. در تنظیمات Advanced (پیشرفته) View، گزینه Use AJAX را پیدا کنید.
3. این گزینه را به Yes تغییر دهید.
4. Apply (اعمال) کنید و View را ذخیره کنید.

با فعال کردن این گزینه، تمام فیلترها، Page (صفحه بندی) و Sort (مرتب سازی) در آن View به صورت آژاکس عمل خواهند کرد. به این معنی که وقتی کاربر فیلتری را تغییر می دهد یا به صفحه بعدی می رود، فقط نتایج View به روزرسانی می شوند، نه کل صفحه.

مثال عملی 5: ایجاد یک View پیشرفته با فیلترهای AJAX برای جستجوی پویا

تصور کنید یک View داریم که لیستی از محصولات را نمایش می دهد و می خواهیم فیلترهایی بر اساس دسته بندی و قیمت داشته باشیم که به صورت آژاکس عمل کنند.

1. یک View جدید از نوع Content (محتوا) ایجاد کنید. نام آن را Products بگذارید.
2. یک Page Display اضافه کنید و مسیر آن را /products تنظیم کنید.
3. فیلدهایی مانند عنوان محصول و قیمت را اضافه کنید.
4. در بخش Filter criteria (معیارهای فیلتر)، فیلترهایی برای دسته بندی محصول (مثلاً یک فیلد Term Reference) و قیمت (مثلاً یک فیلد عددی) اضافه کنید.
5. مطمئن شوید که گزینه Expose this filter to visitors برای هر فیلتر فعال باشد.
6. به بخش Advanced بروید و گزینه Use AJAX را روی Yes تنظیم کنید.
7. View را ذخیره کنید.

حالا، وقتی به مسیر /products در وب سایت خود مراجعه می کنید، مشاهده خواهید کرد که تغییر فیلترها یا کلیک بر روی لینک های صفحه بندی، بدون رفرش کامل صفحه، نتایج را به روزرسانی می کند. این یک تجربه کاربری بسیار روان و مدرن را فراهم می آورد که به کاربران اجازه می دهد تا به سرعت محصولات مورد نظر خود را پیدا کنند.

نکات پیشرفته و بهترین روش ها (Advanced Tips & Best Practices)

پیاده سازی آژاکس فراتر از اصول اولیه است. برای اطمینان از عملکرد بهینه، امنیت و تجربه کاربری بالا، رعایت برخی نکات پیشرفته و بهترین روش ها ضروری است. توسعه دهنده ای که به این نکات توجه می کند، می تواند پروژه هایی پایدارتر و باکیفیت تر ایجاد کند.

مدیریت کش (Caching)

کشینگ در دروپال یک سیستم پیچیده و قدرتمند است که برای افزایش عملکرد وب سایت طراحی شده است. هنگام استفاده از آژاکس، مدیریت صحیح کش اهمیت دوچندانی پیدا می کند، زیرا محتوای به روزرسانی شده باید به درستی و بدون تأخیر به کاربر نمایش داده شود.

• Cache Contexts: این قابلیت دروپال به شما اجازه می دهد تا کش محتوا را بر اساس زمینه های مختلف (مانند کاربر فعلی، زبان، مسیر URL و غیره) مدیریت کنید. برای پاسخ های آژاکس که محتوای شخصی سازی شده دارند، باید Cache Contexts مناسب را به پاسخ های خود اضافه کنید.
• Cache Tags: با اختصاص تگ های کش به محتوای خود، می توانید در صورت تغییر آن محتوا، کش مربوطه را به صورت هدفمند باطل کنید. این تضمین می کند که کاربران همیشه جدیدترین داده ها را دریافت کنند. برای مثال، اگر یک بلاک محتوای خاصی را با آژاکس به روز می کند، باید تگ های کش مرتبط با آن محتوا (مانند node:X) را به پاسخ آژاکس اضافه کنید.

امنیت (Security)

هر تعامل با سرور، چه با آژاکس و چه بدون آن، پتانسیل آسیب پذیری های امنیتی را دارد. دروپال ابزارهای قدرتمندی برای حفظ امنیت فراهم می کند، اما توسعه دهنده نیز باید هوشیار باشد.

• جلوگیری از حملات رایج (XSS, CSRF):
  • XSS (Cross-Site Scripting): همیشه تمام ورودی های کاربر را در سمت سرور به دقت پاکسازی (Sanitize) کنید تا از تزریق کدهای مخرب جاوااسکریپت جلوگیری شود. هرگز ورودی خام کاربر را مستقیماً در خروجی HTML قرار ندهید.
  • CSRF (Cross-Site Request Forgery): دروپال به صورت پیش فرض توکن های امنیتی (CSRF tokens) را در فرم ها مدیریت می کند. هنگام ساخت درخواست های آژاکس سفارشی، اطمینان حاصل کنید که این توکن ها به درستی ارسال و اعتبارسنجی می شوند.
• اعتبارسنجی دقیق ورودی کاربر در سمت سرور: حتی اگر در سمت کلاینت اعتبارسنجی انجام می دهید، همیشه باید ورودی کاربر را در سمت سرور نیز اعتبارسنجی کنید. کدهای سمت کلاینت به راحتی قابل دستکاری هستند.
• مدیریت مجوزهای دسترسی (Permissions): اطمینان حاصل کنید که کنترل کننده ها و Callbackهای آژاکس شما، فقط برای کاربرانی قابل دسترسی باشند که مجوزهای لازم را دارند. از هوک _permission در فایل های .routing.yml استفاده کنید.

عملکرد (Performance)

هدف اصلی آژاکس بهبود عملکرد است، اما پیاده سازی نادرست می تواند به جای بهبود، باعث کاهش عملکرد شود.

• بهینه سازی پاسخ های AJAX: فقط داده های مورد نیاز را از سرور به کلاینت ارسال کنید. از ارسال ساختارهای کامل فرم یا اشیاء بزرگ که نیازی به آن ها ندارید، خودداری کنید.
• کاهش تعداد درخواست های غیرضروری: از ارسال درخواست های آژاکس به صورت مکرر و بی رویه خودداری کنید. از Debouncing و Throttling در جاوااسکریپت برای کنترل نرخ رویدادها (مانند تایپ کاربر) استفاده کنید.
• استفاده از Lazy Loading: محتوایی که بلافاصله به آن نیاز نیست را به صورت Lazy Load (بارگذاری تأخیری) با آژاکس بارگذاری کنید. این کار زمان بارگذاری اولیه صفحه را کاهش می دهد.

دیباگ کردن (Debugging)

عیب یابی مشکلات آژاکس می تواند چالش برانگیز باشد، زیرا بسیاری از عملیات در پشت صحنه اتفاق می افتند. اما ابزارهایی برای کمک به توسعه دهندگان وجود دارد.

• استفاده از ابزارهای مرورگر (Developer Tools): از تب Network در ابزارهای توسعه دهنده مرورگر خود برای مشاهده درخواست ها و پاسخ های آژاکس استفاده کنید. می توانید وضعیت HTTP، محتوای درخواست و پاسخ، و زمان بندی آن را بررسی کنید.
• استفاده از ماژول های دیباگ دروپال (مانند Devel): ماژول Devel امکانات قدرتمندی برای دیباگ کردن دروپال فراهم می کند. می توانید از dpm() برای نمایش متغیرها در پیام های دروپال، یا از XDebug برای دیباگ کردن کدهای PHP در Callbackهای آژاکس استفاده کنید.
• لاگ برداری: از سیستم لاگ دروپال (Drupal::logger('mymodule')->warning('پیام خطا')) برای ثبت اطلاعات مربوط به درخواست ها و پاسخ های آژاکس در سمت سرور استفاده کنید.

ملاحظات تجربه کاربری (UX/UI)

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

• ارائه بازخورد واضح به کاربر:
  • پیام های موفقیت/خطا: پس از هر عملیات آژاکس، یک پیام واضح (مثلاً با استفاده از AjaxResponse::addCommand(new ReplaceCommand('#message-area', $message)) یا drupal_set_message()) به کاربر نمایش دهید.
  • انیمیشن های بارگذاری: همان طور که قبلاً ذکر شد، استفاده از throbber یا fullscreen progress indication در حین انجام عملیات آژاکس ضروری است.
• مدیریت تاریخچه مرورگر با AJAX (اختیاری – pushState/replaceState): برای سایت های تک صفحه ای (Single Page Applications) که به شدت به آژاکس متکی هستند، ممکن است نیاز باشد تا با استفاده از History API مرورگر (pushState و replaceState) آدرس URL را به روزرسانی کنید. این کار به کاربران اجازه می دهد تا از دکمه های بازگشت و جلو مرورگر استفاده کنند و لینک های مستقیم به وضعیت های خاصی از برنامه را به اشتراک بگذارند.

پیاده سازی موفقیت آمیز آژاکس در دروپال، نیازمند درک عمیق از معماری هسته، توجه به جزئیات امنیتی و تمرکز بر ارائه بهترین تجربه کاربری است. با رعایت بهترین روش ها، می توان به نهایت کارایی و پویایی در وب سایت دست یافت.

جمع بندی و نتیجه گیری

در این مقاله، تلاش شد تا یک راهنمای جامع برای پیاده سازی و استفاده از آژاکس در دروپال ارائه شود. از معرفی مفاهیم پایه آژاکس و چرایی اهمیت آن در دروپال، تا بررسی معماری آن، و سپس ارائه مثال های عملی برای فرم ها، ماژول های سفارشی و Views، سعی بر این بود که مسیری روشن برای توسعه دهندگان ترسیم شود. اهمیت استفاده از آژاکس در دروپال، در بهبود تجربه کاربری، افزایش سرعت سایت و کاهش بار سرور غیرقابل انکار است.

همان طور که در طول مقاله به آن اشاره شد، قابلیت آژاکس در دروپال نه تنها به ایجاد فرم های تعاملی و به روزرسانی پویا کمک می کند، بلکه با فعال سازی آن در Views، امکان ارائه فیلترها و صفحه بندی بدون رفرش کامل صفحه را نیز فراهم می سازد. این امر به کاربران حس سرعت و پاسخگویی می دهد که در دنیای امروز وب، یک مزیت رقابتی بزرگ محسوب می شود.

با این حال، باید به خاطر داشت که پیاده سازی آژاکس در دروپال، نیازمند دقت و توجه به جزئیات است. مدیریت صحیح کش، رعایت اصول امنیتی (مانند جلوگیری از XSS و CSRF)، بهینه سازی عملکرد و ارائه بازخورد مناسب به کاربر، از نکات کلیدی هستند که نباید نادیده گرفته شوند. توسعه دهندگان باید همواره به این موارد توجه داشته باشند تا پروژه هایی پایدار، امن و کارآمد ارائه دهند. با دانش و تجربه کافی در پیاده سازی و استفاده از آژاکس در دروپال، می توان سایت هایی ساخت که نه تنها قدرتمند هستند، بلکه کاربران را با خود همراه و از تجربه کاربری آن ها راضی نگه می دارند.