چگونه از توابع WooCommerce برای توسعه قالب وردپرس استفاده کنیم؟

اولین بار که یک قالب اختصاصی برای یک فروشگاه ووکامرسی ساختم، به این نتیجه رسیدم که ووکامرس در واقع یک وردپرس کوچک درون وردپرس است: سیستم قالب اختصاصی، هوک‌های مستقل، توابع داده خاص و حتی ساختار فایل مخصوص به خود. اگر توسعه‌دهنده‌ای فقط با هسته وردپرس آشنا باشد و بخواهد روی ووکامرس کار کند، در همان ساعات اولیه با دیوارهایی روبه‌رو می‌شود که با دانش عمومی وردپرس قابل عبور نیستند. امروز می‌خواهم به این پرسش پاسخ بدهم: چگونه از توابع WooCommerce برای توسعه قالب وردپرس استفاده کنیم؟ اگر با مفهوم پایه‌ای این افزونه فروشگاهی آشنایی کامل ندارید، ابتدا مطالعه ووکامرس چیست و چگونه فروشگاه اینترنتی بسازیم نقطه شروع خوبی است. همچنین برای درک چارچوب کلی Template Override، می‌توانید نگاهی به تعریف Template Method Pattern بیندازید که اساس فلسفه طراحی این سیستم است.

چرا توسعه قالب ووکامرس با وردپرس خام متفاوت است؟

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

در سطح فنی، این سه تفاوت به این معناست که یک توسعه‌دهنده قالب وردپرس که می‌خواهد وارد فضای ووکامرس شود، باید سه لایه دانش جدید را بپذیرد. لایه اول، ساختار فایل ووکامرس در قالب است که مسیر پوشه `woocommerce` در ریشه قالب را شامل می‌شود. لایه دوم، توابع ووکامرس است که از فضای نام `wc_` یا کلاس `WC()` استفاده می‌کنند. لایه سوم، هوک‌های ووکامرس است که با پیشوند `woocommerce_` شروع می‌شوند. آگاهی از این سه لایه، پیش‌نیاز هر پروژه فروشگاهی جدی است.

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

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

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

ساختار فایل و پوشه ووکامرس در قالب

ساختار فایل و پوشه ووکامرس در قالب، اولین چیزی است که هر توسعه‌دهنده قالب باید بفهمد. ووکامرس به‌طور پیش‌فرض یک پوشه اختصاصی با نام `woocommerce` در ریشه قالب شما ایجاد می‌کند که در آن تمام فایل‌های قالب قابل override قرار می‌گیرند.

ساختار پیش‌فرض این پوشه به‌شرح زیر است:

your-theme/
├── woocommerce/
│   ├── single-product.php
│   ├── archive-product.php
│   ├── content-product.php
│   ├── cart/
│   │   ├── cart.php
│   │   ├── cart-empty.php
│   │   └── cart-item-data.php
│   ├── checkout/
│   │   ├── form-checkout.php
│   │   └── review-order.php
│   ├── loop/
│   │   ├── loop-start.php
│   │   ├── loop-end.php
│   │   ├── price.php
│   │   └── add-to-cart.php
│   ├── single-product/
│   │   ├── product-image.php
│   │   ├── price.php
│   │   ├── title.php
│   │   └── tabs/
│   └── global/
│       ├── breadcrumb.php
│       └── form-login.php

نکته مهم این است که این ساختار، یک نسخه از ساختار پیش‌فرض ووکامرس است که در پوشه `templates` افزونه قرار دارد. شما با ایجاد پوشه `woocommerce` در ریشه قالب خود و کپی‌کردن فایل‌های موردنیاز در همان مسیر، آن‌ها را override می‌کنید. ووکامرس ابتدا در قالب شما جستجو می‌کند و اگر فایل مورد نظر را پیدا نکرد، از نسخه پیش‌فرض افزونه استفاده می‌کند.

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

سیستم Template Override: قلب توسعه قالب ووکامرس

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

