مفهوم‌های پایه

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

ویجت، نمونه و شناسه

هر بار که یک ویجت را روی صفحه می‌گذارید، یک نمونه ساخته می‌شود که شناسه‌ی یکتا دارد. در جستجوی زنده این شناسه در نام ریشه‌ی DOM استفاده می‌شود:

$uid = 'wgcr-search-' . sanitize_html_class( $uid !== '' ? $uid : 'sc' . $counter );

یعنی اگر در یک صفحه دو ویجت جستجو داشته باشید، هر کدام ریشه و وضعیت مستقل خودشان را دارند و روی هم اثر نمی‌گذارند. در ویجت سوالات متداول هم شناسه‌ی هر آیتم ترکیبی از شناسه‌ی ویجت و شماره‌ی آیتم است (wgcr-faq-q-{uid} و wgcr-faq-a-{uid}) تا aria-controls و aria-labelledby یکتا بمانند.

حالت نمایش (display mode)

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

منبع و پرس‌وجو

منبع (source) همان پست‌تایپی است که جستجو در آن انجام می‌شود. فقط پست‌تایپ‌های عمومی و قابل‌جستجو مجازند؛ اگر مقدار نامعتبری وارد شود، به post برمی‌گردد:

function wgcr_search_sanitize_source( $source ) {
	$source = sanitize_key( (string) $source );
	if ( '' === $source ) {
		return 'post';
	}
	$public = get_post_types( array( 'public' => true, 'exclude_from_search' => false ), 'names' );
	unset( $public['attachment'], $public['elementor_library'] );
	return isset( $public[ $source ] ) ? $source : 'post';
}

اگر «منبع» را روی پست‌تایپ سفارشی بگذارید، مقدار کنترل custom_type به‌عنوان اسلاگ استفاده می‌شود و در صورت خالی بودن، به post برمی‌گردد. attachment و elementor_library همیشه از فهرست مجاز بیرون می‌مانند.

پرس‌وجو مجموعه‌ای از فیلترهاست که روی همان منبع اعمال می‌شود:

پرس‌وجو در نهایت به یک WP_Query تبدیل می‌شود که همیشه post_status => publish و has_password => false دارد؛ یعنی نوشته‌های رمزدار یا پیش‌نویس هرگز در نتایج نمی‌آیند.

قالب (template)

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

در حالت سفارشی، شناسه‌ی قالب به REST فرستاده می‌شود و افزونه خروجی قالب را با get_builder_content_for_display() می‌سازد، CSS خود قالب را یک بار در صفحه بارگذاری می‌کند و هندلرهای سمت کاربر المنتور را روی آن اجرا می‌کند. اگر قالب خروجی قابل‌مشاهده‌ای نسازد، افزونه به کارت پیش‌فرض برمی‌گردد تا نتیجه خالی نماند.

صفحه‌بندی

صفحه‌بندی فقط وقتی معنا دارد که تعداد نتایج از «آیتم در هر برگه» بیشتر باشد.

در انواع شماره‌ای، درخواست با page فرستاده می‌شود و سرور هدرهای X-WP-Total و X-WP-TotalPages را برمی‌گرداند. در انواع «بارگذاری»، نتایج جدید به همان فهرست اضافه می‌شوند و جای نتایج قبلی را نمی‌گیرند.

کلاس‌های ریشه

ظاهر ویجت جستجو با کلاس‌های ریشه کنترل می‌شود؛ این کلاس‌ها را جاوااسکریپت بر اساس تنظیمات می‌سازد:

wgcr-search                       ریشه‌ی همه‌ی نمونه‌ها
wgcr-search--modal                حالت لیست
wgcr-search--page                 حالت نمایش در صفحه
wgcr-search--cols-3               تعداد ستون‌ها (1 تا 6)
wgcr-search--masonry              چیدمان آجری
wgcr-search--equal                ارتفاع برابر کارت‌ها
wgcr-search--tpl                  قالب سفارشی المنتور
wgcr-search--spacer               فاصله‌ی اضافی برای صفحه‌بندی

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

اسکیمای ساخت‌یافته

ویجت سوالات متداول در صورت فعال بودن کنترل «اسکیمای FAQ»، یک بلوک JSON-LD از نوع FAQPage چاپ می‌کند که mainEntity آن فهرست پرسش‌ها و پاسخ‌های همان ویجت است. اگر چند ویجت FAQ در یک صفحه باشد، فقط اولین ویجت اسکیما می‌دهد تا داده‌ی تکراری به موتور جستجو نرسد.

پیکربندی جاوااسکریپت

افزونه یک آبجکت پیکربندی به صورت درون‌خطی پیش از search.js چاپ می‌کند:

window.WGCRSearch = {
	restUrl: 'https://example.com/wp-json/wgcr/v1/search',
	homeUrl: 'https://example.com/',
	minChars: 2,
	maxResults: 50,
	i18n: { noResults: '…', found: '…', error: '…', prev: '…', next: '…', page: '…', pageOf: '…' }
};

restUrl و homeUrl از خود سایت گرفته می‌شوند، minChars حداقل طول عبارت، maxResults سقف نتایج (50) و i18n متن‌های رابط است که با زبان سایت ترجمه می‌شوند. هیچ‌کدام از این مقدارها را دستی در قالب ننویسید؛ اگر لازم است سقف نتایج عوض شود، ثابت WGCR_SEARCH_MAX_RESULTS را در wp-config.php تعریف کنید.