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

عنوان و خلاصه

عنوان و خلاصه، اولین چیزی هستند که کاربر می‌بیند. سه تابع اصلی در این دسته:

the_title( $before, $after, $echo );   // چاپ عنوان
get_the_title( $post_id );             // بازگرداندن عنوان
the_excerpt();                          // چاپ خلاصه
get_the_excerpt( $post_id );           // بازگرداندن خلاصه

نکته‌ها: یک — پارامترهای the_title: می‌توانید قبل و بعد از عنوان، HTML تزریق کنید:

the_title( '<h2 class="post-title">', '</h2>' );

این خیلی بهتر از ترکیب echo و get_the_title است. دو — تفاوت the_excerpt و get_the_excerpt: اولی چاپ می‌کند، دومی برمی‌گرداند. اگر می‌خواهید در متغیر ذخیره کنید، از دومی استفاده کنید. سه — خلاصهٔ خودکار: اگر کاربر خلاصه دستی وارد نکرده باشد، وردپرس از محتوا کپی می‌گیرد و تا ۵۵ کلمه نمایش می‌دهد. برای تغییر این عدد، از فیلتر excerpt_length استفاده کنید:

add_filter( 'excerpt_length', function( $length ) {
    return 25;
} );

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

<h2 class="card-title">
    <a href="<?php the_permalink(); ?>">
        <?php the_title(); ?>
    </a>
</h2>

این ساختار، هم برای سئو بهتر است (لینک داخل H2)، هم برای دسترس‌پذیری (خوانندهٔ صفحه با Tab به آن می‌رسد).

محتوا

نمایش محتوای نوشته، ظریف‌ترین بخش قالب است. تابع اصلی:

the_content();                                     // چاپ با فیلترها
get_the_content( $more_link_text, $strip_teaser, $post );  // بازگرداندن

نکته‌ها: یک — the_content فیلترها را اعمال می‌کند: اگر get_the_content را مستقیم چاپ کنید، فیلترهای wptexturize، wpautop، do_shortcode اعمال نمی‌شوند و محتوا به‌شکل خام نمایش داده می‌شود. الگوی درست:

$content = get_the_content();
$content = apply_filters( 'the_content', $content );
echo $content;

یا ساده‌تر: فقط the_content() را صدا بزنید. دو — صفحه‌بندی داخلی: وردپرس با تگ <!--nextpage--> در محتوا، صفحه‌بندی داخلی می‌سازد. برای نمایش پیوندهای صفحه‌بندی، از تابع زیر استفاده کنید:

wp_link_pages( array(
    'before' => '<div class="page-links">' . __( 'صفحات:', 'textdomain' ),
    'after'  => '</div>',
) );

سه — محتوا در آرشیو: در آرشیو، معمولاً خلاصه نمایش داده می‌شود نه محتوای کامل. اگر می‌خواهید محتوای کامل باشد، از همان the_content() استفاده کنید ولی در نظر داشته باشید که صفحه‌بندی داخلی، در آرشیو کار نمی‌کند. راهنمای هوک the_content در هوک‌های محتوای نوشته.

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

تاریخ و زمان

تاریخ و زمان نوشته، برای سئو و برای تجربهٔ کاربری مهم است. توابع اصلی:

the_time( 'Y-m-d' );           // چاپ تاریخ با فرمت دلخواه
get_the_time( 'Y-m-d' );        // بازگرداندن
the_date();                      // تاریخ با فرمت تنظیمات وردپرس
get_the_date();

the_modified_time( 'Y-m-d' );   // تاریخ آخرین تغییر
get_the_modified_time();

get_post_time( 'U' );            // تاریخ به‌صورت timestamp
get_post_modified_time( 'U' );

human_time_diff( get_the_time( 'U' ), current_time( 'timestamp' ) );  // "3 روز پیش"

نکته‌ها: یک — فرمت: پارامتر فرمت، از استاندارد date() پیاچپی پیروی می‌کند. Y-m-d، j F Y، H:i و مشابه. دو — تاریخ در HTML5: برای خوانایی ماشین، از تگ <time> با ویژگی datetime استفاده کنید:

<time datetime="<?php echo esc_attr( get_the_date( 'c' ) ); ?>">
    <?php echo esc_html( get_the_date() ); ?>
</time>

پارامتر c در فرمت، استاندارد ISO 8601 را برمی‌گرداند. سه — نمایش «x روز پیش»: با ترکیب human_time_diff:

printf(
    '%s پیش',
    esc_html( human_time_diff( get_the_time( 'U' ), current_time( 'timestamp' ) ) )
);

راهنمای کامل در توابع تاریخ و زمان وردپرس. یک نکته در قالب‌های حرفه‌ای: تاریخ نمایش، باید با تنظیمات منطقهٔ زمانی وردپرس سازگار باشد. همیشه از توابع وردپرس استفاده کنید، نه date() مستقیم، تا تغییرات منطقهٔ زمانی خودکار اعمال شوند.

نویسنده

نمایش اطلاعات نویسنده، هم برای اعتبار محتوا و هم برای سئو مهم است:

the_author();                    // چاپ نام نمایشی
get_the_author();                // بازگرداندن
the_author_meta( 'description' ); // چاپ یکی از فیلدهای کاربر
get_the_author_meta( 'user_email' );
get_the_author_meta( 'ID' );      // شناسهٔ نویسنده
the_author_posts_link();         // لینک به آرشیو نویسنده
get_author_posts_url( $author_id );
get_avatar( $author_id, 48 );    // آواتار

نکته‌ها: یک — فیلدهای قابل دسترس: display_name، user_email، description، first_name، last_name، user_url، ID. دو — get_avatar: خروجی را باید escape کنید یا با echo مستقیم چاپ کنید (خروجی HTML است). الگو:

echo get_avatar( get_the_author_meta( 'ID' ), 48, '', get_the_author(), array( 'class' => 'author-avatar' ) );

سه — نویسنده در کارت نویسنده: برای ساختار اعتماد، بخشی از قالب که اطلاعات نویسنده را با آواتار، توضیح و لینک نمایش می‌دهد. راهنمای داده‌های کاربر در توابع دادهٔ کاربر و توابع کاربران. یک نکته در امنیت: فیلدهایی مثل user_email، اگر در قالب عمومی نمایش داده شوند، خطر spam و افشای اطلاعات دارند. فقط فیلدهای عمومی (display_name، description) را در فرانت نمایش دهید.

لینک دائمی، پایهٔ ناوبری سایت است:

the_permalink( $post );          // چاپ لینک
get_permalink( $post_id );       // بازگرداندن

// برای نویسنده و ترم
get_author_posts_url( $author_id );
get_term_link( $term );
get_category_link( $cat_id );
get_tag_link( $tag_id );

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

<a href="<?php the_permalink(); ?>" rel="bookmark">
    <?php the_title(); ?>
</a>

ویژگی rel="bookmark"، از استاندارد قدیم HTML وردپرس است و همچنان مفید. راهنمای ساختار URL در ساختار URL و سئو و توابع لینک و URL.

تصویر شاخص

تصویر شاخص، در فهرست‌ها، شبکه‌های اجتماعی و نتایج جستجو نقش مهمی دارد:

has_post_thumbnail( $post_id );              // بررسی وجود
the_post_thumbnail( 'medium' );               // چاپ تصویر
get_the_post_thumbnail_url( $post_id, 'large' );
get_the_post_thumbnail( $post_id, 'medium', array( 'class' => 'card-img' ) );
get_post_thumbnail_id( $post_id );            // شناسهٔ رسانه

نکته‌ها: یک — بررسی وجود: همیشه پیش از نمایش، has_post_thumbnail را چک کنید:

if ( has_post_thumbnail() ) {
    the_post_thumbnail( 'medium', array( 'class' => 'post-thumb' ) );
} else {
    echo '<img src="' . esc_url( get_template_directory_uri() . '/assets/images/default.webp' ) . '" alt="" />';
}

دو — alt تصویر: the_post_thumbnail، alt را از متادیتای تصویر می‌خواند. اگر alt خالی باشد، بهتر است دستی ست کنید:

the_post_thumbnail( 'medium', array(
    'alt' => esc_attr( get_the_title() ),
) );

ولی توجه کنید که alt تکراری در همهٔ تصاویر، برای سئو مفید نیست. alt باید توصیف واقعی تصویر باشد. راهنمای کامل در توابع تصویر شاخص، نقش alt در سئو، و سئوی تصویر.

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

متادیتا، دادهٔ اضافی روی نوشته است:

get_post_meta( $post_id, '_key', true );       // خواندن یک کلید
get_post_custom( $post_id );                    // همهٔ متاها
get_post_custom_values( '_key', $post_id );     // مقادیر یک کلید
update_post_meta( $post_id, '_key', $value );
delete_post_meta( $post_id, '_key' );

نکته: همیشه پارامتر سوم get_post_meta را true بگذارید تا مقدار تکی برگردد. نمایش امن:

$source = get_post_meta( get_the_ID(), '_source', true );
if ( ! empty( $source ) ) {
    printf(
        '<p class="post-source">منبع: %s</p>',
        esc_html( $source )
    );
}

راهنمای کامل در توابع متادیتا و کار با متاباکس‌ها.

دسته و برچسب

نمایش دسته و برچسب، هم برای ناوبری و هم برای سئو مهم است:

the_category( ', ' );                       // چاپ دسته‌ها
get_the_category( $post_id );                // بازگرداندن
the_tags( '<span>', '</span>', '، ' );      // چاپ برچسب‌ها
get_the_tags( $post_id );
get_the_terms( $post_id, 'category' );       // تاکسونومی دلخواه
has_category( 'news', $post_id );            // بررسی
get_term_link( $term );                       // لینک ترم

