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

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

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

فهرست مطالب

• مفهوم اسکریپت های کوتاه وردپرس
• ساخت یک شورتکد پایه
• افزودن پارامترهای دینامیک به شورتکد
• استفاده از شورتکد در محتوا
• سفارشی سازی ظاهر با CSS و جاوااسکریپت
• رفع خطاها و بهینه سازی شورتکدها
• سوالات متداول

مفهوم اسکریپت های کوتاه وردپرس

اسکریپت های کوتاه یا shortcodes در وردپرس راهی سریع برای افزودن عملکرد پیشرفته به محتوا بدون نیاز به نوشتن کدهای HTML یا PHP در متن است. این برچسب های مخصوص با استفاده از براکت های مربعی [ ] تعریف می شوند و وقتی صفحه رندر می شود، توسط هسته وردپرس به خروجی نهایی تبدیل می شوند. به عبارت دیگر، شما فقط یک کلیدواژه کوتاه می نویسید و وردپرس آن را به یک بلوک محتوا پویا می برد.

مکانیسم کار اسکریپت های کوتاه بر پایه تجزیه (parsing) متن است؛ وردپرس ابتدا تمام رشته های داخل براکت را شناسایی می کند، سپس نام اسکریپت و ویژگی های اختیاری (attribute) آن را استخراج می کند. بعد از این مرحله، تابع PHP مربوطه که توسط add_shortcode() ثبت شده است، فراخوانی می شود و خروجی نهایی (معمولاً HTML) جایگزین متن اولیه می شود. به همین دلیل می توانید از پارامترهای سفارشی مانند size="large" یا align="center" برای کنترل ظاهر استفاده کنید.

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

برای ایجاد یک اسکریپت کوتاه ساده، کافی است کد زیر را به functions.php یا یک افزونه سفارشی اضافه کنید. این مثال یک اسکریپت به نام hello می سازد که یک پیام خوش آمد گویی را با نام کاربر نمایش می دهد.

function my_hello_shortcode( $atts ) {
    $atts = shortcode_atts( array(
        'name' => 'بازدیدکننده',
    ), $atts, 'hello' );
    return '
سلام ' . esc_html( $atts['name'] ) . '! خوش آمدید.
';
}
add_shortcode( 'hello', 'my_hello_shortcode' );

به کارگیری این اسکریپت در نوشته به سادگی با نوشتن [hello name="علی"] امکان پذیر است؛ وقتی صفحه لود می شود، خروجی زیر نمایش داده می شود: «سلام علی! خوش آمدید.» این روش نه تنها زمان و خطاهای دستی را کاهش می دهد، بلکه امکان به روزرسانی مرکزی محتوا را برای تمام صفحات فراهم می کند.

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

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

1. باز کردن فایل functions.php: می توانید این فایل را از طریق ویرایشگر قالب یا با استفاده از یک کلاینت FTP باز کنید.
2. تعریف تابع خروجی: تابع باید یک رشته HTML یا متنی برگرداند. به عنوان مثال، یک تابع ساده که تاریخ جاری را نمایش می دهد.
3. ثبت شورتکد با استفاده از add_shortcode( 'نام_شورتکد', 'نام_تابع' );. این خط، وردپرس را مطلع می کند که وقتی کاربر [نام_شورتکد] را می نویسد، کدام تابع اجرا شود.
4. آزمایش در ویرایشگر: پس از ذخیرهٔ تغییرات، شورتکد را در یک پست یا صفحهٔ آزمایشی وارد کنید تا خروجی را ببینید.

در ادامه یک مثال عملی آورده شده است. این شورتکد به نام hello_date یک پیام خوش آمد گویی به همراه تاریخ امروز نمایش می دهد:


function hello_date_shortcode( $atts ) {
$args = shortcode_atts( array( 'name' => 'بازدیدکننده' ), $atts, 'hello_date' );
$name = esc_html( $args['name'] );
$date = esc_html( date_i18n( 'j F Y' ) );
return "سلام $name! امروز تاریخ $date است.";
}
add_shortcode( 'hello_date', 'hello_date_shortcode' );


در این کد، shortcode_atts برای تعریف مقادیر پیش فرض ویژگی ها (attributes) استفاده می شود؛ در اینجا تنها ویژگی name وجود دارد. تابع esc_html خروجی را برای جلوگیری از حملات XSS پاک سازی می کند. برای استفاده، کافی است در محتوای خود بنویسید [hello_date name="علی"] یا بدون پارامتر برای استفاده از مقدار پیش فرض.

افزودن پارامترهای دینامیک به شورتکد

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

در زمان تعریف شورتکد، باید پارامترهای پیش فرض را با shortcode_atts() مشخص کنید. این تابع دو آرایه می گیرد: آرایه پیش فرض ها و آرایه ای که توسط کاربر در داخل کوتیشن ارائه می شود. به عنوان مثال، برای یک شورتکد [button] می توانید به این شکل عمل کنید:

