🏷 فصل ۷: Template Tags و توابع وردپرس

Template Tag ها توابع کمکی وردپرس هستن که محتوای داینامیک رو در قالب نمایش می‌دن. توی این فصل پرکاربردترین‌ها رو یاد می‌گیریم.

🤔 Template Tag چیست؟

توابعی که برای نمایش یا گرفتن اطلاعات از پایگاه داده طراحی شدن. دو نوع داریم:

• Display tags (با پیشوند the_): مستقیم چاپ می‌کنن
• Get tags (با پیشوند get_the_): مقدار رو برمی‌گردونن

// نمایش مستقیم
the_title();
// خروجی: عنوان نوشته (echo می‌کنه)

// گرفتن مقدار
$title = get_the_title();
// مقدار در $title ذخیره می‌شه - بعداً می‌تونی استفاده کنی
echo strtoupper($title);

📝 تگ‌های نوشته

اطلاعات اصلی

تصویر شاخص

// چک کن که تصویر شاخص داره
if ( has_post_thumbnail() ) {
    
    // نمایش با اندازه پیش‌فرض
    the_post_thumbnail();
    
    // با اندازه خاص
    the_post_thumbnail( 'large' );  // thumbnail, medium, large, full
    
    // اندازه سفارشی
    the_post_thumbnail( array( 600, 400 ) );
    
    // با attribute
    the_post_thumbnail( 'large', array(
        'alt'   => get_the_title(),
        'class' => 'featured-img rounded',
    ) );
    
    // فقط URL تصویر
    $thumbnail_url = get_the_post_thumbnail_url( get_the_ID(), 'large' );
}

دسته‌بندی و برچسب

// نمایش دسته‌ها به صورت لینک
the_category( ', ' );  // با جداکننده ویرگول

// گرفتن دسته‌ها
$categories = get_the_category();
foreach ( $categories as $cat ) {
    echo $cat->name;
    echo $cat->slug;
    echo $cat->term_id;
}

// نمایش برچسب‌ها
the_tags( 'برچسب: ', ', ', '' );

// taxonomy سفارشی
the_terms( get_the_ID(), 'product_category', '', ', ', '' );

🌐 تگ‌های سایت

اطلاعات سایت

bloginfo( 'name' );          // عنوان سایت
bloginfo( 'description' );    // توضیحات
bloginfo( 'url' );           // آدرس سایت
bloginfo( 'admin_email' );   // ایمیل ادمین
bloginfo( 'charset' );       // UTF-8
bloginfo( 'language' );      // fa-IR
bloginfo( 'rss2_url' );      // فید RSS
bloginfo( 'pingback_url' );  // pingback

URL ها

// آدرس صفحه اصلی
echo home_url( '/' );

// آدرس یه برگه با مسیر
echo home_url( '/contact' );

// آدرس قالب فعال
echo get_template_directory_uri();        // قالب والد
echo get_stylesheet_directory_uri();      // قالب فعلی (فرزند یا والد)

// مسیر فیزیکی قالب
echo get_template_directory();
echo get_stylesheet_directory();

// آدرس wp-admin
echo admin_url();
echo admin_url( 'edit.php' );

// آدرس آرشیو CPT
echo get_post_type_archive_link( 'icsd_product' );

🎯 تگ‌های شرطی (Conditional Tags)

توابعی که چک می‌کنن کاربر روی چه نوع صفحه‌ایه:

if ( is_home() ) {
    // صفحه وبلاگ
}

if ( is_front_page() ) {
    // صفحه اصلی سایت
}

if ( is_single() ) {
    // تک نوشته
}

if ( is_singular( 'icsd_product' ) ) {
    // تک محصول (CPT خاص)
}

if ( is_page() ) {
    // برگه
}

if ( is_page( 'about' ) ) {
    // برگه «درباره ما»
}

if ( is_archive() ) {
    // هر نوع آرشیو
}

if ( is_category() ) {
    // آرشیو دسته‌بندی
}

if ( is_tag() ) {
    // آرشیو برچسب
}

if ( is_search() ) {
    // صفحه نتایج جستجو
}

if ( is_404() ) {
    // صفحه ۴۰۴
}

if ( is_user_logged_in() ) {
    // کاربر وارد شده
}

if ( is_admin() ) {
    // در پنل ادمین (نه فرانت!)
}

if ( wp_is_mobile() ) {
    // کاربر موبایلیه
}

🔍 WP_Query پیشرفته

وقتی می‌خوای کوئری اختصاصی بنویسی (نه حلقه پیش‌فرض)، از WP_Query استفاده کن:

کوئری ساده

$query = new WP_Query( array(
    'post_type'      => 'post',
    'posts_per_page' => 5,
    'orderby'        => 'date',
    'order'          => 'DESC',
) );

if ( $query->have_posts() ) :
    while ( $query->have_posts() ) :
        $query->the_post();
        // نمایش
        the_title();
    endwhile;
    wp_reset_postdata(); // مهم!
endif;

کوئری پیشرفته

$args = array(
    'post_type'      => 'icsd_product',
    'posts_per_page' => 12,
    'orderby'        => 'meta_value_num',
    'meta_key'       => '_price',
    'order'          => 'ASC',
    
    // فیلتر بر اساس taxonomy
    'tax_query' => array(
        array(
            'taxonomy' => 'product_tech',
            'field'    => 'slug',
            'terms'    => array( 'django', 'flutter' ),
            'operator' => 'IN',
        ),
    ),
    
    // فیلتر بر اساس meta
    'meta_query' => array(
        'relation' => 'AND',
        array(
            'key'     => '_featured',
            'value'   => '1',
            'compare' => '=',
        ),
        array(
            'key'     => '_price',
            'value'   => 100000,
            'type'    => 'NUMERIC',
            'compare' => '>',
        ),
    ),
    
    // تاریخ
    'date_query' => array(
        array(
            'after' => '1 month ago',
        ),
    ),
);

$query = new WP_Query( $args );

پارامترهای کلیدی WP_Query

📦 کار با Post Meta

metadata اطلاعات اضافی برای هر نوشته‌ست. مثل قیمت محصول، نسخه نرم‌افزار و…

$post_id = get_the_ID();

// ذخیره
update_post_meta( $post_id, '_price', 250000 );
update_post_meta( $post_id, '_in_stock', 'yes' );
update_post_meta( $post_id, '_features', array( 'rtl', 'persian' ) );

// خوندن
$price = get_post_meta( $post_id, '_price', true );  // single
$features = get_post_meta( $post_id, '_features', true );

// همه meta
$all_meta = get_post_meta( $post_id );

// حذف
delete_post_meta( $post_id, '_price' );

// افزودن (بدون جایگزینی)
add_post_meta( $post_id, '_views', 1, true );

🎯 مثال‌های کاربردی

<span class="post-time">
    <?php echo human_time_diff( get_the_time('U'), current_time('timestamp') ); ?> پیش
</span>
<!-- خروجی: ۲ ساعت پیش -->

<?php
// گرفتن دسته‌های نوشته فعلی
$categories = wp_get_post_categories( get_the_ID() );

if ( ! empty( $categories ) ) :
    $related = new WP_Query( array(
        'category__in'   => $categories,
        'posts_per_page' => 4,
        'post__not_in'   => array( get_the_ID() ),
        'orderby'        => 'rand',
    ) );

    if ( $related->have_posts() ) : ?>
        <section class="related-posts">
            <h3>نوشته‌های مرتبط</h3>
            <div class="grid">
                <?php while ( $related->have_posts() ) : $related->the_post(); ?>
                    <article class="related-card">
                        <a href="<?php the_permalink(); ?>">
                            <?php the_post_thumbnail( 'medium' ); ?>
                            <h4><?php the_title(); ?></h4>
                        </a>
                    </article>
                <?php endwhile; ?>
            </div>
        </section>
        <?php
        wp_reset_postdata();
    endif;
endif;
?>

// افزایش شمارنده با هر بازدید
function track_post_views() {
    if ( is_single() && ! is_user_logged_in() ) {
        $post_id = get_the_ID();
        $count = (int) get_post_meta( $post_id, '_post_views', true );
        $count++;
        update_post_meta( $post_id, '_post_views', $count );
    }
}
add_action( 'wp_head', 'track_post_views' );

// تابع کمکی برای نمایش
function get_post_views( $post_id = null ) {
    if ( ! $post_id ) $post_id = get_the_ID();
    $count = (int) get_post_meta( $post_id, '_post_views', true );
    return $count;
}

// در single.php
echo '<span>بازدید: ' . number_format_i18n( get_post_views() ) . '</span>';

📝 خلاصه فصل

• تگ‌های the_ چاپ می‌کنن، get_the_ برمی‌گردونن
• تگ‌های شرطی برای کنترل نمایش
• WP_Query برای کوئری‌های اختصاصی
• همیشه بعد از WP_Query، wp_reset_postdata() رو فراموش نکن
• meta با پیشوند _ در ادمین مخفیه