آموزش تابع get_block_template() در وردپرس و کاربرد آن

تابع get_block_template() در اکوسیستم بلاک‌ها و Full Site Editing (FSE) وردپرس برای واکشی تمپلیت‌های مبتنی بر بلاک طراحی شده است. این تابع به توسعه‌دهندگان اجازه می‌دهد تمپلیت‌های بلاکی مربوط به یک نوع نوشته، یک قالب خاص یا یک بخش از سایت را بازیابی کرده و سپس محتوای بلاک‌ها را بررسی یا رندر کنند.

چرا از get_block_template() استفاده کنیم؟

• دسترسی برنامه‌ریزی‌شده به تمپلیت‌های بلاکی بدون نیاز به بارگذاری مستقیم فایل‌های تم.
• امکان پردازش، آنالیز یا تغییر محتوا پیش از رندر کردن (مثلاً بازنویسی برخی بلاک‌ها یا افزودن wrapper).
• ایجاد fallback و منطق سفارشی برای تمپلیت‌ها در پلاگین‌ها یا توابع theme.

چه چیزی باز می‌گرداند؟

در نسخه‌های دارای FSE، این تابع معمولاً یک شیء مربوط به تمپلیت بلاکی (که شامل متادیتا و محتوای بلاک‌ها است) یا مقدار null در صورت عدم وجود تمپلیت برمی‌گرداند. شیء برگشتی معمولاً شامل محتوای HTML/بلاک‌ها و اطلاعاتی مثل slug یا نام تمپلیت است که می‌توان با آن کار کرد.

نمونه ساده: واکشی و رندر تمپلیت

<?php
if ( function_exists( 'get_block_template' ) ) {
    $template = get_block_template( 'post' ); // شناسه یا نام context
    if ( $template && ! empty( $template->content ) ) {
        echo do_blocks( $template->content );
    } else {
        echo '<p>Template not found.</p>';
    }
}
?>

توضیح: این قطعه ابتدا بررسی می‌کند که تابع get_block_template موجود باشد (برای سازگاری با نسخه‌های قدیمی‌تر وردپرس). سپس تمپلیت مربوط به context (مثلاً ‘post’) را واکشی می‌کند. اگر تمپلیت پیدا شد و محتوای بلاکی دارد، با استفاده از do_blocks() محتوای بلاک‌ها رندر می‌شود. در غیر این صورت پیام جایگزین نمایش داده می‌شود.

مثال پیشرفته‌تر: بررسی، اصلاح و رندر

<?php
if ( function_exists( 'get_block_template' ) ) {
    $template = get_block_template( 'post' );
    if ( $template && ! empty( $template->content ) ) {
        // تبدیل به آرایه بلاک‌ها برای دستکاری
        $blocks = parse_blocks( $template->content );

        // نمونه: اضافه کردن کلاس به اولین بلاک گروه
        if ( ! empty( $blocks ) && isset( $blocks[0]['attrs'] ) ) {
            $blocks[0]['attrs']['className'] = ( $blocks[0]['attrs']['className'] ?? '' ) . ' my-custom-class';
        }

        // بازسازی HTML بلاک‌ها و رندر
        $content = serialize_blocks( $blocks );
        echo do_blocks( $content );
    }
}
?>

توضیح: این کد محتوای تمپلیت را ابتدا با parse_blocks() به آرایه‌ای از بلاک‌ها تبدیل می‌کند تا بتوان آن‌ها را دستکاری کرد (مثلاً افزودن کلاس یا تغییر آتربیوها). سپس با serialize_blocks() دوباره به HTML تبدیل و با do_blocks() رندر می‌شود. این روش برای اعمال تغییرات برنامه‌ریزی‌شده بسیار کاربردی است.

بهینه‌سازی: کش کردن نتایج

<?php
function my_get_cached_block_template( $name ) {
    $cache_key = 'block_template_' . $name;
    $template = wp_cache_get( $cache_key );
    if ( false === $template ) {
        $template = function_exists( 'get_block_template' ) ? get_block_template( $name ) : null;
        wp_cache_set( $cache_key, $template, '', HOUR_IN_SECONDS );
    }
    return $template;
}
?>

توضیح: واکشی تمپلیت ممکن است هزینه‌بر باشد؛ با استفاده از API کش داخلی وردپرس می‌توان نتایج را برای بازدیدهای بعدی نگه داشت و بار سرور را کاهش داد. در مثال بالا از wp_cache_get و wp_cache_set استفاده شده است.

موارد استفاده عملی

• پلاگین‌هایی که چندین نوع تمپلیت بلاکی را مدیریت می‌کنند (مثلاً فروشگاه، آرشیو، تک نوشته) و نیاز به انتخاب/ویرایش آن‌ها دارند.
• سفارشی‌سازی دینامیک تمپلیت بر اساس نقش کاربر یا پارامترهای کوئری.
• ایجاد fallback‌های قابل کنترل برای سایت‌های میکس شده (بخشی FSE و بخشی کلاسیک).

نکات و چالش‌های معمول

• سازگاری: تابع در نسخه‌های قدیمی وردپرس ممکن است موجود نباشد؛ همیشه با function_exists بررسی کنید.
• فرمت شیء برگشتی: ممکن است ساختار داخلی تمپلیت بسته به نسخه و پیاده‌سازی theme تغییر کند؛ مستندات و کد هسته را بررسی کنید.
• امنیت و اعتبارسنجی: قبل از رندر محتوای ساختگی یا ورودی خارجی حتماً آن‌ها را اعتبارسنجی کنید.
• حافظه: واکشی و پردازش تمپلیت‌های بزرگ ممکن است حافظه زیادی مصرف کند؛ از کش و paginate منطقی استفاده کنید.

مقایسه سریع

نکات پیشرفته و توصیه‌های متخصصی

• در پلاگین‌های بزرگ از لایه انتزاعی استفاده کنید: یک تابع wrapper بنویسید که واکشی، کش و سازگاری را مدیریت کند تا تغییرات نسخه‌های وردپرس به راحتی هندل شود.
• برای تست، تمپلیت‌های FSE را در محیط توسعه (local) تغییر دهید و رفتار رندر را در شرایط مختلف بررسی کنید؛ نسخه‌های مختلف وردپرس ممکن است تغییراتی در شیء تمپلیت ایجاد کنند.
• اگر می‌خواهید تمپلیت‌ها را برای ویرایشی در رابط کاربری نمایش دهید، حتماً متادیتاهایی مانند نام و توضیح را نمایش دهید تا UX بهتری داشته باشید.

خلاصه کاربردی

تابع get_block_template() ابزار قدرتمندی برای توسعه‌دهندگانی است که با بلاک‌ها و FSE کار می‌کنند. با ترکیب این تابع با توابعی مانند parse_blocks، serialize_blocks و do_blocks می‌توانید تمپلیت‌ها را واکشی، دستکاری و رندر کنید. برای پایداری و عملکرد بهتر از بررسی وجود تابع، کش کردن نتایج و اعتبارسنجی محتوا استفاده کنید.

در صورتی که به مستندات نسخه وردپرس خود دسترسی دارید، همیشه Signature و ساختار شیء برگشتی را از هسته وردپرس (source) بررسی کنید تا از جزئیات پیاده‌سازی مطمئن شوید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال