شورتکد وردپرس چیست و چگونه محتوا را غنی می‌کند؟

شورتکد (Shortcode) وردپرس یک میانبر متنی است که به کاربران اجازه می‌دهد بدون نوشتن کد، قابلیت‌های پویا و پیچیده را به محتوای سایت اضافه کنند. اگر تا امروز فقط از ویرایشگر کلاسیک یا گوتنبرگ برای نوشتن متن استفاده کرده‌اید، احتمالاً با شورتکدهایی مثل [gallery] یا [contact-form-7] برخورد کرده‌اید. اما پشت این کروشه‌های ساده، یک مکانیزم قدرتمند نهفته است که محتوای وردپرس را از یک متن ایستا به یک بستر تعاملی تبدیل می‌کند. در این راهنما، از تعریف پایه‌ای شروع می‌کنیم و به‌تدریج به مباحث پیشرفته‌تر مثل ساخت شورتکد سفارشی، پارامترها، امنیت، کارایی و تفاوت آن با بلوک‌های گوتنبرگ می‌رسیم.

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

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

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

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

شورتکد دقیقاً چیست و چگونه کار می‌کند؟

شورتکد (Shortcode) در وردپرس یک کد کوتاه است که در میان کروشه‌های مربع قرار می‌گیرد و هنگام نمایش محتوا، به یک خروجی پویا تبدیل می‌شود. مثلاً [gallery] یک شورتکد پیش‌فرض است که به یک گالری تصاویر تبدیل می‌شود. مفهوم Short Code در ویکی‌پدیا توضیح داده شده و ریشه‌ی آن به سیستم‌های مدیریت محتوای اولیه بازمی‌گردد.

مکانیزم پردازش شورتکد در وردپرس بر پایه‌ی یک سری عبارت باقاعده (Regular Expression) است. وقتی محتوا نمایش داده می‌شود، تابع do_shortcode() فراخوانی می‌شود و همه‌ی الگوهای [shortcode] را در متن پیدا می‌کند. برای هر شورتکد، یک تابع کالبک (Callback) وجود دارد که خروجی HTML را تولید می‌کند. این خروجی، جایگزین کد شورتکد در متن می‌شود.

// نمونه ساده از یک شورتکد
function my_greeting_shortcode($atts) {
    $atts = shortcode_atts([
        'name' => 'دوست عزیز',
    ], $atts);

    return '<p>سلام، ' . esc_html($atts['name']) . '!</p>';
}
add_shortcode('greeting', 'my_greeting_shortcode');

با این کد، هر جا در محتوا بنویسید [greeting name="علی"]، خروجی <p>سلام، علی!</p> نمایش داده می‌شود. این مثال ساده، ساختار پایه‌ی همه‌ی شورتکدها را نشان می‌دهد: یک تابع که پارامترها را می‌گیرد و خروجی HTML برمی‌گرداند، و یک فراخوانی add_shortcode() که این تابع را به نام شورتکد متصل می‌کند.

نکته‌ی مهم این است که شورتکدها فقط در محتوایی پردازش می‌شوند که از فیلتر the_content عبور کرده باشد. اگر یک شورتکد را در یک فیلد سفارشی (Custom Field) یا در یک ویجت قرار دهید، ممکن است پردازش نشود. برای رفع این مشکل، باید do_shortcode() را به‌صورت دستی فراخوانی کنید. این نکته، یکی از رایج‌ترین دلایل «کار نکردن شورتکد» در پروژه‌های واقعی است.

یک شورتکد، در واقع یک قرارداد بین محتوا و کد است: محتوا می‌گوید «اینجا یک خروجی پویا لازم است» و کد می‌گوید «من آن را تولید می‌کنم».

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

شورتکدهای پیش‌فرض وردپرس

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

شورتکد [gallery] برای نمایش یک گالری تصاویر استفاده می‌شود. با پارامترهایی مثل ids، columns، size و link می‌توانید ظاهر گالری را کنترل کنید. مثلاً [gallery ids="1,2,3" columns="3"] یک گالری سه‌ستونه از تصاویر مشخص می‌سازد.

