ساخت شورت‌کد با کدنویسی وردپرس

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

شورت‌کد چیست و چه زمانی مناسب است؟

شورت‌کد، کد کوتاهی داخل براکت است که کاربر در محتوا درج می‌کند و وردپرس در زمان رندر، آن را به HTML تبدیل می‌کند. مثال: [my_gallery count="6"]. سه کاربرد اصلی: یک — محتوای تکرارشوندهٔ ساده. جدول قیمت، دکمه، کارت اطلاعات. دو — کدگذاری چیزهایی که در ویرایشگر سخت‌اند. مثال: ساختار تودرتوی HTML پیچیده. سه — اتصال به قابلیت افزونه. مثال: درج فرم یا گالری داخل نوشته. سه محدودیت شورت‌کد را هم بدانید: یک — شورت‌کد وابستگی به افزونه یا قالب می‌سازد. اگر افزونه حذف شود، شورت‌کد خام در محتوا می‌ماند. دو — در روز تغییر قالب یا افزونه، محتوای درج‌شده با شورت‌کدهای اختصاصی به متن خام تبدیل می‌شود. سه — برای UI تعاملی، شورت‌کد ابزار بهینه‌ای نیست؛ بلاک گوتنبرگ انتخاب بهتری است. تفصیل این تفکیک در افزودن قابلیت به وردپرس.

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

ساده‌ترین شورت‌کد

حداقلِ یک شورت‌کد، یک تابع و یک هوک است:

function my_shortcode_hello() {
    return '<p>سلام از شورت‌کد!</p>';
}
add_shortcode( 'my_hello', 'my_shortcode_hello' );

در محتوا:

[my_hello]

نکته: تابع باید HTML را return کند، نه echo. اشتباه رایجی که در تجربه‌های پشتیبانی زیاد دیده‌ام: استفاده از echo در تابع شورت‌کد، که خروجی را به بالای صفحه منتقل می‌کند. قاعده: در شورت‌کد، همیشه return. راهنمای هوک add_shortcode در هوک‌های وردپرس آمده است.

آتریبیوت‌ها با shortcode_atts

آتریبیوت، پارامترهای ورودی شورت‌کد است. الگوی استاندارد با shortcode_atts:

function my_shortcode_button( $atts ) {
    $atts = shortcode_atts( array(
        'text'  => 'کلیک کنید',
        'url'   => '#',
        'color' => 'primary',
    ), $atts, 'my_button' );

    return sprintf(
        '<a href="%s" class="btn btn-%s">%s</a>',
        esc_url( $atts['url'] ),
        esc_attr( $atts['color'] ),
        esc_html( $atts['text'] )
    );
}
add_shortcode( 'my_button', 'my_shortcode_button' );

در محتوا: [my_button text="خرید" url="https://example.com" color="success"]. نکته: پارامتر سوم shortcode_atts (نام شورت‌کد)، برای فیلترهای shortcode_atts_my_button است. با این، افزونه‌های دیگر می‌توانند مقادیر پیش‌فرض شما را تغییر دهند. راهنمای escape در PHP امن در وردپرس و پاک‌سازی داده‌ها.

شورت‌کد با محتوای درونی

برای شورت‌کدی که محتوای میان تگ‌ها را دربر می‌گیرد، الگو با پارامتر دوم $content:

function my_shortcode_note( $atts, $content = null ) {
    $atts = shortcode_atts( array(
        'type' => 'info',
    ), $atts, 'my_note' );

    return sprintf(
        '<div class="note note-%s">%s</div>',
        esc_attr( $atts['type'] ),
        do_shortcode( $content )
    );
}
add_shortcode( 'my_note', 'my_shortcode_note' );

در محتوا:

[my_note type="warning"]محتوای هشدار با [my_button] درونی[/my_note]

نکتهٔ مهم: پارامتر دوم همیشه وقتی که شورت‌کد به‌صورت جفتی استفاده می‌شود، پاس داده می‌شود. در تابع، همیشه بررسی کنید که $content !== null. فراخوانی do_shortcode( $content ) اجازه می‌دهد شورت‌کدهای تودرتو هم اجرا شوند. اگر نیاز به تودرتویی ندارید، از do_shortcode صرف‌نظر کنید. نمونه‌های بیشتر در این مقاله آمده است.