در سطح فنی، ووکامرس از تابع `wc_get_template` برای بارگذاری قالب استفاده می‌کند که مسیر جستجوی زیر را طی می‌کند:

1. پوشه `woocommerce` در قالب فرزند (اگر وجود داشته باشد)
2. پوشه `woocommerce` در قالب والد
3. پوشه `templates` در افزونه ووکامرس

این ترتیب جستجو، به شما اجازه می‌دهد نسخه خودتان را در قالب قرار دهید و ووکامرس به‌طور خودکار از آن استفاده کند. برای override یک فایل، فقط باید آن را در همان مسیر نسبی در پوشه `woocommerce` قالب خود کپی کنید:

// برای override کردن فایل single-product/price.php
// فایل ووکامرس اصلی در:
wp-content/plugins/woocommerce/templates/single-product/price.php

// فایل override شده در قالب شما در:
wp-content/themes/your-theme/woocommerce/single-product/price.php

نکته مهم درباره Template Override، تشخیص فایل‌های به‌روز شده است. ووکامرس در پنل مدیریت، بخشی به‌نام Status دارد که در آن فهرست فایل‌های override شده و فایل‌های قدیمی نمایش داده می‌شود. توصیه من این است که پس از هر بروزرسانی ووکامرس، این بخش را بررسی کنید و فایل‌های override شده را با نسخه جدید هماهنگ کنید.

در Template Override، قاعده طلایی این است: هرچه فایل‌های کمتری را override کنید، قالب شما پایدارتر خواهد بود. اگر می‌توانید یک تغییر کوچک را با هوک انجام دهید، هرگز فایل قالب را override نکنید. فایل override شده، تعهد بلندمدت شما به هماهنگی با هر بروزرسانی ووکامرس است.

تجربه‌ای که در پروژه‌های واقعی داشته‌ام این است: در قالب‌هایی که تعداد زیادی از فایل‌های ووکامرس را override کرده‌ام، با هر بروزرسانی، بین دو تا چهار ساعت زمان صرف بررسی و هماهنگی می‌شود. در مقابل، قالب‌هایی که از هوک‌ها به‌جای override استفاده می‌کنند، با هر بروزرسانی، تقریباً بدون هیچ تغییری کار می‌کنند. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در هوک‌های وردپرس برای ووکامرس نوشته‌ام نقطه شروع خوبی است.

اعلام پشتیبانی قالب از ووکامرس

اعلام پشتیبانی قالب از ووکامرس، اولین قدم در توسعه قالب فروشگاهی است. بدون این اعلام، ووکامرس ممکن است هشدارهایی نمایش دهد یا از قابلیت‌های پیشرفته خود محروم بماند. اعلام پشتیبانی از طریق تابع `add_theme_support` و در هوک `after_setup_theme` انجام می‌شود.

add_action( 'after_setup_theme', function() {
  add_theme_support( 'woocommerce', array(
    'thumbnail_image_width' => 400,
    'single_image_width' => 800,
    'product_grid' => array(
      'default_columns' => 4,
      'default_rows' => 3,
      'min_columns' => 2,
      'max_columns' => 6,
      'min_rows' => 1,
      'max_rows' => 6,
    ),
  ) );
  add_theme_support( 'wc-product-gallery-zoom' );
  add_theme_support( 'wc-product-gallery-lightbox' );
  add_theme_support( 'wc-product-gallery-slider' );
} );

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

تجربه‌ای که در پروژه‌های واقعی به آن رسیده‌ام این است: در قالب‌هایی که اعلام پشتیبانی از گالری محصول را فراموش کرده‌ام، مشتریان با مشکل «تصاویر محصول کلید نمی‌شوند» روبه‌رو شده‌اند. این مشکل به‌طور معمول یک هفته طول می‌کشد تا تشخیص داده شود چون به‌نظر می‌رسد گالری کار می‌کند اما قابلیت‌های تعاملی آن غیرفعال است. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در سفارشی‌سازی صفحه محصول در ووکامرس نوشته‌ام به‌طور کامل این موضوع را باز می‌کند.