شورتکد [audio] برای نمایش پخش‌کننده صوتی، شورتکد [video] برای نمایش پخش‌کننده ویدئو و شورتکد [embed] برای جاسازی محتوای خارجی استفاده می‌شوند. مثلاً [embed]https://example.com/video[/embed] یک ویدئو را از یک سرویس خارجی جاسازی می‌کند.

شورتکد [caption] برای افزودن زیرنویس به تصاویر و شورتکد [playlist] برای نمایش لیست پخش استفاده می‌شوند. این شورتکدها، ابزارهای پایه‌ای برای غنی‌سازی محتوا هستند و بدون نیاز به هیچ افزونه‌ای کار می‌کنند.

علاوه بر این، بسیاری از افزونه‌های محبوب، شورتکدهای اختصاصی خود را ارائه می‌دهند. مثلاً افزونه‌های فرم‌ساز مثل Contact Form 7 شورتکد [contact-form-7] را فراهم می‌کنند که با آن می‌توانید یک فرم را در هر جای محتوا جاسازی کنید. برای آشنایی بیشتر با افزونه‌های کاربردی، مقاله بهترین افزونه‌های ضروری وردپرس برای هر سایت را مطالعه کنید.

شورتکد	کاربرد	نمونه
`[gallery]`	نمایش گالری تصاویر	`[gallery ids="1,2,3"]`
`[audio]`	پخش‌کننده صوتی	`[audio src="file.mp3"]`
`[video]`	پخش‌کننده ویدئو	`[video src="file.mp4"]`
`[embed]`	جاسازی محتوای خارجی	`[embed]https://...[/embed]`
`[caption]`	زیرنویس تصویر	`[caption]متن[/caption]`

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

ساختار شورتکد و پارامترها

هر شورتکد می‌تواند سه بخش داشته باشد: نام، ویژگی‌ها (Attributes) و محتوای درونی (Content). درک این ساختار، برای استفاده‌ی حرفه‌ای از شورتکدها ضروری است.

نام شورتکد اولین بخش است و بین کروشه‌ها قرار می‌گیرد. مثلاً در [gallery]، نام gallery است. نام شورتکد باید یکتا باشد و نباید با نام شورتکدهای دیگر تداخل داشته باشد.

ویژگی‌ها پارامترهایی هستند که بعد از نام شورتکد و با فاصله می‌آیند. مثلاً در [gallery ids="1,2,3" columns="3"]، دو ویژگی ids و columns وجود دارد. ویژگی‌ها می‌توانند مقدار داشته باشند یا بدون مقدار باشند.

// شورتکد با ویژگی‌ها
[my_shortcode foo="bar" baz="qux"]

// شورتکد با محتوای درونی
[my_shortcode]محتوای درونی[/my_shortcode]

// شورتکد خودبسته
[my_shortcode /]

محتوای درونی زمانی استفاده می‌شود که شورتکد نیاز به پردازش محتوایی بین تگ باز و بسته داشته باشد. مثلاً [caption]متن زیرنویس[/caption] محتوای درونی را به‌عنوان متن زیرنویس در نظر می‌گیرد. برای دسترسی به این محتوا در تابع کالبک، از پارامتر دوم تابع استفاده کنید.

function my_wrapper_shortcode($atts, $content = null) {
    $atts = shortcode_atts([
        'class' => 'default',
    ], $atts);

    return '<div class="' . esc_attr($atts['class']) . '">'
        . do_shortcode($content)
        . '</div>';
}
add_shortcode('wrapper', 'my_wrapper_shortcode');

نکته‌ی مهم در پردازش محتوای درونی این است که اگر محتوا خودش شامل شورتکدهای دیگر باشد، باید do_shortcode() را روی آن فراخوانی کنید. در غیر این صورت، شورتکدهای درونی پردازش نمی‌شوند و به‌صورت متن خام نمایش داده می‌شوند. این نکته، یکی از رایج‌ترین دلایل «کار نکردن شورتکدهای تودرتو» است.

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

ساخت شورتکد سفارشی

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

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

function my_recent_posts_shortcode($atts) {
    $atts = shortcode_atts([
        'count' => 5,
        'category' => '',
        'orderby' => 'date',
    ], $atts, 'recent_posts');

    $args = [
        'posts_per_page' => absint($atts['count']),
        'orderby' => sanitize_key($atts['orderby']),
    ];

    if (!empty($atts['category'])) {
        $args['category_name'] = sanitize_title($atts['category']);
    }

    $query = new WP_Query($args);

    if (!$query->have_posts()) {
        return '';
    }

    $output = '<ul class="recent-posts">';
    while ($query->have_posts()) {
        $query->the_post();
        $output .= '<li><a href="' . esc_url(get_permalink()) . '">'
            . esc_html(get_the_title()) . '</a></li>';
    }
    $output .= '</ul>';

    wp_reset_postdata();

    return $output;
}
add_shortcode('recent_posts', 'my_recent_posts_shortcode');

این شورتکد، لیستی از آخرین نوشته‌ها را نمایش می‌دهد و سه ویژگی قابل تنظیم دارد. نکته‌ی مهم در این کد، استفاده از wp_reset_postdata() بعد از حلقه است. بدون این فراخوانی، متغیر سراسری $post تغییر می‌کند و ممکن است محتوای بعدی صفحه به‌درستی نمایش داده نشود. این اشتباه، یکی از رایج‌ترین باگ‌ها در شورتکدهای سفارشی است.

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

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

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

یکی از مباحث پیشرفته در شورتکدها، مدیریت شورتکدهای تودرتو (Nested Shortcodes) است. وقتی یک شورتکد درون شورتکد دیگری قرار می‌گیرد، پردازش آن نیازمند دقت بیشتر است، زیرا اگر محتوای درونی به‌درستی پردازش نشود، شورتکدهای داخلی به‌صورت متن خام نمایش داده می‌شوند.

[wrapper class="box"]
    [greeting name="علی"]
[/wrapper]

در این مثال، شورتکد wrapper باید محتوای درونی خود را که شامل شورتکد greeting است، پردازش کند. اگر در تابع کالبک wrapper صرفاً $content را برگردانید، شورتکد greeting به‌صورت متن خام نمایش داده می‌شود. راه‌حل، فراخوانی do_shortcode() روی محتوای درونی است.

function my_wrapper_shortcode($atts, $content = null) {
    return '<div class="box">' . do_shortcode($content) . '</div>';
}
add_shortcode('wrapper', 'my_wrapper_shortcode');

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

راه‌حل جایگزین برای شورتکدهای تودرتو، استفاده از توابع کمکی (Helper Functions) است که خروجی HTML را به‌جای شورتکد تولید می‌کنند. این رویکرد، از پردازش بازگشتی جلوگیری می‌کند و کارایی را افزایش می‌دهد. در پروژه‌های بزرگ، این رویکرد توصیه می‌شود.

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

پارامترها و ویژگی‌های پیشرفته

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

ویژگی‌های رشته‌ای رایج‌ترین نوع هستند و با shortcode_atts() تعریف می‌شوند. مثلاً [my_shortcode title="سلام"] یک ویژگی رشته‌ای است.

ویژگی‌های عددی باید با توابع اعتبارسنجی مثل absint() یا intval() پردازش شوند تا از مقادیر نامعتبر جلوگیری شود. مثلاً [recent_posts count="5"] باید مقدار 5 را به عدد صحیح تبدیل کند.

ویژگی‌های بولی معمولاً به‌صورت true یا false تعریف می‌شوند. برای پردازش این نوع، از filter_var($value, FILTER_VALIDATE_BOOLEAN) استفاده کنید.

$atts = shortcode_atts([
    'title' => '',
    'count' => 5,
    'show_thumb' => false,
    'order' => 'DESC',
], $atts);

$atts['count'] = absint($atts['count']);
$atts['show_thumb'] = filter_var($atts['show_thumb'], FILTER_VALIDATE_BOOLEAN);
$atts['order'] = in_array(strtoupper($atts['order']), ['ASC', 'DESC'], true)
    ? strtoupper($atts['order'])
    : 'DESC';

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

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

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

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

اصل اول، پاک‌سازی ورودی‌ها. همیشه مقادیر ویژگی‌ها را قبل از استفاده، پاک‌سازی کنید. برای متن از sanitize_text_field()، برای اعداد از absint()، برای URL از esc_url() و برای کلاس‌های CSS از sanitize_html_class() استفاده کنید.

$title = sanitize_text_field($atts['title']);
$count = absint($atts['count']);
$url = esc_url($atts['url']);
$class = sanitize_html_class($atts['class']);

اصل دوم، فرار دادن خروجی‌ها. هر مقداری که در خروجی HTML قرار می‌گیرد، باید با توابع مناسب فرار داده شود. برای متن از esc_html()، برای ویژگی‌های HTML از esc_attr() و برای URL از esc_url() استفاده کنید.

return '<div class="' . esc_attr($class) . '">'
    . '<h3>' . esc_html($title) . '</h3>'
    . '<a href="' . esc_url($url) . '">' . esc_html__('بیشتر', 'textdomain') . '</a>'
    . '</div>';

اصل سوم، بررسی سطح دسترسی. اگر شورتکد شما عملیات حساسی مثل ذخیره‌ی داده یا حذف رکورد انجام می‌دهد، حتماً سطح دسترسی کاربر را با current_user_can() بررسی کنید. همچنین برای عملیات فرم، از wp_verify_nonce() استفاده کنید.

if (!current_user_can('edit_posts')) {
    return '<p>' . esc_html__('دسترسی غیرمجاز', 'textdomain') . '</p>';
}

اصل چهارم، جلوگیری از XSS. اگر شورتکد شما محتوای HTML را از کاربر دریافت می‌کند، از wp_kses_post() یا wp_kses() برای محدود کردن تگ‌های مجاز استفاده کنید. هرگز محتوای خام کاربر را مستقیماً در خروجی قرار ندهید.

$allowed_html = [
    'a' => ['href' => [], 'title' => []],
    'strong' => [],
    'em' => [],
];
$safe_content = wp_kses($content, $allowed_html);

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

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

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

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

تکنیک اول، کاهش کوئری‌های دیتابیس. اگر شورتکد شما نیاز به دریافت داده دارد، از WP_Query با پارامترهای دقیق استفاده کنید و از get_posts() با no_found_rows برای صرفه‌جویی در منابع بهره ببرید. همچنین از wp_reset_postdata() بعد از هر حلقه استفاده کنید.

$args = [
    'posts_per_page' => 5,
    'no_found_rows' => true,
    'update_post_meta_cache' => false,
    'update_post_term_cache' => false,
];

تکنیک دوم، کش کردن خروجی. اگر شورتکد شما خروجی سنگینی تولید می‌کند، می‌توانید آن را با Transient API کش کنید. این کار، از اجرای مکرر کوئری‌ها جلوگیری می‌کند و کارایی را به‌طور قابل‌توجهی افزایش می‌دهد.

$cache_key = 'my_shortcode_' . md5(serialize($atts));
$output = get_transient($cache_key);

if (false === $output) {
    $output = generate_shortcode_output($atts);
    set_transient($cache_key, $output, HOUR_IN_SECONDS);
}

return $output;

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

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

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

شورتکد یا بلوک گوتنبرگ؟

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

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

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

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

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

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

اشتباهات رایج در استفاده از شورتکدها

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

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

// نادرست
function my_shortcode() {
    echo 'خروجی';
}

// درست
function my_shortcode() {
    return 'خروجی';
}

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

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

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

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

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

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

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

دیباگ و عیب‌یابی شورتکدها

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

ابزار اول، تابع shortcode_exists(). این تابع بررسی می‌کند که آیا یک شورتکد خاص ثبت شده است یا نه. اگر shortcode_exists('my_shortcode') مقدار false برگرداند، یعنی شورتکد ثبت نشده است.

if (shortcode_exists('my_shortcode')) {
    // شورتکد ثبت شده است
} else {
    // شورتکد ثبت نشده است
}

ابزار دوم، فراخوانی دستی do_shortcode(). اگر شورتکد در محتوا نمایش داده نمی‌شود، می‌توانید آن را به‌صورت دستی فراخوانی کنید و خروجی را بررسی کنید.

$output = do_shortcode('[my_shortcode]');
var_dump($output);

ابزار سوم، بررسی فیلتر the_content. اگر شورتکد در محتوا پردازش نمی‌شود، ممکن است فیلتر the_content به‌درستی اعمال نشده باشد. بررسی کنید که آیا قالبتان از the_content() استفاده می‌کند یا از get_the_content(). تابع دوم، فیلترها را اعمال نمی‌کند و شورتکدها پردازش نمی‌شوند.

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

ابزار پنجم، فعال کردن WP_DEBUG. اگر شورتکد شما خطای PHP تولید می‌کند، فعال کردن WP_DEBUG در فایل wp-config.php به شما کمک می‌کند تا خطا را ببینید. برای درک عمیق‌تر این موضوع، مقاله فعال‌سازی حالت Debug وردپرس و پیدا کردن خطاها را مطالعه کنید.

نکته‌ی مهم در دیباگ شورتکدها این است که همیشه از محیط توسعه (Development) استفاده کنید، نه محیط تولید. تغییرات در کد شورتکدها، در محیط تولید می‌تواند سایت را از کار بیندازد.

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

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

چرا شورتکد من در محتوا نمایش داده نمی‌شود؟ دلایل متعددی وجود دارد: ممکن است شورتکد ثبت نشده باشد، ممکن است محتوا از فیلتر the_content عبور نکرده باشد، ممکن است تابع کالبک به‌جای return از echo استفاده کند، یا ممکن است نام شورتکد اشتباه نوشته شده باشد.

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

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

چگونه یک شورتکد سفارشی بسازم؟ سه مرحله دارد: تعریف یک تابع کالبک که پارامترها را می‌گیرد و خروجی HTML برمی‌گرداند، ثبت شورتکد با add_shortcode()، و استفاده از شورتکد در محتوا. برای جزئیات بیشتر، مقاله ساخت شورتکد سفارشی در وردپرس را مطالعه کنید.

آیا می‌توانم شورتکد را در ویجت استفاده کنم؟ به‌صورت پیش‌فرض، شورتکدها در ویجت‌ها پردازش نمی‌شوند. اما می‌توانید با فراخوانی do_shortcode() در ویجت، این قابلیت را اضافه کنید. برخی افزونه‌ها این قابلیت را به‌صورت آماده ارائه می‌دهند.

آیا شورتکدها روی سرعت سایت تأثیر دارند؟ هر شورتکد، یک فراخوانی تابع و یک پردازش عبارت باقاعده است. اگر تعداد شورتکدها زیاد باشد یا هر شورتکد کوئری سنگینی اجرا کند، می‌تواند بر سرعت تأثیر بگذارد. با کش کردن خروجی و بهینه‌سازی کوئری‌ها، می‌توان این تأثیر را کاهش داد.

چگونه شورتکد را از محتوا حذف کنم؟ برای حذف یک شورتکد از محتوا، می‌توانید از تابع remove_shortcode() استفاده کنید. اما توجه داشته باشید که این تابع، ثبت شورتکد را حذف می‌کند، نه استفاده از آن در محتوا. برای حذف استفاده، باید کد شورتکد را از محتوا حذف کنید.

آیا می‌توانم چند شورتکد را در یک صفحه ترکیب کنم؟ بله، می‌توانید چند شورتکد را در یک صفحه استفاده کنید و حتی آن‌ها را تودرتو کنید. اما توجه داشته باشید که شورتکدهای تودرتو نیازمند فراخوانی do_shortcode() در محتوای درونی هستند.

آیا شورتکدها با قالب‌های مختلف سازگار هستند؟ شورتکدها در هسته وردپرس پردازش می‌شوند و به قالب وابسته نیستند. اما اگر قالب شما از the_content() استفاده نکند، شورتکدها پردازش نمی‌شوند. برای درک عمیق‌تر ساختار قالب، مقاله فایل‌های ضروری قالب وردپرس کدامند را مطالعه کنید.

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

آیا می‌توانم شورتکد را در فایل قالب استفاده کنم؟ بله، با فراخوانی do_shortcode() در فایل قالب، می‌توانید شورتکد را اجرا کنید. مثلاً <?php echo do_shortcode('[my_shortcode]'); ?>.

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

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