شورت‌کدهای تودرتو

اجرای تودرتوی شورت‌کد، کار می‌کند ولی محدودیت دارد. مثال تودرتوی معتبر:

[my_row]
  [my_column size="6"]ستون اول[/my_column]
  [my_column size="6"]ستون دوم[/my_column]
[/my_row]

سه نکته: یک — ترتیب اجرا: شورت‌کد داخلی، اول اجرا می‌شود. دو — کاراکترهای مخصوص: اگر شورت‌کد داخل [ ] غیرفعال باشد، از [[my_shortcode]] استفاده کنید — با دو براکت، شورت‌کد به‌صورت متن رندر می‌شود. سه — نبود شورت‌کد در آتریبیوت: آتریبیوت‌ها نمی‌توانند شورت‌کد داشته باشند. اگر لازم است، از فیلتر do_shortcode_tag برای پیش‌پردازش استفاده کنید.

امنیت در شورت‌کد

شورت‌کد، نقطهٔ ورود بالقوه‌ای برای XSS و SQLi است. سه قاعدهٔ الزامی: یک — پاک‌سازی هر آتریبیوت قبل از استفاده. از sanitize_text_field، sanitize_email، absint، esc_url_raw بسته به نوع. دو — escape خروجی. esc_html، esc_attr، esc_url. سه — محدودسازی محتوای درونی. اگر $content شامل HTML آزاد است، با wp_kses_post فیلتر کنید. الگو:

$atts = shortcode_atts( array(
    'url' => '#',
), $atts, 'my_button' );

// پاک‌سازی ورودی
$url = esc_url_raw( $atts['url'] );

// escape خروجی
return sprintf( '<a href="%s">%s</a>', esc_url( $url ), esc_html( $atts['text'] ) );

راهنمای کامل در PHP امن در وردپرس، پاک‌سازی داده‌ها، و اعتبارسنجی داده‌ها.

کجا شورت‌کد را بنویسیم؟

سه گزینه، به ترتیب اولویت: یک — افزونهٔ اختصاصی. بهترین انتخاب برای هر شورت‌کدی که قرار است سال‌ها بماند. دو — mu-plugins. برای شورت‌کد زیرساختی که نباید خاموش شود. سه — چایلد تم. فقط اگر شورت‌کد کاملاً ظاهری است و می‌دانید در روز تغییر قالب از دست می‌رود. قاعده: شورت‌کد در افزونه یا mu-plugins، هرگز در قالب والد. راهنمای تفصیلی در افزودن کد سفارشی به وردپرس و افزودن کد بدون ویرایش هسته.

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

در افزونهٔ جدی، شورت‌کد را در کلاس قرار دهید:

class My_Plugin_Shortcodes {
    public static function init() {
        add_shortcode( 'my_button', array( __CLASS__, 'button' ) );
        add_shortcode( 'my_note', array( __CLASS__, 'note' ) );
    }

    public static function button( $atts ) {
        $atts = shortcode_atts( array(
            'text' => 'کلیک کنید',
            'url'  => '#',
        ), $atts, 'my_button' );

        return sprintf(
            '<a href="%s" class="btn">%s</a>',
            esc_url( $atts['url'] ),
            esc_html( $atts['text'] )
        );
    }

    public static function note( $atts, $content = null ) {
        // ...
    }
}
My_Plugin_Shortcodes::init();

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

شورت‌کد و گوتنبرگ

در وردپرس مدرن، گوتنبرگ ویرایشگر اصلی است. شورت‌کد در گوتنبرگ به‌طور خودکار رندر می‌شود، ولی دو نکته: یک — بلاک Shortcode: گوتنبرگ بلوکی به نام Shortcode دارد که می‌توانید شورت‌کد را در آن درج کنید. دو — پیش‌نمایش: بعضی شورت‌کدها در پیش‌نمایش گوتنبرگ درست دیده نمی‌شوند؛ باید صفحه را ذخیره و در front-end ببینید. برای شورت‌کدهای پیچیده، بهتر است به بلاک اختصاصی مهاجرت کنید. چشم‌انداز کلی در گوتنبرگ و آیندهٔ ویرایش محتوا و روش ساخت بلاک در ساخت بلوک سفارشی گوتنبرگ. یک قاعدهٔ عملی برای تصمیم: اگر شورت‌کد شما فقط HTML ساده تولید می‌کند (مثل دکمه یا نقل‌قول)، بلوک بومی گوتنبرگ انتخاب بهتری است. اگر شورت‌کد، داده‌ای بیرونی می‌خواند یا نیاز به کامپوننت PHP دارد (مثل گالری از منبع بیرونی)، شورت‌کد بماند.

