پستتایپ سفارشی وردپرس، ACF و صفحات مدیریت
در این راهنما یک نوع محتوای سفارشی وردپرس را به اپ متصل میکنید، فیلدهای ACF آن را انتخاب میکنید و صفحههای نمایش و مدیریت محتوا را بهصورت خودکار میسازید.
برای نمایش عمومی پستتایپ و فیلدهای ACF، فعال بودن REST API کافی است. برای ساخت، ویرایش یا حذف محتوا از داخل اپ باید افزونهٔ AppEditor - App Builder for WordPress نسخهٔ ۰٫۷٫۰ یا جدیدتر نصب باشد و کاربر وردپرس مجوز لازم را داشته باشد.
پیشنیازها
پیش از شروع، این موارد را آماده کنید:
- سایت را طبق راهاندازی اتصال وردپرس در اپادیتور ثبت و به اپ متصل کرده باشید؛
- HTTPS و REST API وردپرس در دسترس عمومی باشند؛
- پستتایپ سفارشی با گزینهٔ
show_in_restفعال شده باشد؛ - برای استفاده از فیلدهای سفارشی، افزونهٔ ACF نصب و فعال باشد و گروه فیلد به پستتایپ موردنظر اختصاص یافته باشد؛
- دستکم یک محتوای منتشرشده با مقدارهای نمونه داشته باشید تا اپادیتور بتواند شکل دادههای ACF را تشخیص دهد؛
- برای صفحات مدیریت، افزونهٔ AppEditor نسخهٔ ۰٫۷٫۰ یا جدیدتر نصب و با کلید اتصال به پنل وصل باشد.
نسخههای پیش از ۰٫۷٫۰ میتوانند محتوای عمومی REST را نمایش دهند، اما مدیریت پستتایپ سفارشی، taxonomy، تصویر شاخص و ACF را پشتیبانی نمیکنند. وجود نسخهٔ قدیمی افزونه برای فعال شدن صفحات مدیریت کافی نیست.
چککردن تنظیمات وردپرس
فعال بودن REST برای پستتایپ
پستتایپ فقط وقتی در اپادیتور دیده میشود که در ثبت آن show_in_rest برابر true باشد. اگر آن را با افزونهای مانند CPT UI ساختهاید، گزینهٔ Show in REST API را در تنظیمات همان پستتایپ روشن کنید.
برای بررسی، نشانی زیر را با دامنهٔ سایت خود باز کنید:
https://example.com/wp-json/wp/v2/types
نام پستتایپ باید در پاسخ JSON دیده شود. attachment و product در این فهرست اپادیتور نمایش داده نمیشوند، چون رسانه و محصول ووکامرس سرویسهای اختصاصی خود را دارند.
فعال بودن REST برای ACF
در پیشخوان وردپرس، گروه فیلد ACF را ویرایش و گزینهٔ Show in REST API را روشن کنید. سپس مطمئن شوید قواعد نمایش گروه فیلد، پستتایپ انتخابی را پوشش میدهد.
اگر این گزینه خاموش باشد، فیلدها در پاسخ عمومی وردپرس نیستند و اپادیتور نمیتواند آنها را برای نمایش یا ساخت صفحه پیشنهاد کند.
گام ۱: اتصال سایت وردپرسی
- اپ را در پنل اپادیتور باز کنید.
- به تنظیمات اپ ← اتصال به وردپرس بروید.
- سایت را با نشانی کامل
https://اضافه کنید و آن را در انتخاب سایت برگزینید. - برای نمایش عمومی، روی بررسی اتصال بزنید تا REST API سایت خوانده شود.
- برای صفحات مدیریت، افزونهٔ نسخهٔ ۰٫۷٫۰ یا جدیدتر را در وردپرس نصب کنید، از پنل یک کلید اتصال بسازید و آن را در اپ ادیتور ← تنظیمات وردپرس وارد کنید؛ سپس آزمایش اتصال را بزنید.
کلید اتصال فقط یک بار بهصورت کامل نمایش داده میشود. ساخت کلید جدید، کلید قبلی را باطل میکند.
گام ۲: انتخاب custom post type
- در صفحهٔ دلخواه یک لیست پویا اضافه کنید.
- در منبع داده، نوع منبع را روی WordPress بگذارید.
- سایت وردپرسی را انتخاب کنید.
- روی دکمهٔ بهروزرسانی (آیکون دو فلش چرخان) کنار سایت وردپرسی بزنید تا فهرست انواع محتوا و فیلترها دوباره از سایت دریافت شود.
- در نوع داده، پستتایپ سفارشی را انتخاب کنید.
پستتایپهای سفارشی با شناسهای مانند wp.type.book ذخیره میشوند. اگر taxonomy متصل به آن در REST فعال و برای فیلتر پشتیبانی شده باشد، فیلتر آن نیز در همان پنجره ظاهر میشود.
فیلترهای رایج مانند جستوجو، نویسنده، تاریخ و ترتیب بهصورت بصری در دسترساند. برای پارامترهای دیگر یا مقدارهای متغیر میتوانید از تنظیمات پیشرفتهٔ JSON استفاده کنید.
اگر پستتایپ در فهرست نیست، ابتدا show_in_rest را در وردپرس بررسی کنید و سپس دوباره دکمهٔ بهروزرسانی را بزنید. اپادیتور نوع ناشناخته یا حذفشده را خودکار به «نوشته» تبدیل نمیکند.
گام ۳: انتخاب فیلدهای ACF
در پنجرهٔ ساخت صفحهها، فیلدهای ACF قابل نمایش را انتخاب کنید. اپادیتور نام، نوع داده، یک نمونهٔ مقدار و مسیر اتصال هر فیلد را از REST عمومی سایت میخواند.
دو قالب دریافت مقدار در دسترس است:
| قالب | کاربرد |
|---|---|
light | پاسخ سبکتر؛ مناسب فیلدهای ساده و صفحههایی که سرعت اولویت دارد |
standard | مقدار قالببندیشدهٔ ACF؛ مناسب تصویر، گالری، رابطهها و ساختارهایی که جزئیات بیشتری لازم دارند |
برای یک تصویر یا ساختار تودرتو، مسیر فرزند قابل نمایش را انتخاب کنید؛ برای نمونه:
sys.inPage.entity.raw.acf.cover.url
sys.inPage.entity.raw.acf.gallery.0.url
مسیر دوم فقط اولین تصویر گالری را نمایش میدهد. برای نمایش همهٔ اعضای گالری یا repeater باید یک لیست تودرتو طراحی کنید و مسیر آرایه را بهصورت دستی به آن بدهید.
محدودیتهای انتخاب و نمایش ACF
- فقط فیلدهایی دیده میشوند که گروه آنها Show in REST API دارد و در context عمومی
viewقابل خواندناند؛ فیلدهای محدود بهeditوارد انتخابگر نمیشوند. - وجود یک محتوای منتشرشده و مقداردهیشده به تشخیص بهتر نوع و مسیر فیلد کمک میکند. فیلد بدون نمونه ممکن است ناقص یا با عنوان «بدون نمونه» دیده شود.
- در هر بار ساخت خودکار، حداکثر ۲۰ فیلد متنی یا تصویری را میتوان به صفحهٔ جزئیات افزود.
- آرایه و آبجکت بهطور مستقیم به ویجت متن یا تصویر تبدیل نمیشوند؛ باید یک مقدار فرزند مانند
url،titleیا عضو اول آرایه را انتخاب کنید. - عمق ساختارهای بسیار تودرتو محدود است؛ برای ساختار پیچیده، مسیر را دستی تنظیم یا JSON را در طراحی پیشرفته پردازش کنید.
- نام فیلد قابل ذخیره باید فقط از حروف انگلیسی، عدد، خط تیره و زیرخط تشکیل شده باشد. برای جلوگیری از خطای ذخیره، نامهایی مانند
book_authorرا بهکار ببرید.
گام ۴: ساخت خودکار صفحات نمایش
- در تنظیمات منبع WordPress لیست پویا، ساخت خودکار صفحات این نوع محتوا را باز کنید.
- پستتایپ، قالب ACF و فیلدهای موردنیاز را بازبینی کنید.
- در صورت نیاز یک taxonomy قابل فیلتر را انتخاب کنید.
- ساخت صفحهها را تأیید کنید.
اپادیتور یک پوشه برای این نوع محتوا میسازد و صفحهها را به سایت، منبع داده و صفحههای مقصد درست متصل میکند.
بدون taxonomy، این صفحهها ساخته میشوند:
فهرست محتوا
├── کارت محتوا
└── جزئیات محتوا
با انتخاب taxonomy، سه صفحهٔ دیگر نیز ساخته میشوند:
فهرست دستهبندی
├── کارت دستهبندی
└── محتوای دستهبندی
صفحهها نقطهٔ شروع هستند. پس از ساخت میتوانید عنوانها، رنگها، چیدمان، حالت خالی و خطا و ویجتهای جزئیات را ویرایش کنید.
taxonomy فقط وقتی برای ساخت صفحههای دستهبندی قابل انتخاب است که به همان پستتایپ متصل باشد، در REST API دیده شود و مسیر REST آن از فیلتر محتوا پشتیبانی کند.
گام ۵: فعالکردن صفحات مدیریت محتوا
در همان پنجرهٔ ساخت خودکار، گزینهٔ صفحات مدیریت را روشن کنید. علاوه بر صفحههای نمایش، چهار صفحه ساخته میشود:
- فهرست مدیریت؛
- کارت مدیریت؛
- فرم ایجاد محتوا؛
- فرم ویرایش محتوا.
فرم تولیدشده عنوان، متن، خلاصه، شناسهٔ تصویر شاخص، taxonomyهای متصل و فیلدهای سادهٔ ACF را دارد. سه دکمهٔ ذخیره پیشنویس، ارسال برای بررسی و انتشار نیز ساخته میشود؛ فرم ویرایش دکمهٔ انتقال به زبالهدان دارد.
ورود درست را کنترل کنید
کاربر این صفحهها باید از داخل اپ به حساب وردپرس وارد شده باشد. گزینهٔ «نیاز به ورود» در تنظیمات صفحه مربوط به حساب اپادیتور است و جای ورود وردپرس را نمیگیرد. برای محدود کردن صفحههای مدیریت از شرط ورود کاربر به حساب وردپرس استفاده کنید.
مجوزهای وردپرس
افزونه نقش «مدیر» را دور نمیزند و capabilityهای واقعی همان پستتایپ را بررسی میکند:
| کار | مجوز لازم |
|---|---|
| دیدن فهرست و ساخت محتوا | edit_posts یا capability متناظر پستتایپ |
| ویرایش یک آیتم | edit_post برای همان آیتم |
| ویرایش محتوای کاربران دیگر | edit_others_posts یا capability متناظر |
| انتشار یا زمانبندی | publish_posts یا capability متناظر |
| انتقال به زبالهدان | delete_post برای همان آیتم |
| نسبتدادن taxonomy | assign_terms همان taxonomy |
اگر کاربر مجوز انتشار نداشته باشد، درخواست انتشار یا زمانبندی به وضعیت در انتظار بررسی تبدیل میشود. کاربری که مجوز ویرایش محتوای دیگران را ندارد فقط محتوای خودش را در فهرست مدیریت میبیند.
لازم نیست به همهٔ کاربران نقش مدیر بدهید. نقش یا capabilityهای پستتایپ را با اصل حداقل دسترسی تنظیم کنید؛ برای نمونه، نویسنده میتواند محتوای خودش را بسازد و برای بررسی بفرستد، در حالی که ویراستار امکان انتشار و ویرایش محتوای دیگران را دارد.
محدودیتهای ویرایش ACF
- فرم خودکار فقط فیلدهای سطح اول و مقدارپذیر را میسازد؛ متن، عدد و مقدارهای ساده مناسب این مسیرند.
- گروه، repeater، گالری، flexible content، relationship و ساختارهای آرایهای یا تودرتو به فرم خودکار تبدیل نمیشوند. این مقدارها را باید با طراحی دستی و آبجکت
acfدر تنظیمات پیشرفتهٔ عملکرد ذخیره ارسال کنید. - برای ذخیرهٔ ACF، خود افزونهٔ ACF باید روی سایت فعال باشد و تابع ذخیرهٔ آن در دسترس باشد.
- فیلد باید برای همان پستتایپ و آیتم معتبر باشد. اگر کلید یا نام فیلد شناخته نشود، عملیات با خطای ذخیره متوقف میشود.
- انتخابگر نمایش فقط دادهٔ عمومی را نشان میدهد؛ بنابراین ممکن است فیلدی از راه تنظیمات پیشرفته قابل ذخیره باشد اما بهعلت context خصوصی در انتخابگر نمایش داده نشود.
پس از ساخت صفحهها
- صفحهٔ فهرست عمومی و جزئیات را با چند محتوای واقعی بررسی کنید.
- با یک کاربر دارای نقش نویسنده وارد شوید و ساخت پیشنویس و ارسال برای بررسی را امتحان کنید.
- با یک کاربر دارای مجوز انتشار، ویرایش و انتقال به زبالهدان را بررسی کنید.
- فیلدهای خالی، تصویر شاخص نامعتبر و taxonomy بدون مجوز را نیز آزمایش کنید.
- اگر عملیات ناموفق بود، مقدار
sys.wordpress.lastErrorرا موقتاً در یک ویجت متن نمایش دهید تا پیام دقیق سرور را ببینید.
صفحههای مدیریت را فقط پشت شرط ورود وردپرس قرار دهید و صرفاً مخفی کردن دکمه یا صفحه را کنترل دسترسی حساب نکنید. کنترل نهایی روی سرور وردپرس انجام میشود، اما رابط اپ نیز نباید مسیر مدیریتی را برای کاربر مهمان نمایش دهد.
رفع اشکال سریع
| نشانه | علت محتمل | راهحل |
|---|---|---|
| پستتایپ در «نوع داده» نیست | show_in_rest خاموش یا REST مسدود است | REST پستتایپ را فعال و فهرست نوعها را بهروزرسانی کنید |
| هیچ فیلد ACF پیدا نمیشود | Show in REST API خاموش است یا نمونهٔ عمومی مقدار ندارد | گزینهٔ گروه فیلد را روشن و یک محتوای منتشرشده را مقداردهی کنید |
| فیلد تصویر بهصورت متن دیده میشود | قالب یا مسیر فرزند مناسب نیست | قالب standard و مسیر فرزندی مانند .url را انتخاب کنید |
| صفحات نمایش کار میکنند ولی مدیریت نه | افزونه قدیمی، اتصال افزونه قطع یا کاربر مهمان است | نسخهٔ ۰٫۷٫۰ یا جدیدتر، کلید اتصال و ورود وردپرس را بررسی کنید |
| کاربر فقط نوشتههای خودش را میبیند | مجوز ویرایش محتوای دیگران ندارد | capability نقش را در وردپرس بازبینی کنید |
| دکمه انتشار نتیجهٔ «در انتظار بررسی» میدهد | کاربر publish_posts متناظر را ندارد | مجوز انتشار بدهید یا همین گردش تأیید را حفظ کنید |
| taxonomy ذخیره نمیشود | taxonomy به پستتایپ متصل نیست یا assign_terms وجود ندارد | اتصال taxonomy و مجوز نقش را بررسی کنید |
| فیلد پیچیدهٔ ACF در فرم نیست | فرم خودکار فقط فیلد سادهٔ سطح اول را میسازد | فرم دستی و payload پیشرفتهٔ acf بسازید |