پرش به محتویات

سازنده پاپ‌آپ (Popup Builder)

سازنده پاپ‌آپ (Popup Builder) یک راه‌حل بسیار انعطاف‌پذیر و کاملاً قابل سفارشی‌سازی برای نمایش پاپ‌آپ در هر جایی از وب‌سایت شما بر اساس Interactions است.

یک popup در Bricks صرفاً یک قالب است. برای ساخت اولین popup، بیایید یک قالب جدید اضافه کنیم و نوع قالب جدید Popup را انتخاب کنیم:

نوع قالب Popup

قالب جدید را ذخیره کنید، سپس آن را با Bricks ویرایش کنید.

بلافاصله متوجه می‌شوید که این قالب با سایر نوع‌های قالب Bricks متفاوت به نظر می‌رسد.

محتوای popup در وسط canvas نمایش داده می‌شود، یک گروه «Template Settings» جدید با نام «Popup» وجود دارد، و «Populated Content» وجود ندارد:

صفحه نوع قالب Popup

ساخت محتوای popup دقیقاً مثل هر صفحه یا قالب دیگری در Bricks است: فقط المان‌های مورد نیاز را از طریق کلیک و/یا drag & drop به canvas اضافه کنید.

از template conditions داخل سازنده زیر «Settings > Template Settings > Conditions» استفاده کنید تا به Bricks بگویید این popup باید در کجای وب‌سایت شما نمایش داده شود.

شرط popup

می‌توانید به هر تعداد قالب popup که بخواهید به یک صفحه اضافه کنید.

تنظیمات مخصوص Popup در زیر «Settings > Template Settings > Popup» قرار دارند.

اولین گروه کنترل به شما امکان استایل‌دهی overlay و محتوای popup را می‌دهد:

تنظیمات Popup

می‌توانید popup های خود را به‌صورت سراسری از طریق گروه کنترل «Popups» داخل Theme Styles استایل دهید.

در پایین‌تر پنل تنظیمات popup، گروه کنترل Interactions را می‌یابید.

اینجاست که trigger های باز/بسته شدن popup را تعریف می‌کنید.

Trigger ها رویدادهای مرورگر مانند «Content loaded»، «Scroll» (به اندازه X px، X درصد از ارتفاع body یا X vh (ارتفاع viewport))، خروج موس از پنجره و غیره هستند.

یک trigger معمول این است که popup را پس از بارگذاری محتوا نمایش دهید (مثلاً popup خبرنامه، پیشنهادهای ویژه و غیره). برای این کار، یک تعامل «Content loaded» مانند این تنظیم کنید:

تعامل Content loaded

یادداشت

کلیک بیرون از محتوای popup (روی overlay) یا فشار دادن کلید ESC popup را می‌بندد.

اگر هیچ تعاملی روی خود popup یا هیچ المان دیگری در صفحه که popup را برای نمایش trigger کند تعریف نشده باشد، popup مخفی می‌ماند.

محدودیت Popup

به‌طور پیش‌فرض، popup هر بار که توسط یک تعامل trigger شود نمایش داده می‌شود.

همچنین می‌توانید محدودیت‌های popup را زیر «Settings > Template settings > Popup > Popup limit» هنگام ویرایش قالب popup خود تعریف کنید.

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

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

نوع محدودیت Browser storage توضیح
Per page load window.brx_popup_{id}_total پس از reload صفحه ریست می‌شود
Per session sessionStorage.brx_popup_{id}_total پس از بستن tab ریست می‌شود
Across sessions localStorage.brx_popup_{id}_total تا زمانی که حذف شود باقی می‌ماند

محدودیت Popup

رویدادها و توابع کمکی Popup

در زیر فهرست توابع کمکی و رویدادهای (JavaScript) موجود برای توسعه‌دهندگان آمده است.

می‌توانید از bricksOpenPopup و bricksClosePopup برای باز یا بستن برنامه‌نویسانه popup های ساخته‌شده در Bricks استفاده کنید.

هر دوی این توابع ID popup (= template ID) یا node المان popup را می‌پذیرند.

مثال: باز کردن Popup با selector

// Open Popup ID 3321 if any element with .brxe-heading or .my-custom-selector class
document.querySelectorAll('.brxe-heading, .my-custom-selector').forEach( (el) => {
    el.addEventListener('click', () => {
        bricksOpenPopup(3321)
    })
})

مثال: باز کردن یک popup حلقه‌ای با query element ID و loop index در بارگذاری صفحه

// Open a selected looping popup where query Element ID is vfiqrn and loop index is 7
document.addEventListener('DOMContentLoaded', ()=>{
    // If you are using code element, set some delay after DOMContentLoaded to ensure windows.bricksIsFrontend set properly
    setTimeout( ()=>{
        const queryId = 'vfiqrn'
        const targetPopup = document.querySelector(`.brx-popup[data-popup-loop="${queryId}"][data-popup-loop-index="7"]`)
        bricksOpenPopup(targetPopup)

    }, 200)

})