توابع و هوک‌های Product Loop

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

در سطح فنی، Product Loop از مجموعه‌ای از فایل‌های قالب و هوک‌ها استفاده می‌کند که هرکدام یک بخش از کارت محصول را نمایش می‌دهند:

<?php
// حلقه محصولات در archive-product.php
if ( woocommerce_product_loop() ) {
  woocommerce_product_loop_start();
  while ( have_posts() ) {
    the_post();
    wc_get_template_part( 'content', 'product' );
  }
  woocommerce_product_loop_end();
} else {
  do_action( 'woocommerce_no_products_found' );
}
?>

سه تابع اصلی در این حلقه عبارتند از: `woocommerce_product_loop()` که بررسی می‌کند آیا محصولی وجود دارد، `woocommerce_product_loop_start()` و `woocommerce_product_loop_end()` که قالب شروع و پایان حلقه را تولید می‌کنند، و `wc_get_template_part()` که فایل قالب کارت محصول را بارگذاری می‌کند.

هوک‌های مهم در Product Loop به‌شرح زیر هستند:

تجربه‌ای که در پروژه‌های واقعی به آن رسیده‌ام این است: در فروشگاه‌هایی که نیاز به نمایش اطلاعات اضافه روی کارت محصول دارند (مثل امتیاز، تعداد نظرات یا برچسب «جدید»)، استفاده از هوک `woocommerce_after_shop_loop_item_title` انتخاب بهتری از override فایل `content-product.php` است چون این رویکرد در آپدیت‌های ووکامرس پایدارتر است. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در مهم‌ترین هوک‌های وردپرس کدامند نوشته‌ام نقطه شروع خوبی است.

سفارشی‌سازی صفحه محصول تکی

سفارشی‌سازی صفحه محصول تکی، یکی از پرکاربردترین کارها در توسعه قالب ووکامرس است. صفحه محصول تکی از چند بخش اصلی تشکیل شده: تصویر محصول، عنوان، قیمت، توضیح کوتاه، دکمه افزودن به سبد و تب‌های اطلاعات (توضیحات، نظرات، اطلاعات اضافه). هر بخش از این صفحه، از طریق هوک‌های اختصاصی قابل سفارشی‌سازی است.

هوک‌های مهم در صفحه محصول تکی به‌شرح زیر هستند:

// ساختار پیش‌فرض صفحه محصول
do_action( 'woocommerce_before_single_product' );

// تصویر محصول
do_action( 'woocommerce_before_single_product_summary' );
do_action( 'woocommerce_before_single_product_summary' );

// خلاصه محصول
do_action( 'woocommerce_single_product_summary' );
// شامل: title، rating، price، excerpt، add_to_cart، meta، sharing

do_action( 'woocommerce_after_single_product_summary' );
// شامل: tabs، related products، upsells

do_action( 'woocommerce_after_single_product' );

سه هوک پرکاربرد که در پروژه‌های واقعی بیشترین استفاده را داشته‌ام:

هوک woocommerce_single_product_summary

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

add_action( 'woocommerce_single_product_summary', 'custom_product_badge', 5 );

function custom_product_badge() {
  echo '<span class="product-badge">جدید</span>';
}

در این مثال، با تنظیم اولویت روی عدد ۵ (کوچکتر از پیش‌فرض ۱۰)، بخش جدید قبل از عنوان محصول نمایش داده می‌شود. اگر اولویت را روی ۲۵ بگذارید، بخش جدید پس از دکمه سبد نمایش داده می‌شود.

هوک woocommerce_product_tabs

این هوک به شما اجازه می‌دهد تب‌های صفحه محصول را سفارشی کنید. برای افزودن، حذف یا جابه‌جایی تب‌ها:

add_filter( 'woocommerce_product_tabs', function( $tabs ) {
  // حذف تب نظرات
  unset( $tabs['reviews'] );

  // افزودن تب جدید
  $tabs['shipping'] = array(
    'title' => 'ارسال و مرجوعی',
    'priority' => 25,
    'callback' => 'custom_shipping_tab_content',
  );

  return $tabs;
} );

هوک woocommerce_related_products_args

این فیلتر آرگومان‌های کوئری محصولات مرتبط را تغییر می‌دهد:

add_filter( 'woocommerce_related_products_args', function( $args ) {
  $args['posts_per_page'] = 6;
  $args['columns'] = 3;
  return $args;
} );

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

در صفحه محصول ووکامرس، انتخاب بین هوک و override فایل قالب یک تصمیم معماری است: هوک‌ها پایداری می‌دهند اما انعطاف محدودی دارند؛ override آزادی کامل می‌دهد اما نگهداری بلندمدت را سخت می‌کند. بهترین توسعه‌دهندگان، ترکیبی از این دو را انتخاب می‌کنند.

توابع دسترسی به داده محصول

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

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

<?php
global $product;
$sku = $product->get_sku();
$stock = $product->get_stock_quantity();
$rating = $product->get_average_rating();
?>

<div class="product-meta">
  <?php if ( $sku ) : ?>
    <p><strong>کد محصول:</strong> <?php echo esc_html( $sku ); ?></p>
  <?php endif; ?>

  <?php if ( $stock !== null ) : ?>
    <p><strong>موجودی:</strong> <?php echo esc_html( $stock ); ?> عدد</p>
  <?php endif; ?>

  <?php if ( $rating > 0 ) : ?>
    <p><strong>امتیاز:</strong> <?php echo esc_html( $rating ); ?> از ۵</p>
  <?php endif; ?>
</div>

نکته مهم درباره استفاده از این توابع، استفاده از `esc_html` و مشابه آن برای پاک‌سازی خروجی است. توابع ووکامرس داده خام برمی‌گردانند و اگر شما آن‌ها را مستقیم چاپ کنید، ممکن است به باگ امنیتی منجر شود. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در توابع پرکاربرد وردپرس کدامند نوشته‌ام نقطه شروع خوبی است.

سفارشی‌سازی سبد خرید و تسویه‌حساب

سفارشی‌سازی سبد خرید و تسویه‌حساب، یکی از پرچالش‌ترین بخش‌های توسعه قالب ووکامرس است چون این صفحات، به‌طور مستقیم روی درآمد فروشگاه اثر می‌گذارند و هر تغییر، می‌تواند نرخ تبدیل را به‌طور محسوس تغییر دهد. سبد خرید و تسویه‌حساب در ووکامرس، معمولاً از طریق بلوک‌های Gutenberg یا شورت‌کدها نمایش داده می‌شوند که هرکدام چالش‌های خاص خود را دارند.

هوک‌های مهم در سبد خرید و تسویه‌حساب به‌شرح زیر هستند:

فیلترهای مهم برای سفارشی‌سازی فیلدهای تسویه‌حساب:

add_filter( 'woocommerce_checkout_fields', function( $fields ) {
  // حذف فیلد شرکت
  unset( $fields['billing']['billing_company'] );

  // تغییر ترتیب فیلدها
  $fields['billing']['billing_phone']['priority'] = 20;

  // افزودن فیلد سفارشی
  $fields['billing']['billing_mobile_extra'] = array(
    'label' => 'شماره موبایل دوم',
    'required' => false,
    'class' => array( 'form-row-wide' ),
    'priority' => 25,
  );

  return $fields;
} );

نکته مهم درباره سفارشی‌سازی سبد خرید و تسویه‌حساب، سازگاری با بلوک‌های Gutenberg است. در نسخه‌های جدید ووکامرس، سبد خرید و تسویه‌حساب به‌طور پیش‌فرض با بلوک‌های Gutenberg نمایش داده می‌شوند و برخی از هوک‌ها در این حالت کار نمی‌کنند. برای استفاده از هوک‌های کلاسیک، باید یا از شورت‌کدهای قدیمی استفاده کنید یا از بلاک‌های ووکامرس با افزونه‌های سازگار. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در سفارشی‌سازی سبد خرید و تسویه‌حساب ووکامرس نوشته‌ام به‌طور کامل این موضوع را باز می‌کند.

توابع شرطی مخصوص ووکامرس

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

نمونه استفاده ترکیبی از این توابع:

add_action( 'wp_enqueue_scripts', function() {
  // بارگذاری استایل مخصوص صفحه محصول
  if ( is_product() ) {
    wp_enqueue_style( 'product-style', get_template_directory_uri() . '/css/product.css' );
  }

  // بارگذاری استایل مخصوص سبد و تسویه
  if ( is_cart() || is_checkout() ) {
    wp_enqueue_style( 'checkout-style', get_template_directory_uri() . '/css/checkout.css' );
  }
} );

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

بارگذاری استایل و اسکریپت در قالب ووکامرس

بارگذاری استایل و اسکریپت در قالب ووکامرس، یکی از بخش‌های مهم توسعه قالب فروشگاهی است چون مستقیماً روی سرعت سایت اثر می‌گذارد. ووکامرس به‌طور پیش‌فرض چندین فایل CSS و JS بارگذاری می‌کند که برخی از آن‌ها فقط در صفحات خاص لازم هستند. اگر این فایل‌ها در همه صفحات بارگذاری شوند، حجم صفحات به‌طور محسوس افزایش می‌یابد.

نکته مهم درباره بارگذاری استایل ووکامرس، غیرفعال‌سازی استایل‌های پیش‌فرض در صفحات غیرمرتبط است:

add_action( 'wp_enqueue_scripts', function() {
  // حذف استایل ووکامرس در صفحات غیرمرتبط
  if ( ! is_woocommerce() && ! is_cart() && ! is_checkout() && ! is_account_page() ) {
    wp_dequeue_style( 'woocommerce-general' );
    wp_dequeue_style( 'woocommerce-layout' );
    wp_dequeue_style( 'woocommerce-smallscreen' );
    wp_dequeue_script( 'wc-cart-fragments' );
    wp_dequeue_script( 'woocommerce' );
    wp_dequeue_script( 'wc-add-to-cart' );
  }
}, 99 );

نکته دومی که در بارگذاری استایل ووکامرس اهمیت دارد، استایل‌های مخصوص افزونه‌ها است. اگر فروشگاه شما از افزونه‌های ووکامرس متعددی استفاده می‌کند، هر افزونه ممکن است فایل‌های CSS و JS خودش را بارگذاری کند. توصیه من این است که فهرست تمام فایل‌های بارگذاری شده در صفحات مختلف را با ابزارهایی مثل Query Monitor بررسی کنید و فایل‌های غیرضروری را حذف کنید.

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

هوک‌های کلیدی ووکامرس در توسعه قالب

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

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

در توسعه قالب ووکامرس، هوک‌ها و فایل‌های override شده مثل دو ابزار مکمل هستند: هوک‌ها انعطاف کمتری دارند اما نگهداری بلندمدت را ساده می‌کنند؛ فایل‌های override انعطاف کامل می‌دهند اما شما را به هماهنگی مداوم با بروزرسانی ووکامرس متعهد می‌کنند. در ۹۰ درصد پروژه‌ها، ترکیبی از این دو، بهترین گزینه است.

چرا چایلد تم در فروشگاه ضروری است

چایلد تم در فروشگاه ووکامرس، نه یک توصیه بلکه یک ضرورت است. اگر فایل‌های ووکامرس را مستقیماً در قالب اصلی خود override کنید، با هر بروزرسانی قالب، تغییرات شما پاک می‌شود. اگر از هوک‌ها در فایل `functions.php` قالب اصلی استفاده کنید، همان اتفاق می‌افتد. چایلد تم، راه‌حل استاندارد این مشکل است.

