چرا هر بار کد قالب را کپی می‌کنید؟ راهنمای تابع get_template_part
تابع get_template_part برای فراخوانی ماژولار بخش‌های قالب در وردپرس؛ بررسی پارامترها، slug و name، رفتار در Child Theme و اشتباهات رایج.
7 دقیقه مطالعه
چرا ماژولار کردن قالب ضروری است؟
در قالب‌های وردپرس، بخش‌های زیادی از HTML بین فایل‌های مختلف تکرار می‌شوند: کارت نوشته در صفحه اصلی و آرشیو، بخش محتوای نوشته در صفحات مختلف، اطلاعات نویسنده در چند نقطه و کارت محصول در صفحات فروشگاهی. اگر این بخش‌ها را در هر فایل جداگانه بنویسید، نگهداری قالب به کابوس تبدیل می‌شود. راه‌حل، استخراج این بخش‌های تکراری در فایل‌های جداگانه و فراخوانی آنها با تابعget_template_part() است. این رویکرد که به آن DRY (Don’t Repeat Yourself) گفته می‌شود، پایه هر قالب حرفه‌ای محسوب می‌شود.
تابع get_template_part چیست؟
تابعget_template_part() یک تابع هسته وردپرس است که در فایل wp-includes/general-template.php تعریف شده است. این تابع یک بخش قالب (Template Part) را بر پایه نام فایل و نامک مشخص‌شده بارگذاری می‌کند.
مکانیزم این تابع بر پایه locate_template() است: ابتدا در Child Theme جستجو می‌کند، سپس در Parent Theme. این رفتار باعث می‌شود کاربران بتوانند بخش‌های خاص را در Child Theme خود سفارشی کنند بدون تغییر فایل‌های والد.
نکته مهم این است که این تابع برخلاف get_header و get_footer نام فایل را از طریق دو پارامتر slug و name می‌سازد.
امضای تابع و پارامترها
امضای این تابع به‌شکل زیر است:function get_template_part( $slug, $name = null, $args = array() ) {
do_action( "get_template_part_{$slug}", $slug, $name, $args );
$templates = array();
$name = (string) $name;
if ( '' !== $name ) {
$templates[] = "{$slug}-{$name}.php";
}
$templates[] = "{$slug}.php";
locate_template( $templates, true, false, $args );
}slug)، نام عمومی بخش قالب است. پارامتر دوم (name)، نامک نسخه خاص است که به فایل اضافه می‌شود. پارامتر سوم (از وردپرس ۵.۵) امکان پاس دادن آرایه‌ای از داده‌ها به فایل قالب را فراهم می‌کند.
اگر نامک خاص داده شود، تابع ابتدا به دنبال فایل {slug}-{name}.php می‌گردد و اگر پیدا نشد، به فایل {slug}.php برمی‌گردد.
سازوکار داخلی و ترتیب جستجو
وقتیget_template_part() فراخوانی می‌شود، مراحل زیر اجرا می‌شوند:
- هوک get_template_part_{$slug} با پارامترها اجرا می‌شود
- اگر نامک خاص داده شده باشد، فایل {slug}-{name}.php به فهرست جستجو اضافه می‌شود
- فایل {slug}.php نیز به فهرست اضافه می‌شود
- تابع locate_template ابتدا در Child Theme، سپس در Parent Theme جستجو می‌کند
- در صورت پیدا شدن، فایل با require بارگذاری می‌شود
- اگر هیچ فایلی پیدا نشود، هیچ خطایی نمایش داده نمی‌شود اما بخش قالب رندر نمی‌شود
نکته مهم این است که اگر فایل پیدا نشود، هیچ هشداری داده نمی‌شود. این رفتار در ظاهر مفید است اما در عمل می‌تواند به نبود بخشی از قالب منجر شود بدون آنکه توسعه‌دهنده متوجه شود.
نقش slug و name در نام فایل
ترکیبslug و name امکان تعریف فایل‌های متعدد و اختصاصی برای هر بخش را فراهم می‌کند. این الگو در قالب‌های حرفه‌ای بسیار رایج است.
نمونه‌های رایج:
- get_template_part( 'content', 'page' ) → فایل content-page.php
- get_template_part( 'content', 'single' ) → فایل content-single.php
- get_template_part( 'content', get_post_type() ) → فایل content-{post_type}.php
- get_template_part( 'parts/card', 'product' ) → فایل parts/card-product.php
الگوی حرفه‌ای:
get_template_part( 'template-parts/content', get_post_type() );content.php عمومی برمی‌گردد.
کاربردهای عملی در قالب
الگوی رایج در حلقه:while ( have_posts() ) :
the_post();
get_template_part( 'template-parts/content', get_post_type() );
endwhile;template-parts/content.php:
<article <?php post_class(); ?>>
<h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
<div class="entry-summary"><?php the_excerpt(); ?></div>
</article>post_class برای تولید کلاس‌های استاندارد استفاده شده است. راهنمای این تابع در صفحه post_class آمده است.
پاس دادن داده به بخش قالب (از وردپرس ۵.۵):
get_template_part( 'template-parts/card', 'product', array(
'show_price' => true,
'badge_text' => __( 'جدید', 'mytheme' ),
) );template-parts/card-product.php، داده‌ها در متغیر $args قابل دسترسی هستند:
if ( ! empty( $args['show_price'] ) ) {
echo '<span class="price">' . wp_kses_post( wc_price( $product->get_price() ) ) . '</span>';
}رفتار در Child Theme
تابعget_template_part ابتدا در Child Theme جستجو می‌کند. برای سفارشی‌سازی یک بخش، کافی است فایل مربوطه را در همان مسیر نسبی در Child Theme بسازید.
نمونه: اگر قالب والد فایل template-parts/content.php داشته باشد و بخواهید نسخه سفارشی در Child Theme بسازید، فایل template-parts/content.php را در Child Theme ایجاد کنید.
نکته مهم: مسیر نسبی باید دقیقاً یکی باشد. اگر در Parent فایل در template-parts/content.php باشد، در Child هم باید در همان مسیر باشد.
برای مطالعه درباره ساختار Child Theme به راهنمای get_stylesheet_directory و راهنمای get_template_directory مراجعه کنید.
بررسی وجود فایل پیش از فراخوانی
یکی از الگوهای حرفه‌ای، بررسی وجود فایل پیش از فراخوانی است. با استفاده ازlocate_template می‌توان وجود فایل را بررسی کرد:
if ( locate_template( 'template-parts/hero.php' ) ) {
get_template_part( 'template-parts/hero' );
}locate_template در راهنمای locate_template به تفصیل بررسی شده است.
رویکرد بهتر، افزودن پیام در محیط توسعه:
if ( ! locate_template( 'template-parts/missing.php' ) && WP_DEBUG ) {
trigger_error( 'Template part missing: template-parts/missing.php', E_USER_WARNING );
}نکات امنیتی و اشتباهات رایج
اشتباه اول، نبود فایل است. اگر فایل بخش قالب وجود نداشته باشد، هیچ خطایی نمایش داده نمی‌شود و بخشی از صفحه ناقص می‌ماند. اشتباه دوم، نبود شرط برای بررسی وجود فایل است. پیش از فراخوانی، همیشه وجود فایل را بررسی کنید یا در محیط توسعه هشدار بگیرید. اشتباه سوم، نبود نسخه Child است. اگر قالب در Child Theme استفاده می‌شود، مسیر فایل‌های سفارشی باید نسبت به root قالب تعریف شود. اشتباه چهارم، نبود escape در فایل بخش است. اگر در فایل بخش، داده‌های پویا چاپ می‌کنید، از توابع escape استفاده کنید. راهنمای این تابع در صفحه esc_html آمده است. اشتباه پنجم، استفاده از این تابع برای فایل‌های PHP غیرقالبی است. برای include فایل‌های PHP درinc یا includes، از require با get_template_directory استفاده کنید.
اشتباه ششم، نبود تست در Child Theme است. باید هم در Parent Theme و هم در Child Theme رفتار کد را بررسی کنید.
اشتباه هفتم، استفاده از نام فایل با کاراکترهای خاص است. نام فایل باید فقط شامل حروف کوچک انگلیسی، عدد و خط تیره باشد.
تحلیل فنی پیشرفته
در نگاه مهندسی، تابعget_template_part() یک نقطه معماری در لایه رندر است که بر چند جنبه از سیستم اثر می‌گذارد. لایه اول لایه Override است. مکانیزم locate_template امکان Override کامل را در Child Theme فراهم می‌کند و این الگو یکی از پایه‌ای‌ترین اصول توسعه پایدار در وردپرس است.
لایه دوم لایه ماژولاریتی است. این تابع امکان استخراج بخش‌های تکراری را فراهم می‌کند و کد قالب را به ماژول‌های قابل تست و قابل نگهداری تبدیل می‌کند.
لایه سوم لایه کشینگ است. خروجی این تابع به‌طور پیش‌فرض کش نمی‌شود، اما HTML نهایی ممکن است کش شود. اگر بخش قالب داده‌های پویا داشته باشد، باید استراتژی کش مناسب انتخاب شود.
لایه چهارم لایه Performance است. فراخوانی مکرر این تابع در حلقه‌های طولانی می‌تواند تأثیر محسوسی داشته باشد. در پروژه‌های پرترافیک، بهتر است بخش‌های آماده و کش‌شده استفاده شوند.
لایه پنجم لایه امنیت است. اگر بخش قالب داده‌های پویا چاپ می‌کند، باید به escape توجه شود. این نکته در Child Themeهایی که از منابع خارجی داده دریافت می‌کنند، حیاتی است.
لایه ششم لایه Accessibility است. ساختار HTML بخش قالب باید با استانداردهای دسترسی‌پذیری سازگار باشد. برچسب‌های معنایی، ALT تصاویر و مدیریت فوکوس باید رعایت شوند.
لایه هفتم لایه Multisite است. در شبکه‌های Multisite، هر سایت می‌تواند قالب متفاوتی داشته باشد و این تابع در هر سایت بر پایه قالب همان سایت کار می‌کند.
لایه هشتم لایه تست است. تست‌های End-to-End باید همه بخش‌های قالب را پوشش دهند و مطمئن شوند که هیچ بخشی به‌درستی رندر نمی‌شود. مفاهیم پایه‌ای ماژولاریتی در Modular Programming در ویکی‌پدیا توضیح داده شده است.
برای مطالعه بیشتر روی توابع مرتبط، می‌توانید به راهنمای locate_template، راهنمای get_header، راهنمای get_footer، راهنمای get_sidebar، راهنمای body_class و راهنمای post_class مراجعه کنید.
پرسش‌های پرتکرار
تفاوتget_template_part و locate_template چیست؟ اولی فایل را بارگذاری می‌کند و دومی تنها مسیر فایل را برمی‌گرداند.
آیا get_template_part خطا می‌دهد اگر فایل نباشد؟ خیر، خطا نمی‌دهد و فقط فایل رندر نمی‌شود.
چطور داده به بخش قالب پاس دهیم؟ با پارامتر سوم (آرایه) که در متغیر $args قابل دسترسی است.
چطور بخش قالب را در Child Theme سفارشی کنیم؟ با ایجاد همان فایل در همان مسیر نسبی در Child Theme.
آیا می‌توان بخشی از قالب را از افزونه فراخوانی کرد؟ بله، با تابع locate_template و بررسی مسیر.
نتیجه و مسیر ادامه
تابعget_template_part() ابزار اصلی وردپرس برای ماژولار کردن قالب است. استفاده درست از آن یعنی ترکیب slug و name برای ساخت نام‌های پویا، بررسی وجود فایل پیش از فراخوانی، رعایت escape در بخش‌ها و تست در Parent و Child Theme. اشتباه‌های کوچک در این تابع اغلب به نبود بخشی از قالب منجر می‌شوند بدون آنکه توسعه‌دهنده متوجه شود.
اگر این تابع را در پروژه‌ای واقعی به کار برده‌اید و رفتار غیرمنتظره‌ای دیده‌اید — به‌خصوص در ترکیب با Child Theme یا در سایت‌های پربازدید — تجربه‌تان می‌تواند راهگشای دیگران باشد. کدام بخش بیشترین زمان را از شما گرفت؟ دیدگاه خود را بنویسید.
سعید کریمه
نویسنده
نویسنده در وردپرس کار.