function my_button_shortcode( $atts ) {
    $args = shortcode_atts( array(
        'text'  => 'دکمه',
        'url'   => '#',
        'color' => 'primary',
        'size'  => 'md',
    ), $atts, 'button' );

    return sprintf(
        '%s',
        esc_url( $args['url'] ),
        esc_attr( $args['color'] ),
        esc_attr( $args['size'] ),
        esc_html( $args['text'] )
    );
}
add_shortcode( 'button', 'my_button_shortcode' );

در این مثال، هر پارامتر می تواند به صورت دلخواه بازنویسی شود؛ اگر کاربر فقط text="ثبت نام" را بدهد، بقیه مقادیر از پیش فرض ها استفاده می شوند. برای پارامترهای بولی (مانند active) یا عددی، می توانید مقدار ورودی را با filter_var() یا intval() پاک سازی کنید تا از خطاهای احتمالی جلوگیری شود.

یک نکته عملی: اگر می خواهید مقادیر پیش فرض را بسته به زمینه ای که شورتکد استفاده می شود (مثلاً در صفحهٔ تماس یا صفحهٔ محصول) تغییر دهید، می توانید از فیلتر shortcode_atts_{$tag} بهره بگیرید. به این ترتیب می توانید به صورت شرطی مقادیر را تنظیم کنید، بدون اینکه به صورت مستقیم کد شورتکد را ویرایش کنید. به کارگیری این تکنیک باعث می شود شورتکدهایتان در سراسر سایت به صورت یکپارچه و انعطاف پذیر رفتار کنند.

استفاده از شورتکد در محتوا

شورتکدها ابزار قدرتمندی برای افزودن عملکرد پیش ساخته به محتوای نوشته ها و برگه ها هستند؛ بدون نیاز به نوشتن کد HTML یا PHP می توانید یک گالری، فرم تماس یا حتی یک جدول قیمت گذاری را در یک خط کوتاه قرار دهید. این امکان نه تنها زمان و تلاش توسعه دهنده را صرفه جویی می کند، بلکه ویرایش گران محتوا (نویسندگان، مدیران) را از پیچیدگی های برنامه نویسی دور می سازد.

در ویرایشگر کلاسیک، شورتکدها مستقیماً داخل بلوک متن قرار می گیرند؛ کافیست [my_shortcode attribute="value"] را تایپ کنید و وردپرس به صورت خودکار آن را به خروجی مربوطه تبدیل می کند. در ویرایشگر بلوکی (Gutenberg) می توانید از بلوک «شورتکد» استفاده کنید یا به صورت مستقیم در بلوک های متن یا پاراگراف کد شورتکد را بچسبانید. برای جلوگیری از تداخل با قالب بندی، بهتر است شورتکد را در یک بلوک جداگانه یا داخل بلوک «HTML سفارشی» قرار دهید.

به کارگیری ویژگی ها (attributes) شورتکدها می تواند انعطاف پذیری را چندین برابر کند. برای مثال، شورتکد به شما اجازه می دهد تعداد ستون ها و شناسه های تصویر را به سرعت تنظیم کنید. اگر می خواهید چند شورتکد را درون هم قرار دهید (نستینگ)، ابتدا اطمینان حاصل کنید که هر شورتکد به درستی بسته شده باشد؛ در غیر این صورت خروجی نادرست یا خالی ممکن است ظاهر شود.

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

سفارشی سازی ظاهر با CSS و جاوااسکریپت

کدهای کوتاه (shortcode) در وردپرس فقط یک قطعهٔ متنی ساده نیستند؛ آن ها می توانند خروجی HTML، CSS و حتی JavaScript تولید کنند. برای اینکه ظاهر این خروجی دقیقاً همان گونه باشد که می خواهید، لازم است استایل های سفارشی و اسکریپت های تعاملی را به‑صورت درست به صفحه اضافه کنید. در ادامه به دو مسیر اصلی – استفاده از CSS برای استایل دهی و استفاده از JavaScript برای رفتارهای پویا – می پردازیم.