برای فروشگاه ووکامرس، ساختار چایلد تم مشابه چایلد تم وردپرس خام است اما با چند نکته مهم. اولین نکته این است که چایلد تم شما باید اعلام پشتیبانی از ووکامرس را در فایل `functions.php` خودش داشته باشد. دومین نکته این است که پوشه `woocommerce` باید در چایلد تم قرار بگیرد، نه در قالب والد. سومین نکته این است که تنظیمات ووکامرس (مثل تعداد محصولات در صفحه) در دیتابیس ذخیره می‌شود و با تغییر چایلد تم پاک نمی‌شود.

ساختار پیشنهادی چایلد تم برای فروشگاه ووکامرس:

your-shop-child/
├── style.css
├── functions.php
├── woocommerce/
│   ├── single-product/
│   │   └── price.php
│   ├── loop/
│   │   └── add-to-cart.php
│   └── cart/
│       └── cart.php
└── assets/
    ├── css/
    │   └── woocommerce-custom.css
    └── js/
        └── woocommerce-custom.js

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

اشتباهات رایج در توسعه قالب ووکامرس

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

• override فایل‌های زیاد بدون دلیل: هر فایل override شده، یک تعهد بلندمدت به هماهنگی با بروزرسانی ووکامرس است. قبل از هر override، بررسی کنید که آیا با هوک قابل حل است یا خیر.
• نداشتن چایلد تم: تغییرات در قالب اصلی، با اولین بروزرسانی قالب پاک می‌شود. چایلد تم در فروشگاه یک ضرورت است.
• فراموش‌کردن اعلام پشتیبانی گالری: بدون اعلام پشتیبانی از `wc-product-gallery-zoom`، `wc-product-gallery-lightbox` و `wc-product-gallery-slider`، گالری محصول به‌طور کامل کار نمی‌کند.
• بارگذاری استایل ووکامرس در همه صفحات: استایل و اسکریپت ووکامرس باید فقط در صفحات مرتبط بارگذاری شود تا سرعت صفحات دیگر کاهش نیابد.
• استفاده مستقیم از `$product` بدون global: در بسیاری از توابع هوک، `$product` در دسترس نیست و باید با `global $product` یا `wc_get_product` بازیابی شود.
• چاپ داده بدون پاک‌سازی: توابع ووکامرس داده خام برمی‌گردانند و باید با `esc_html` و مشابه آن پاک‌سازی شوند.
• نادیده‌گرفتن بلوک‌های Gutenberg: سبد خرید و تسویه‌حساب در نسخه‌های جدید ووکامرس به‌طور پیش‌فرض با بلوک‌ها نمایش داده می‌شوند و بسیاری از هوک‌های کلاسیک در این حالت کار نمی‌کنند.
• عدم بررسی تغییرات در بروزرسانی: ووکامرس ساختار فایل‌ها و توابع را در بروزرسانی‌های مهم تغییر می‌دهد و اگر این تغییرات بررسی نشوند، سایت شما ممکن است با خطا روبه‌رو شود.

اگر می‌خواهید درک عمیق‌تری از این اشتباهات داشته باشید، مقاله‌ای که در خطای قالب در ووکامرس و راه حل آن نوشته‌ام به‌طور کامل این موضوع را باز می‌کند.

پرسش‌های پرتکرار درباره توسعه قالب ووکامرس

این بخش را به سؤالاتی اختصاص داده‌ام که بیشتر در جلسه‌های مشاوره تکرار می‌شوند و پاسخ‌شان در تصمیم نهایی وزن زیادی دارد.

سیستم Template Override در ووکامرس چگونه کار می‌کند؟

ووکامرس از تابع `wc_get_template` برای بارگذاری قالب استفاده می‌کند که ترتیب جستجوی زیر را طی می‌کند: ابتدا پوشه `woocommerce` در قالب فرزند، سپس همان پوشه در قالب والد، و در نهایت پوشه `templates` در افزونه ووکامرس. برای override کردن یک فایل، باید آن را در مسیر نسبی مشابه در پوشه `woocommerce` قالب خود کپی کنید. پس از هر بروزرسانی ووکامرس، فایل‌های override شده را باید با نسخه جدید هماهنگ کنید.

چگونه اعلام پشتیبانی قالب از ووکامرس را انجام دهم؟

اعلام پشتیبانی از ووکامرس با تابع `add_theme_support( 'woocommerce', $args )` در هوک `after_setup_theme` انجام می‌شود. در این تابع، می‌توانید اندازه تصویر شاخص و تک‌تصویر، تعداد ستون‌های گرید و محدوده‌های آن را تعیین کنید. علاوه بر این، برای فعال‌سازی قابلیت‌های گالری محصول، باید سه اعلام پشتیبانی زیر را هم اضافه کنید: `wc-product-gallery-zoom`، `wc-product-gallery-lightbox` و `wc-product-gallery-slider`.

تفاوت هوک و override فایل در توسعه قالب ووکامرس چیست؟

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

چگونه یک محصول در قالب با کد نمایش دهم؟

برای نمایش یک محصول خاص در قالب، از تابع `wc_get_product( $product_id )` استفاده کنید که یک شیء محصول برمی‌گرداند. سپس می‌توانید از متدهای این شیء (مثل `get_name`، `get_price_html`، `get_image_id`) استفاده کنید. برای نمایش فهرست محصولات، از `wc_get_products( $args )` استفاده کنید که آرایه‌ای از اشیاء محصول برمی‌گرداند. مثال: `$products = wc_get_products( array( 'limit' => 10, 'status' => 'publish' ) );`.

چرا صفحه محصول ووکامرس در قالب من به‌هم ریخته است؟

به‌هم‌ریختگی صفحه محصول معمولاً به یکی از سه دلیل زیر رخ می‌دهد. دلیل اول، نبود اعلام پشتیبانی از ووکامرس در `functions.php` قالب است که باعث می‌شود ووکامرس از استایل‌های پیش‌فرض خودش استفاده کند. دلیل دوم، override ناقص فایل‌های قالب ووکامرس است که باعث می‌شود برخی بخش‌ها بارگذاری نشوند. دلیل سوم، عدم بارگذاری استایل سفارشی قالب در صفحات ووکامرس است. راه‌حل، بررسی فایل Status ووکامرس و مطابقت ساختار فایل‌ها با نسخه فعال است.

چگونه استایل ووکامرس را فقط در صفحات مرتبط بارگذاری کنم؟

با استفاده از توابع شرطی ووکامرس مثل `is_woocommerce()`، `is_cart()` و `is_checkout()` در هوک `wp_enqueue_scripts`، می‌توانید استایل‌های ووکامرس را فقط در صفحات مرتبط بارگذاری کنید. برای حذف استایل‌های پیش‌فرض، از `wp_dequeue_style` و `wp_dequeue_script` با اولویت بالا (مثلاً ۹۹) استفاده کنید. این کار می‌تواند حجم صفحات غیرمرتبط را تا سی درصد کاهش دهد.

چگونه فیلد سفارشی به فرم تسویه‌حساب اضافه کنم؟

برای افزودن فیلد سفارشی به فرم تسویه‌حساب، از فیلتر `woocommerce_checkout_fields` استفاده کنید. در این فیلتر، می‌توانید فیلد جدیدی به بخش `billing`، `shipping` یا `order` اضافه کنید و برای هرکدام `label`، `required`، `class` و `priority` تعیین کنید. سپس برای ذخیره مقدار فیلد، از هوک `woocommerce_checkout_update_order_meta` استفاده کنید. توجه داشته باشید که این هوک‌ها در بلوک‌های Gutenberg ممکن است کار نکنند و باید از شورت‌کدهای کلاسیک استفاده کنید.

آیا باید از چایلد تم برای فروشگاه ووکامرس استفاده کنم؟