الگوهای پیشرفته

سه الگوی پیشرفته در ساخت شورت‌کد: یک — اسم‌گذاری معنادار با فضای نام. به‌جای button، از myplugin_button استفاده کنید تا با افزونه‌های دیگر تعارض نکنید. دو — کش نتیجه. اگر شورت‌کد، محاسبهٔ سنگین یا درخواست به سرویس بیرونی دارد، از transients برای کش استفاده کنید:

function my_shortcode_expensive( $atts ) {
    $atts = shortcode_atts( array( 'id' => 0 ), $atts, 'my_expensive' );
    $cache_key = 'my_sc_' . absint( $atts['id'] );
    $output = get_transient( $cache_key );
    if ( $output === false ) {
        $output = /* محاسبه */;
        set_transient( $cache_key, $output, HOUR_IN_SECONDS );
    }
    return $output;
}

راهنمای ترنزینت در ترنزینت‌ها در وردپرس. سه — Context-Aware. شورت‌کدی که هم در محتوا و هم در ویجت استفاده می‌شود، باید بتواند تفاوت را تشخیص دهد. از is_singular() و توابع مشابه برای تنظیم رفتار استفاده کنید. تجربه‌های میدانی من در این مورد: در پروژه‌ای که ۳۰ شورت‌کد اختصاصی داشتیم، بعد از دو سال، تنها شورت‌کدهایی که کش و نام‌گذاری معنادار داشتند، بدون مشکل ادامه دادند. بقیه، در آپدیت‌های PHP نسخه‌های بالاتر، خطاهای deprecated گرفتند. این تفاوت، هزینهٔ نگهداری بلندمدت را مشخص می‌کند. الگوی دقیق در بهینه‌سازی کد وردپرس و کدنویسی اختصاصی افزونه آمده است.

اشتباهات رایج

• استفاده از echo به‌جای return: خروجی به بالای صفحه می‌رود. الگوی درست در بخش اول.
• نبود shortcode_atts: کد آسیب‌پذیر و بی‌نظم. استانداردها.
• نبود sanitize و escape: خطر XSS — PHP امن در وردپرس.
• ثبت شورت‌کد در چایلد تم: با تغییر قالب از دست می‌رود. افزودن کد سفارشی.
• نام شورت‌کد عمومی: تعارض با افزونه‌های دیگر. اشتباهات رایج.
• نبود do_shortcode برای محتوای تودرتو: شورت‌کدهای درونی رندر نمی‌شوند.
• نادیده‌گرفتن بلاک گوتنبرگ: برای UI پیچیده، شورت‌کد ابزار بهینه‌ای نیست. گوتنبرگ.
• نبود کش در محاسبات سنگین: کندی صفحه — ترنزینت‌ها.
• نادیده‌گرفتن ABSPATH: خطر دسترسی مستقیم به فایل. کدنویسی افزونه.
• وابستگی شدید محتوا به شورت‌کد: روز تغییر قالب یا افزونه، محتوا به متن خام تبدیل می‌شود. تغییر امن قالب.

ساخت شورت‌کد، ساده‌ترین و در دسترس‌ترین راه افزودن قابلیت به محتوای وردپرس است. پنج گام اصلی آن: ثبت تابع، آتریبیوت با shortcode_atts، محتوای درونی اختیاری، امنیت در ورودی و خروجی، و نگهداری در افزونه یا mu-plugins. اگر همین امروز یک کار در این مسیر انجام می‌دهید: یک شورت‌کد ساده برای دکمه بسازید و آن را در یک نوشتهٔ آزمایشی درج کنید. دیدن همان اولین رندر، درهای تازه‌ای به کدنویسی وردپرس باز می‌کند. تجربهٔ خودتان از شورت‌کدی که ساختید یا مشکلی که در رندر آن دیدید، در دیدگاه‌ها ارزشمند است — همان گزارش‌های واقعی، این راهنما را دقیق‌تر می‌کند. 🧩