بهترین روش برای افزودن CSS اختصاصی، اضافه کردن کلاس های منحصر به فرد به کد کوتاه است. در زمان تعریف add_shortcode() می توانید یک آرگومان class دریافت کنید و آن را به عنصر ریشهٔ خروجی اضافه کنید. سپس در فایل style.css قالب یا افزونهٔ خود، استایل های مرتبط را بنویسید، یا با استفاده از wp_enqueue_style() یک فایل CSS جداگانه بارگذاری کنید. برای مثال، اگر shortcode شما یک جدول قیمت باشد، می توانید کلاس pricing-table بدهید و سپس قواعدی مثل .pricing-table { border: 1px solid #ddd; } تعریف کنید. این کار باعث می شود استایل ها به صورت محلی اعمال شوند و با سایر بخش های سایت تداخل نداشته باشند.

اگر نیاز به تعامل کاربری دارید – مثل اسلایدر، تب ها یا منوی کشویی – باید JavaScript را به صورت صحیح enqueue کنید. همانند CSS، می توانید اسکریپت را در فایل جداگانه ای ذخیره کنید و با wp_enqueue_script('my-shortcode-js', get_template_directory_uri() . '/js/shortcode.js', ['jquery'], null, true); بارگذاری کنید. داخل اسکریپت می توانید از document.querySelectorAll('.my-shortcode') برای یافتن تمام نمونه های shortcode استفاده کنید و سپس به هر یک رفتار دلخواه (مثلاً باز/بسته کردن محتوا) را اعمال کنید. به خاطر داشته باشید که اگر از jQuery استفاده می کنید، باید آن را به عنوان وابستگی اعلام کنید تا از بارگذاری قبل اطمینان حاصل شود.

یک نکتهٔ عملی: اگر shortcode شما در چندین صفحه یا پست استفاده می شود، بهتر است CSS و JS را فقط در زمان حضور shortcode بارگذاری کنید. برای این کار می توانید در تابع add_shortcode() یک متغیر سراسری یا گزینهٔ موقت تنظیم کنید و سپس در هوک wp_enqueue_scripts بررسی کنید که آیا این متغیر فعال است یا نه. این کار به بهینه سازی سرعت لود سایت کمک شایانی می کند و از بارگذاری غیرضروری فایل ها جلوگیری می نماید.

رفع خطاها و بهینه سازی شورتکدها

شورتکدهای وردپرس به دلیل سادگی استفاده، گاهی با خطاهای ظریفی مثل ] یا [ گم شده، نام گذاری نادرست پارامترها یا مقداردهی اشتباه متغیرها مواجه می شوند. این اشتباهات معمولاً باعث می شود شورتکد در صفحه به صورت متن خام نمایش داده شود یا خروجی ناقص بدهد. اولین قدم برای رفع این مشکلات، مرور دقیق ساختار کوتاه کد در فایل functions.php یا افزونه مربوطه است؛ به ویژه اطمینان از اینکه تابع add_shortcode() با نام صحیح و یک callback معتبر فراخوانی شده است.

برای تشخیص دقیق تر خطا، حالت اشکال زدایی (debug) وردپرس را فعال کنید. افزودن خط زیر به wp-config.php خروجی خطاها را در لاگ فایل debug.log ثبت می کند:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

سپس می توانید با استفاده از error_log() یا var_dump() داخل تابع شورتکد، مقادیر ورودی را چاپ کنید و ببینید آیا پارامترهای ارسالی همان گونه که انتظار دارید دریافت می شوند یا خیر. همچنین افزونه های رایگانی مثل Query Monitor به سرعت اطلاعات مربوط به کوئری های پایگاه داده و هشدارهای PHP را نشان می دهند.

بهینه سازی شورتکدها بیشتر به کاهش هزینه های پردازشی در زمان رندر صفحه مرتبط است. برای این منظور می توانید خروجی شورتکد را در یک متغیر سراسری یا transient ذخیره کنید تا در درخواست های بعدی از کش استفاده شود و نیازی به اجرای دوبارهٔ کد سنگین نباشد. مثال ساده:

function my_cached_shortcode( $atts ) {
    $cache_key = 'my_shortcode_' . md5( serialize( $atts ) );
    $output    = get_transient( $cache_key );
    if ( false === $output ) {
        // محاسبات سنگین یا کوئری های دیتابیس
        $output = '
نتیجهٔ پردازش
';
        set_transient( $cache_key, $output, HOUR_IN_SECONDS );
    }
    return $output;
}
add_shortcode( 'my_cached', 'my_cached_shortcode' );

استفاده از static داخل تابع نیز می تواند برای ذخیرهٔ مقادیر یکبار محاسبه شده در همان درخواست مفید باشد.

سوالات متداول

چطور یک شورت کد ساده در functions.php ایجاد کنم؟

برای ساخت شورت کد ساده یک تابع PHP بنویسید و با add_shortcode آن را ثبت کنید. تابع باید خروجی HTML یا متن را برگرداند. فایل functions.php را در یک child theme یا افزونه سفارشی قرار دهید تا در به روزرسانی ها محفوظ بماند.

آیا می توانم پارامترهای دلخواه به شورت کد اضافه کنم؟

در تعریف شورت کد آرگومان $atts را دریافت کنید و با shortcode_atts مقادیر پیش فرض تنظیم کنید. سپس می توانید مقادیر ارسال شده را در خروجی به کار ببرید. این کار باعث می شود شورت کد انعطاف پذیرتر شود.

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

در گوتنبرگ می توانید بلوک Shortcode را اضافه کنید یا مستقیماً کد شورت کد را در بلوک پاراگراف وارد کنید. برای استفاده ساده، متن [my_shortcode] را در ویرایشگر بنویسید. اگر نیاز به تنظیمات پیشرفته دارید، می توانید یک بلوک سفارشی با React بنویسید.

آیا شورت کدها می توانند محتوای پویا مثل فرم ها را نمایش دهند؟

شورت کد می تواند تابعی فراخوانی کند که فرم HTML یا خروجی یک پلاگین فرم را تولید می کند. کافی است در تابع شورت کد کد فرم را یا تابع پلاگین را برگردانید. این روش برای نمایش فرم تماس یا فرم ثبت نام مناسب است.

چک لیست سریع

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

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