الگوی حرفه‌ای برای نمایش دسته‌ها با کلاس:

$categories = get_the_category();
if ( ! empty( $categories ) ) :
    echo '<div class="post-categories">';
    foreach ( $categories as $category ) :
        printf(
            '<a href="%s" class="cat-link">%s</a>',
            esc_url( get_category_link( $category->term_id ) ),
            esc_html( $category->name )
        );
    endforeach;
    echo '</div>';
endif;

نکتهٔ امنیتی: the_category خروجی را escape می‌کند، ولی اگر خودتان ترکیب می‌سازید، همیشه esc_html و esc_url را بگذارید. راهنمای کامل در توابع دسته‌بندی، توابع برچسب، و تاکسونومی سفارشی.

وضعیت و شناسه

توابعی که اطلاعات وضعیت و شناسهٔ نوشته را برمی‌گردانند:

get_the_ID();                    // شناسه
get_post_status( $post_id );     // وضعیت (publish, draft, ...)
get_post_type( $post_id );       // نوع‌نوشته
get_post_format( $post_id );     // فرمت (gallery, video, ...)
get_post_field( 'post_name', $post_id ); // یک فیلد خاص
get_post_ancestors( $post_id );  // والدین برگه
get_post_parent( $post_id );     // والد مستقیم

نکته: get_post_field، دسترسی سریع به فیلدهای خام جدول wp_posts می‌دهد. برای مصارف نمایشی، از توابع سطح‌بالاتر مثل get_the_title استفاده کنید؛ get_post_field برای مواردی است که به مقدار خام نیاز دارید. راهنمای کامل در توابع دادهٔ نوشته و کار با CPT.

الگوهای ترکیبی در حلقه

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

<?php if ( have_posts() ) : ?>
    <?php while ( have_posts() ) : the_post(); ?>
        <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
            <header class="entry-header">
                <?php the_title( '<h2 class="entry-title"><a href="' . esc_url( get_permalink() ) . '" rel="bookmark">', '</a></h2>' ); ?>
                <div class="entry-meta">
                    <time datetime="<?php echo esc_attr( get_the_date( 'c' ) ); ?>">
                        <?php echo esc_html( get_the_date() ); ?>
                    </time>
                    <span class="author">
                        <?php the_author_posts_link(); ?>
                    </span>
                </div>
            </header>
            <?php if ( has_post_thumbnail() ) : ?>
                <div class="entry-thumb">
                    <a href="<?php the_permalink(); ?>">
                        <?php the_post_thumbnail( 'medium' ); ?>
                    </a>
                </div>
            <?php endif; ?>
            <div class="entry-content">
                <?php the_excerpt(); ?>
            </div>
            <footer class="entry-footer">
                <?php the_category( '، ' ); ?>
            </footer>
        </article>
    <?php endwhile; ?>

    <?php the_posts_pagination(); ?>
<?php else : ?>
    <p><?php esc_html_e( 'نوشته‌ای یافت نشد.', 'my-theme' ); ?></p>
<?php endif; ?>

سه نکته در این الگو: یک — post_class: کلاس‌های مفید بر اساس وضعیت و نوع نوشته اضافه می‌کند. دو — the_ID: شناسه را برای اتصال CSS یا JS در اختیار می‌گذارد. سه — the_posts_pagination: صفحه‌بندی پیش‌فرض وردپرس. راهنمای کامل قالب در ساختار فایل‌های قالب استاندارد، توسعهٔ قالب از صفر، و ساخت شورت‌کد.

escape خروجی و امنیت

خروجی توابع دادهٔ نوشته، همیشه نیاز به escape دارد، مگر خودِ تابع escape را انجام داده باشد. سه گروه: یک — توابع چاپ‌کنندهٔ escape‌شده: the_title، the_content، the_excerpt، the_author، the_category. دو — توابع بازگرداننده (بدون escape): get_the_title، get_the_excerpt، get_permalink، get_the_author_meta. اگر خودتان چاپ می‌کنید، باید escape کنید:

$title = get_the_title();
echo esc_html( $title );

$url = get_permalink();
echo esc_url( $url );

$content = get_the_content();
echo wp_kses_post( $content ); // اگر HTML مجاز است

سه — متادیتا و داده‌های سفارشی: همیشه با esc_html، esc_attr، یا esc_url بسته به زمینه. راهنمای کامل در PHP امن در وردپرس، پاک‌سازی داده‌ها، اعتبارسنجی داده‌ها، و امنیت وردپرس برای مبتدیان. یک آسیب‌پذیری شایع که در پرونده‌های امنیتی دیده‌ام: قالب‌هایی که متادیتای سفارشی را بدون escape چاپ می‌کنند و در روزی که یک کاربر غیرمجاز، متا را از مسیری آلوده می‌کند، XSS می‌گیرند.

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

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

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