می‌توانید تابع JavaScript خود را هنگام باز یا بسته شدن popup از طریق رویدادهای bricks/popup/open یا bricks/popup/close اجرا کنید.

// Listen to open event
document.addEventListener( 'bricks/popup/open', (event) => {
    // You can get the popup id
    const popupId = event.detail.popupId
    // You can get the popup element
    // const popupElement = event.detail.popupElement

    // Do your stuff here
    if (popupId == 3321) {
        console.log(`3321 popup is opened`)
    }
})

// Listen to close event
document.addEventListener( 'bricks/popup/close', (event) => {
    // You can get the popup id
    const popupId = event.detail.popupId
    // You can get the popup element
    // const popupElement = event.detail.popupElement

    // Do your stuff here
    if (popupId == 3321) {
        console.log(`3321 popup is closed`)
    }
})

مثال: Popup داخل query loop

همچنین می‌توانید یک popup را از طریق المان Template داخل یک query loop اضافه کنید. داخل قالب popup، می‌توانید از داده پویا برای نمایش داده‌های آیتم loop استفاده کنید.

تصویر زیر راه‌اندازی یک دکمه «Quick view» را نشان می‌دهد که یک قالب popup با دکمه «Add to cart»، توضیحات کوتاه محصول و غیره نمایش می‌دهد.

همچنین یک تعامل روی دکمه داخل query loop تنظیم کرده‌ایم که قالب popup «Quick view» ما را هنگام کلیک نمایش می‌دهد.

Popup داخل query loop

یادداشت

یادداشت (برای نسخه‌های Bricks قبل از 1.7.1): تعامل را روی div Query Loop خود تنظیم نکنید.

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

Example layout structure to trigger a looping popup for Bricks version < 1.7.1

مثال: نمایش popup هنگام خروج موس از پنجره مرورگر (exit intent)

پس از راه‌اندازی قالب popup و ساخت layout، به «Settings > Template Settings > Popup» بروید، به پایین گروه Interactions اسکرول کنید و تعامل زیر را اضافه کنید:

باز کردن popup با Mouse leave

مثال: افزودن آیکون بستن popup (با استفاده از interactions)

برای ساخت یک آیکون بستن popup که با کلیک روی آن فعال می‌شود، بیایید یک المان Icon به popup خود اضافه کنیم. البته هر المانی هم کار می‌کند.

نکته: هنگام ویرایش المان Icon، استایل «Cursor» را زیر Styles > Layout > Misc روی «pointer» تنظیم کنید. این نشانه بصری بهتری فراهم می‌کند که این آیکون تعاملی است.

پنل Interactions را هنگام ویرایش المان Icon باز کنید، یک تعامل جدید از نوع «Click» بسازید، هدف را روی «Popup» تنظیم کنید، popup را انتخاب کنید و «Action» را روی «Hide element» تنظیم کنید.

تعامل آیکون بستن

اگر قصد دارید از این آیکون بستن popup در جاهای بیشتری استفاده کنید، ساخت یک المان بستن popup سراسری ممکن است ایده خوبی باشد.

پس از ذخیره این المان به‌عنوان یک Global Element، باید از رویکرد متفاوتی برای تنظیم تعامل بستن popup استفاده کنید تا بتواند هر popup را هدف قرار دهد. در این حالت، از «CSS selector» به‌عنوان «Target» استفاده کنید و «CSS selector» را روی «.brx-popup» تنظیم کنید:

تعامل Global close icon

در حالی که template conditions مشخص می‌کنند popup در کدام صفحات ظاهر می‌شود، می‌توانید با تعریف Element Conditions روی بیرونی‌ترین المان popup، آن را بیشتر محدود کنید.

برای نمایش یک popup فقط قبل از ۱ نوامبر ۲۰۲۲، شرط المان زیر را روی بیرونی‌ترین المان layout popup خود تنظیم می‌کنید:

شرایط المان در Popup Builder

اگر این شرط المان برآورده نشود، یعنی ۱ نوامبر ۲۰۲۲ فرا رسد، HTML popup دیگر رندر نمی‌شود. بنابراین حتی اگر popup توسط یک تعامل trigger شود، نمایش نخواهد داشت زیرا HTML popup ای برای نمایش وجود ندارد.

AJAX popup

Bricks در نسخه 1.9.4 AJAX popup ها را معرفی کرد. هدف اصلی کاهش اندازه DOM و query های popup ها هنگامی‌است که داخل query loop استفاده می‌شوند.

فعال‌سازی واکشی محتوا از طریق AJAX برای popup ها

