// chapter_06.md

🛠 فصل ۶: توسعه قالب وردپرس – مقدمه

از این فصل شروع می‌کنیم به ساخت قالب اختصاصی وردپرس از صفر. ساختار فایل‌ها، Template Hierarchy، حلقه (Loop) و توابع کلیدی قالب‌نویسی رو یاد می‌گیریم.

🤔 چرا قالب اختصاصی بسازیم؟

قالب آماده مزایای زیادی داره ولی محدودیت هم داره. قالب اختصاصی وقتی لازمه که:

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

💼

برای ICSD

خودت قالب ICSD رو ساختی – این تجربه عالی توسعه قالب رو داری. توی این فصل اصول رو مرور می‌کنیم تا برای پروژه‌های بعدیت کاملاً ساختار رو بشناسی.

📁 ساختار قالب وردپرس

یه قالب در پوشه wp-content/themes/your-theme/ قرار می‌گیره. حداقل فایل‌های لازم:

ساختار حداقلی

my-theme/
├── style.css          (الزامی - اطلاعات قالب)
├── index.php          (الزامی - فایل اصلی)
└── screenshot.png     (پیشنهادی - تصویر کارت قالب)

ساختار قالب حرفه‌ای

ساختار کامل

my-theme/
├── style.css                # اطلاعات + استایل اصلی
├── index.php                # فایل پیش‌فرض
├── functions.php            # توابع و قابلیت‌ها
├── header.php               # هدر مشترک
├── footer.php               # فوتر مشترک
├── sidebar.php              # سایدبار
├── single.php               # نمایش تک نوشته
├── page.php                 # نمایش برگه
├── archive.php              # آرشیو
├── category.php             # دسته‌بندی
├── search.php               # نتایج جستجو
├── 404.php                  # صفحه خطا
├── front-page.php           # صفحه اصلی
├── home.php                 # صفحه وبلاگ
├── comments.php             # دیدگاه‌ها
├── searchform.php           # فرم جستجو
├── screenshot.png           # تصویر قالب
├── inc/                     # فایل‌های PHP کمکی
│   ├── custom-post-types.php
│   ├── customizer.php
│   └── template-functions.php
├── template-parts/          # قطعات قالب
│   ├── content.php
│   ├── content-page.php
│   └── content-single.php
├── page-templates/          # قالب‌های اختصاصی صفحه
│   └── full-width.php
├── assets/                  # فایل‌های استاتیک
│   ├── css/
│   ├── js/
│   ├── images/
│   └── fonts/
└── languages/               # ترجمه

🚀 ساخت اولین قالب از صفر

قدم ۱: ساخت پوشه و style.css

یه پوشه به اسم my-first-theme در wp-content/themes/ بساز.

style.css

/*
Theme Name: قالب اول من
Theme URI: https://icsd.ir
Author: محمدعلی ناظری
Author URI: https://icsd.ir
Description: یه قالب ساده برای یاد گرفتن
Version: 1.0.0
Requires at least: 6.0
Tested up to: 6.5
Requires PHP: 7.4
License: GPL v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-first-theme
Tags: rtl, persian, blog, custom-menu
*/

body {
    font-family: 'Vazirmatn', Tahoma, sans-serif;
    direction: rtl;
    text-align: right;
    line-height: 1.8;
    margin: 0;
    background: #f8f9fa;
    color: #333;
}

.site-container {
    max-width: 1200px;
    margin: 0 auto;
    padding: 20px;
}

قدم ۲: index.php

index.php

<?php get_header(); ?>

<main class="site-container">
    <?php if ( have_posts() ) : ?>
        <?php while ( have_posts() ) : the_post(); ?>
            <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
                <h2>
                    <a href="<?php the_permalink(); ?>">
                        <?php the_title(); ?>
                    </a>
                </h2>
                <div class="post-content">
                    <?php the_excerpt(); ?>
                </div>
            </article>
        <?php endwhile; ?>

        <?php the_posts_pagination(); ?>
    <?php else : ?>
        <p>هیچ نوشته‌ای یافت نشد.</p>
    <?php endif; ?>
</main>

<?php get_footer(); ?>

قدم ۳: header.php

header.php