بله، استفاده از چایلد تم در فروشگاه ووکامرس یک ضرورت است. در قالب اصلی، اگر تغییرات اعمال کنید، با اولین بروزرسانی قالب، همه تغییرات پاک می‌شود. چایلد تم به شما اجازه می‌دهد تغییرات را در لایه‌ای جداگانه اعمال کنید و با بروزرسانی قالب والد، تغییرات شما حفظ شود. علاوه بر این، اگر از پوشه `woocommerce` در چایلد تم استفاده کنید، فایل‌های override شده از قالب اصلی جدا می‌مانند.

چگونه هوک‌های ووکامرس را دیباگ کنم؟

برای دیباگ هوک‌های ووکامرس، سه ابزار اصلی وجود دارد. ابزار اول، افزونه Query Monitor است که نمایش دقیقی از تمام هوک‌ها و ترتیب اجرای آن‌ها ارائه می‌دهد. ابزار دوم، تابع `has_action` و `has_filter` است که بررسی می‌کند آیا یک هوک خاص ثبت شده است. ابزار سوم، نمایش متغیر `$wp_filter` در یک هوک انتهای صفحه است که تصویر کاملی از توابع ثبت‌شده روی هر هوک را نشان می‌دهد.

تفاوت `wc_get_product` و `WC_Product` چیست؟

تابع `wc_get_product( $id )` یک تابع کمکی است که با شناسه محصول، شیء `WC_Product` را برمی‌گرداند. کلاس `WC_Product` کلاس اصلی محصول در ووکامرس است که متدهای مختلفی برای دسترسی به داده محصول دارد. تفاوت اصلی این است که `wc_get_product` یک wrapper است که کش را مدیریت می‌کند، در حالی که استفاده مستقیم از `new WC_Product( $id )` این مدیریت را نادیده می‌گیرد. توصیه می‌شود همیشه از `wc_get_product` استفاده کنید چون کارآمدتر است و با نسخه‌های مختلف ووکامرس سازگار است.

آیا استفاده از توابع ووکامرس روی سرعت قالب اثر دارد؟

توابع ووکامرس به‌طور مستقیم اثر محسوسی روی سرعت قالب ندارند اما استفاده نادرست از آن‌ها می‌تواند به کندی منجر شود. سه نکته مهم در این زمینه وجود دارد: اول، کوئری‌های `wc_get_products` و `WP_Query` را در تعداد کم اجرا کنید. دوم، استایل و اسکریپت ووکامرس را فقط در صفحات مرتبط بارگذاری کنید. سوم، برای داده‌های ثابت از transient یا کش استفاده کنید تا با هر بازدید، کوئری تکراری اجرا نشود.

چه زمانی باید قالب سفارشی برای فروشگاه بسازم و چه زمانی از قالب آماده استفاده کنم؟

پاسخ این سؤال به سه عامل بستگی دارد. عامل اول، سطح تمایز برند است: اگر ظاهر فروشگاه، بخشی از هویت برند شماست، قالب سفارشی ارزش دارد. عامل دوم، بودجه و زمان است: قالب سفارشی معمولاً دو تا سه برابر قالب آماده زمان و هزینه می‌برد. عامل سوم، مهارت تیم است: اگر تیم فنی داخلی دارید، قالب سفارشی گزینه مناسبی است. در غیر این صورت، استفاده از یک قالب آماده مثل بهترین قالب‌های سازگار با ووکامرس و سفارشی‌سازی از طریق چایلد تم، اقتصادی‌تر است.

از سفارشی‌سازی تا فروشگاه حرفه‌ای

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

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

اگر تجربه‌ای از توسعه قالب ووکامرس دارید — چه موفق، چه ناامیدکننده — برایم جالب است که در دیدگاه‌ها بنویسید کدام بخش از این راهنما بیشترین اثر را روی پروژه شما داشت و کدام چالش در توسعه قالب فروشگاهی، بیشترین زمان را از شما گرفته است. تجربه‌های واقعی شما، این راهنما را برای خواننده بعدی دقیق‌تر و کاربردی‌تر خواهد کرد. 🛒