هنگام ویرایش یک قالب popup، فقط گزینه «Fetch content via AJAX» را فعال کنید. همچنین می‌توانید یک انیمیشن AJAX loader تعیین کنید که به‌طور پیش‌فرض داخل .brx-popup-content popup قرار می‌گیرد. به خاطر داشته باشید که برای رندر AJAX، context بسیار مهم است. داده‌های پویا از ردیف‌های repeater (مانند ACF یا Metabox) نمی‌توانند نمایش داده شوند زیرا فاقد ID یکتا مانند post، term یا user هستند.

کنترل‌های AJAX popup در قالب popup

تنظیمات context تعامل popup جدید

کنترل‌های context در رابط Interactions

این تنظیمات جدید در پنل «Interactions» یافت می‌شوند اگر تعامل شما برای نمایش یک popup تنظیم شده باشد.

به‌طور پیش‌فرض، Bricks هنگام باز کردن AJAX popup از طریق تعامل، به‌طور خودکار context یا object جاری را شناسایی می‌کند. این بدون توجه به اینکه داخل query loop هستید یا نه کار می‌کند و انواع مختلف object مانند post، term یا user را پوشش می‌دهد.

چرا این تنظیمات context لازم هستند؟

در نظر بگیرید یک popup quick view محصول با تمام داده‌های پویا مربوطه در قالب popup می‌سازید. هنگام واکشی این قالب از طریق AJAX، بسیار مهم است که به Bricks درباره محصول جاری (context) اطلاع دهید. این اطمینان می‌دهد که تمام داده‌های پویا به‌درستی پر می‌شوند. ارائه نوع و ID context نادرست در حین واکشی می‌تواند منجر به داده‌های پویای خالی یا نادرست شود. به خاطر داشته باشید که نه همه داده‌های حلقه‌ای می‌توانند context در یک AJAX popup باشند. برای مثال، نمی‌توانید به Bricks بگویید که context فعلی شما یک ردیف repeater در ردیف N از فیلد repeater است.

چه زمانی باید نوع و ID context را مشخص کنید؟

در مواردی که داخل یک query loop هستید، به‌ویژه یک query loop تو در تو یا یک حلقه repeater فیلد سفارشی، Bricks ممکن است context صحیح را به‌طور خودکار تشخیص ندهد. در چنین مواردی، باید نوع Context (post، term یا user) و ID Context (post ID، Term ID یا User ID) را مشخص کنید. می‌توانید از داده‌های پویا مانند {post_id}، {term_id}، {mb_related_agent:value} و غیره برای تنظیم این مقادیر استفاده کنید.

راه‌اندازی quick view محصول WooCommerce

A looping product quick view popup structure in Bricks

رویدادهای JavaScript AJAX popup (از نسخه 1.9.4)

رویدادهای JavaScript جدید مرتبط با AJAX Popup اضافه شدند:

  • bricks/ajax/popup/start - قبل از انجام یک فراخوانی AJAX popup اجرا می‌شود.
  • bricks/ajax/popup/end - پس از تکمیل یک فراخوانی AJAX popup اجرا می‌شود.
  • bricks/ajax/popup/loaded - پس از افزودن محتوای AJAX popup به DOM اجرا می‌شود.

می‌توانید popupId یا popupElement را با دسترسی به event.details.popupId یا event.details.popupElement بازیابی کنید.

// Listen to AJAX popup content loaded event
document.addEventListener( 'bricks/ajax/popup/loaded', (event) => {
    // You can get the popup id
    const popupId = event.detail.popupId
    // You can get the popup element
    // const popupElement = event.detail.popupElement

    // Do your stuff here
    if (popupId == 3321) {
      console.log(`3321 AJAX popup content DOM loaded. Init my custom element JS`)
    }
})

مثال: باز کردن یک AJAX popup با context در JavaScript (از نسخه 1.9.4)

از نسخه 1.9.4، تابع bricksOpenPopup سه پارامتر می‌پذیرد:

  • object - یا شیء المان popup یا ID popup
  • timeout - این پارامتر برای انیمیشن شمارنده داخل popup است (در صورت عدم نیاز می‌توان نادیده گرفت).
  • additionalParams - به‌طور خاص برای AJAX popup ها استفاده می‌شود. ویژگی‌هایی مانند popupContextId و popupContextType انتظار دارد.
// To open the popup with ID 1190 (already set to fetch content via AJAX) with a context of post ID 668
bricksOpenPopup(
  1190,
  0,
  {
    popupContextId: 668,
    popupContextType: 'post'
  }
);


// To open the popup with ID 2350 (already set to fetch content via AJAX) with a context of term ID 39:
bricksOpenPopup(
  2350,
  0,
  {
    popupContextId: 39,
    popupContextType: 'term'
  }
);