<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
    <meta charset="<?php bloginfo( 'charset' ); ?>">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<?php wp_body_open(); ?>

<header class="site-header">
    <div class="site-container">
        <h1 class="site-title">
            <a href="<?php echo esc_url( home_url( '/' ) ); ?>">
                <?php bloginfo( 'name' ); ?>
            </a>
        </h1>
        <p class="site-description"><?php bloginfo( 'description' ); ?></p>

        <nav class="main-navigation">
            <?php
            wp_nav_menu( array(
                'theme_location' => 'primary',
                'menu_class'     => 'main-menu',
                'fallback_cb'    => false,
            ) );
            ?>
        </nav>
    </div>
</header>

footer.php

<footer class="site-footer">
    <div class="site-container">
        <p>
            &copy; <?php echo date('Y'); ?>
            <a href="<?php echo esc_url( home_url( '/' ) ); ?>">
                <?php bloginfo( 'name' ); ?>
            </a>
            - تمامی حقوق محفوظه
        </p>
    </div>
</footer>

<?php wp_footer(); ?>
</body>
</html>

قدم ۵: functions.php

functions.php

<?php
/**
 * توابع قالب اول من
 */

if ( ! defined( 'ABSPATH' ) ) exit;

// راه‌اندازی قالب
function my_theme_setup() {
    // پشتیبانی از تگ‌های HTML5
    add_theme_support( 'html5', array( 'search-form', 'comment-form', 'gallery', 'caption' ) );
    
    // پشتیبانی از تصویر شاخص
    add_theme_support( 'post-thumbnails' );
    
    // عنوان خودکار از وردپرس
    add_theme_support( 'title-tag' );
    
    // لوگوی سفارشی
    add_theme_support( 'custom-logo' );
    
    // ثبت منو
    register_nav_menus( array(
        'primary' => 'منوی اصلی',
        'footer'  => 'منوی فوتر',
    ) );
}
add_action( 'after_setup_theme', 'my_theme_setup' );

// لود کردن استایل و اسکریپت
function my_theme_enqueue() {
    wp_enqueue_style( 'my-theme-style', get_stylesheet_uri(), array(), '1.0.0' );
}
add_action( 'wp_enqueue_scripts', 'my_theme_enqueue' );

قدم ۶: فعال‌سازی!

توی پنل وردپرس به نمایش → پوسته‌ها برو. قالب جدیدت اونجاست! فعالش کن و سایت رو ببین.

🎉

تبریک!

اولین قالب وردپرست رو ساختی. ساده ولی کاملاً کار می‌کنه.

🌳 Template Hierarchy

وردپرس بر اساس URL تصمیم می‌گیره از کدوم فایل قالب استفاده کنه. این تصمیم‌گیری از یه ساختار درختی تبعیت می‌کنه:

برای صفحه اصلی

front-page.php
home.php
index.php

برای تک نوشته

single-{post-type}-{slug}.php
single-{post-type}.php (مثلاً single-product.php)
single.php
singular.php
index.php

برای برگه

{custom-template}.php (قالب اختصاصی)
page-{slug}.php (مثلاً page-about.php)
page-{id}.php
page.php
singular.php
index.php

برای آرشیو

archive-{post-type}.php
archive.php
index.php

برای دسته/برچسب

category-{slug}.php یا tag-{slug}.php
category.php یا tag.php
archive.php
index.php

📚

منبع کامل

نمودار کامل Template Hierarchy رو در developer.wordpress.org ببین.

🔄 حلقه وردپرس (The Loop)

قلب نمایش محتوا توی وردپرس. وردپرس بر اساس URL، یه سری نوشته بازیابی می‌کنه و حلقه نمایششون می‌ده.

ساختار پایه

حلقه استاندارد

<?php
if ( have_posts() ) :
    while ( have_posts() ) :
        the_post();
        // اینجا محتوای هر نوشته رو نمایش بده
        ?>
        <article>
            <h2><?php the_title(); ?></h2>
            <div><?php the_content(); ?></div>
        </article>
        <?php
    endwhile;
else :
    echo '<p>چیزی پیدا نشد!</p>';
endif;
?>

توابع داخل حلقه

