راهنمای توسعه‌دهنده

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

#شورت‌کد

[pelk_stories section="default"]

شورت‌کد فقط یک پارامتر دارد: section، کلید سکشن. کلید را در سکشن‌های استوری از فیلد شورت‌کد هر سکشن بردار؛ بعد از ذخیره عوض نمی‌شود (سکشن‌ها و محل نمایش).

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

در فایل‌های قالب:

<?php echo do_shortcode( '[pelk_stories section="default"]' ); ?>

#فیلتر و اکشن‌ها

#فیلتر pelk/section_html

HTML هر سکشن را پیش از چاپ تغییر می‌دهد. دو آرگومان دارد: HTML (جعبه‌ی سکشن و داده‌اش) و داده‌ی سکشن (ساختارش پایین‌تر آمده). فقط برای سکشنی اجرا می‌شود که استوری قابل نمایش دارد.

add_filter(
	'pelk/section_html',
	function ( $html, $section ) {
		if ( 'shop' !== $section['key'] ) {
			return $html;
		}

		return '<div class="my-shop-stories">' . $html . '</div>';
	},
	10,
	2
);

#کش صفحه‌ها

هر بار که چیزی که سکشن‌ها نشان می‌دهند عوض می‌شود (استوری ذخیره، منتشر، تمام یا حذف می‌شود، استوری زمان‌بندی‌شده شروع می‌شود، تنظیمات ذخیره یا درون‌ریزی می‌شوند)، پلک در پایان همان درخواست یک بار کل کش صفحه‌های سایت را پاک می‌کند، از راه API خود هر افزونه‌ی کشی که فعال است: WP Rocket، LiteSpeed Cache، W3 Total Cache، WP Super Cache، WP Fastest Cache، SiteGround Optimizer، WP-Optimize، Cache Enabler، Breeze، Hummingbird، Nginx Helper و افزونه‌ی Cloudflare (وقتی صفحه‌ها را کش می‌کند، مثلاً با APO).

#فیلتر pelk/purge_page_cache

با برگرداندن false، پلک کش صفحه‌ها را پاک نمی‌کند (کش خود پلک همچنان پاک می‌شود):

add_filter( 'pelk/purge_page_cache', '__return_false' );

#اکشن pelk/page_cache_purged

بعد از هر بار پاک کردن کش صفحه‌ها اجرا می‌شود و نام کش‌هایی را که پلک پاک کرده می‌گیرد (مثلاً array( 'WP Rocket' )). برای کش هاست یا CDN که پلک نمی‌شناسد، این‌جا پاکش کن:

add_action(
	'pelk/page_cache_purged',
	function ( $purged ) {
		my_host_purge_everything(); // Your host's or CDN's own purge.
	}
);

#اکشن pelk/cache_cleared

وقتی در پیشرفته دکمه‌ی پاک کردن کش زده می‌شود اجرا می‌شود، بعد از این‌که پلک کش خودش و کش صفحه‌ها را پاک کرد.

#REST API

برای اپ موبایل یا سایت دیگری که استوری‌ها را از پلک می‌خواند، در پیشرفته دسترسی REST API برای استوری‌ها را روشن کن. تا وقتی خاموش است، این نشانی پاسخ 404 با کد rest_no_route می‌دهد.

GET /wp-json/pelk/v1/public/stories?section=default

پاسخ برای بازدیدکننده‌ی مهمان ساخته می‌شود: استوری‌های تمام‌شده و استوری‌ها و اسلایدهای فقط کاربران واردشده در آن نیستند. شرط‌هایی که به ساعت یا صفحه‌ی بیننده بستگی دارند در داده می‌مانند و اپ خودش باید آن‌ها را اعمال کند: device هر استوری و when هر اسلاید.

بقیه‌ی مسیرهای pelk/v1 (مثل track، seen و likes) برای نمایشگر و پنل خود پلک‌اند و ممکن است در نسخه‌های بعدی عوض شوند؛ به آن‌ها تکیه نکن.

#ساختار داده‌ی سکشن

همه‌ی زمان‌ها Unix timestamp (ثانیه) هستند.

section: key, size (small|medium|large), gap, order (manual|newest|oldest|random),
         show_titles, seen_last, autoplay_next, stories[]

story:   id, slug, title, link, cover, pinned, published_at, ends_at (0 = never),
         updated_at, device (both|mobile|desktop), video_sound (muted|sound),
         autoplay_next, slides[]

cover:   type (image|icon|color), url, srcset, icon, svg, color

slide:   id, type (image|video|text), duration, title, description, label,
         heading, body, image, video, bg, cta, when

image:   src, srcset, width, height          (or null)
video:   src, mime, poster                   (or null)
bg:      type, color, image                  (or null)
cta:     text, url, new_tab                  (or null)
when:    from, to (0 = open), hours { start, end } (site time, H:i, or null)

link نشانی مستقیم همان استوری است (?story=…) که روی سایت نمایشگر را باز می‌کند.

#رویدادهای گوگل آنالیتیکس

با ارسال رویدادها به گوگل آنالیتیکس در پیشرفته، پلک هر رویداد را به window.dataLayer می‌فرستد؛ با Google Tag Manager برایشان تریگر بساز.

هر رویداد این‌ها را هم دارد: pelk_story (شناسه‌ی استوری)، pelk_slide (شناسه‌ی اسلاید، برای رویدادهای استوری خالی) و pelk_section (کلید سکشن، برای لینک مستقیم خالی).

{ event: 'pelk_click', pelk_story: 20, pelk_slide: 'sl_jszeftld', pelk_section: 'default' }

#رویداد مرورگر

اسکریپت پلک وقتی آماده شد رویداد pelk:ready را روی window می‌فرستد:

window.addEventListener( 'pelk:ready', () => {
	// Pelk has loaded.
} );

#چند نکته‌ی دیگر

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