the_title() – عنوان
the_content() – محتوای کامل
the_excerpt() – چکیده
the_permalink() – لینک نوشته
the_date() – تاریخ انتشار
the_author() – نام نویسنده
the_post_thumbnail() – تصویر شاخص
the_category() – دسته‌ها
the_tags() – برچسب‌ها
get_the_ID() – شناسه نوشته

⚡ enqueue صحیح فایل‌ها

هرگز CSS و JS رو مستقیم توی قالب hardcode نکن. روش درست استفاده از enqueue هست:

functions.php

function my_theme_assets() {
    // CSS اصلی
    wp_enqueue_style(
        'my-theme-main',                              // handle یکتا
        get_template_directory_uri() . '/assets/css/main.css',  // مسیر
        array(),                                       // وابستگی‌ها
        '1.0.0',                                       // نسخه
        'all'                                          // media type
    );
    
    // فونت گوگل
    wp_enqueue_style(
        'vazirmatn',
        'https://fonts.googleapis.com/css2?family=Vazirmatn:wght@400;700&display=swap',
        array(),
        null
    );
    
    // JavaScript
    wp_enqueue_script(
        'my-theme-script',
        get_template_directory_uri() . '/assets/js/main.js',
        array( 'jquery' ),                            // وابسته به jQuery
        '1.0.0',
        true                                           // در فوتر
    );
    
    // پاس کردن متغیر به JavaScript
    wp_localize_script( 'my-theme-script', 'myTheme', array(
        'ajaxUrl' => admin_url( 'admin-ajax.php' ),
        'nonce'   => wp_create_nonce( 'my_theme_nonce' ),
    ) );
}
add_action( 'wp_enqueue_scripts', 'my_theme_assets' );

⚠️

چرا enqueue مهمه؟

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

🎯 مثال‌های عملی

آسان

مثال ۱: نمایش ۳ نوشته آخر در سایدبار

sidebar.php

<aside class="sidebar">
    <h3>آخرین نوشته‌ها</h3>
    <ul>
        <?php
        $recent_posts = new WP_Query( array(
            'posts_per_page' => 3,
            'post_status'    => 'publish',
        ) );
        
        if ( $recent_posts->have_posts() ) :
            while ( $recent_posts->have_posts() ) :
                $recent_posts->the_post(); ?>
                <li>
                    <a href="<?php the_permalink(); ?>">
                        <?php the_title(); ?>
                    </a>
                </li>
            <?php endwhile;
            wp_reset_postdata(); // مهم: ریست کردن
        endif;
        ?>
    </ul>
</aside>

متوسط

مثال ۲: نمایش تصویر شاخص با fallback

single.php

<?php if ( has_post_thumbnail() ) : ?>
    <div class="post-thumbnail">
        <?php the_post_thumbnail( 'large', array(
            'alt'   => get_the_title(),
            'class' => 'featured-image',
        ) ); ?>
    </div>
<?php else : ?>
    <div class="post-thumbnail post-thumbnail-default">
        <img src="<?php echo get_template_directory_uri(); ?>/assets/images/default.jpg" 
             alt="<?php the_title_attribute(); ?>">
    </div>
<?php endif; ?>

پیشرفته

مثال ۳: ساخت قالب صفحه اختصاصی

یه قالب Full-Width بدون سایدبار:

page-templates/full-width.php

<?php
/**
 * Template Name: تمام‌عرض
 * Template Post Type: page
 */

get_header(); ?>

<main class="full-width-main">
    <div class="container-fluid">
        <?php
        while ( have_posts() ) :
            the_post();
            ?>
            <article <?php post_class(); ?>>
                <h1><?php the_title(); ?></h1>
                <div class="content">
                    <?php the_content(); ?>
                </div>
            </article>
        <?php endwhile; ?>
    </div>
</main>

<?php get_footer(); ?>

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

📝 خلاصه فصل

قالب وردپرس حداقل به style.css و index.php نیاز داره
Template Hierarchy تعیین می‌کنه از کدوم فایل استفاده بشه
The Loop قلب نمایش محتواست
همیشه از wp_enqueue_* برای CSS/JS استفاده کن
توابع get_template_directory_uri() و home_url() رو حفظ کن