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

تعاملات (Interactions)

تعاملات (Interactions) که از Bricks 1.6 در دسترس هستند، به شما اجازه می‌دهند رویدادهای کاربر یا مرورگر (مثلاً کلیک، hover موس، بارگذاری محتوا و غیره) را به اکشن‌های خاص مانند نمایش/مخفی‌کردن المان یا popup، افزودن/حذف/toggle کلاس‌های CSS یا ویژگی‌های HTML، شروع انیمیشن‌ها، بارگذاری نتایج بیشتر query loop و غیره متصل کنید.

یادداشت

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

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

دسترسی به تعاملات

هنگام ویرایش یک المان، روی آیکون «Interactions» (toggle) در header پنل کلیک کنید تا رابط تعاملات المان را باز/ببندید.

آیکون toggle Interactions

اگر المانی تعاملات داشته باشد، آیکون «Interactions» toggle را در structure panel هم خواهید دید. روی آیکون کلیک کنید تا رابط تعاملات این المان باز شود.

افزودن تعاملات

برای افزودن یک تعامل به یک المان، روی آیکون «+» کنار عنوان «Interactions» کلیک کنید. می‌توانید به هر تعداد تعامل که بخواهید به یک المان اضافه کنید. با کلیک روی عنوان یک تعامل خاص، می‌توانید آن را تغییر نام دهید.

افزودن interaction

هر تعامل با یک trigger، target و action تعریف می‌شود.

اولین interaction

Trigger تعامل

Trigger رویدادی است که این تعامل را شروع می‌کند. رویداد می‌تواند به خود المان متصل باشد (کلیک، hover موس، focus، blur، ورود موس، خروج موس، ورود به/خروج از viewport) یا به پنجره مرورگر (اسکرول، بارگذاری محتوا، خروج موس از پنجره). Trigger های موجود به شرح زیر هستند:

Action تعامل

Action منطقی است که هنگام trigger شدن رویداد اجرا می‌شود. اینجا اکشن‌های موجود در Bricks هستند:

Target المانی در صفحه است که اکشن روی آن تأثیر می‌گذارد. target می‌تواند خود المان (پیش‌فرض)، یک CSS selector، یا یک Popup باشد.

به‌طور پیش‌فرض، تعامل هر بار که رویداد اتفاق می‌افتد اجرا می‌شود (مثلاً با هر کلیک روی المان). اگر می‌خواهید تعامل فقط یک بار در هر بارگذاری صفحه اتفاق بیفتد، تیک «Run only once» را فعال کنید.

اکشن: Scroll To

اسکرول خودکار به یک المان خاص را هنگام وقوع رویدادهای خاص در صفحه راه‌اندازی کنید. همچنین می‌توانید با استفاده از تنظیمات «Scroll to: Offset (px)» و «Scroll to: Delay (ms)» رفتار را دقیق‌تر تنظیم کنید.

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

اکشن Scroll to

در این سناریو، پس از پایان فراخوانی AJAX «Posts Query»، صفحه به‌آرامی‌به المانی با CSS selector #my-grid-wrapper اسکرول می‌کند و 500 میلی‌ثانیه قبل از شروع اسکرول صبر می‌کند.

اکشن: Toggle Offcanvas

از نسخه 1.11، یک اکشن جدید به شما اجازه می‌دهد المان Offcanvas را از هر المانی toggle کنید. قبلاً فقط المان Toggle می‌توانست با Offcanvas تعامل داشته باشد. لطفاً توجه داشته باشید که این اکشن را مستقیماً روی خود المان Toggle اعمال نکنید.

اکشن Toggle offcanvas

اکشن: JavaScript (Function)

با انتشار Bricks 1.9.5، می‌توانید توابع JavaScript خود را مستقیماً از پنل Interactions اجرا کنید.

یادداشت

فقط توابع JavaScript که در scope global هستند می‌توانند اجرا شوند.

برای نشان دادن این موضوع، چند مثال از توابع JavaScript سفارشی را بررسی می‌کنیم:

<script>
window.myHelperFunctions = {}

myHelperFunctions.myCall = () => {
  console.log('myCall executed')
}

myHelperFunctions.nestedFn = {
  fn1: () => {
    console.log('fn1 executed')
  },
  fn2: () => {
    console.log('fn2 executed')
  }
}

// toggleMiniCart is a global scope function
function toggleMiniCart() {
  // run() is not a global scope function
  const run = () => {
    document.querySelector('.bricks-woo-toggle').dispatchEvent( new Event('click') )
  }
  setTimeout( run, 100 )
}
</script>

برای اجرای توابع بالا، فقط نام تابع را در فیلد Function name (JavaScript) وارد کنید. بدون پرانتز یا شیء window!

  • برای اجرای myHelperFunctions.myCall(): myHelperFunctions.myCall
  • برای اجرای myHelperFunctions.nestedFn.fn1(): myHelperFunctions.nestedFn.fn1
  • برای اجرای myHelperFunctions.nestedFn.fn2(): myHelperFunctions.nestedFn.fn2
  • برای اجرای toggleMiniCart(): toggleMiniCart
  • نمی‌توانید run() داخل toggleMiniCart را اجرا کنید زیرا یک تابع در scope global نیست

مهم

مهم: اگر چندین المان را از طریق «CSS Selector» هدف قرار می‌دهید، Bricks روی هر المان target تکرار می‌کند و تابع مرتبط را اجرا می‌کند.

آرگومان‌های تابع JavaScript

می‌توانید چندگانگی توابع JavaScript سفارشی خود را با ارسال آرگومان‌ها مستقیماً به آن‌ها بیشتر کنید. این از طریق استفاده از کنترل repeater Arguments ممکن است. به یاد داشته باشید ترتیب آرگومان‌های خود را رعایت کنید تا از بروز خطاهای JavaScript جلوگیری کنید.

placeholder %brx% به‌عنوان آرگومانی برای توابع سفارشی شما عمل می‌کند. با تنظیم %brx% به‌عنوان مقدار آرگومان، به اطلاعات ارزشمندی مرتبط با تعامل دسترسی پیدا می‌کنید:

  • param.source (المان منبع): node المان منبع تعامل، المانی است که تعامل را در ابتدا trigger کرده است.
  • param.targets (المان‌های target): آرایه‌ای از node های المان‌های target بر اساس تنظیم target شما.
  • param.target (المان target): node المان target.

اینجا یک مثال برای بازیابی آن اطلاعات در یک تابع آمده است:

تابع JavaScript با arguments

// Play or pause a video element
// Click interaction that runs this custom JavaScript function
function playOrPauseVideo( brxParam, postId ) {
  const target = brxParam?.target || false
  // You can access targets (array) and the source element too
  // const targets = brxParam?.targets || false
  // const source = brxParam?.source || false

  if ( target ) {
    // Find the first video tag from my target node
    const video = target.querySelector('video')
    if ( video && video.play && video.pause ) {
      // Pause or Play
      if ( !video.paused ){
        video.pause()
      } else {
        video.play()
      }
    }
  }
}

شرایط تعامل

شرایط تعامل یک ویژگی اختیاری و پیشرفته‌تر هستند. این ویژگی به شما اجازه می‌دهد یک تعامل را فقط در صورتی اجرا کنید که شرایط خاصی مرتبط با browser storage (window، sessionStorage، localStorage) برآورده شده باشند.

می‌توانید «Interaction conditions» را هنگام ویرایش یک تعامل به این شکل تنظیم کنید:

شرایط interaction

مثال تعامل بالا زمانی برآورده می‌شود که مقدار window.some_key برابر با some_value باشد.

تنظیم «Relation» به شما اجازه می‌دهد مشخص کنید آیا یک (OR) یا همه (AND) شرایط تعامل باید برآورده شوند تا تعامل اجرا شود.

مثال: باز کردن popup خبرنامه با کلیک

در این مثال، می‌خواهیم یک دکمه «subscribe newsletter» به footer سایت اضافه کنیم. یک کلیک روی این دکمه باید یک popup که شامل فرم ثبت‌نام خبرنامه ماست را باز کند.

برای ساخت modal/popup، ابتدا باید یک قالب popup بسازیم. بیایید آن را «Newsletter popup» بنامیم.

مطمئن شوید template conditions popup خبرنامه را روی «Entire website» تنظیم کنید.

در قالب footer خود، یک دکمه اضافه کنید و تعامل زیر را تنظیم کنید:

مثال click interaction

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

مثال: نمایش tooltip سفارشی با hover

بیایید یک tooltip سفارشی کنار یک المان متن بسازیم. مثال زیر از یک المان «Basic Text» و یک «Icon» استفاده می‌کند:

tooltip مرحله ۱

برای نمایش یک tooltip سفارشی کنار آیکون «?»، یک المان مخفی (مثلاً Div + Text) خواهیم داشت که Div دارای کلاس سفارشی .my-tooltip است و هنگامی‌که موس روی آیکون است نمایش داده می‌شود.

برای این کار، باید دو تعامل روی المان Icon ایجاد کنیم. یکی برای نمایش tooltip و دیگری برای مخفی‌کردن آن:

tooltip interactions

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

tooltip نهایی

مثال: ساخت یک دکمه toggle (مثلاً آیکون باز/بسته accordion nestable)

می‌توانیم یک دکمه toggle مانند toggle منوی موبایل با استفاده از element interactions بسازیم.

open-close toggle

ایده در این مثال این است که دو المان Icon داخل یک Div اضافه کنیم.

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

همچنین CSS سفارشی و کلاس‌های سفارشی به Div و آیکون‌ها اضافه می‌کنیم. Div باید کلاس سفارشی .toggle-button با CSS سفارشی زیر داشته باشد:

%root% .toggle-close-icon {
  display: none;
}

%root%.is-open .toggle-open-icon {
  display: none;
}

%root%.is-open .toggle-close-icon {
  display: block;
}

آیکون پیش‌فرض باید کلاس .toggle-open-icon و آیکون فعال کلاس .toggle-close-icon داشته باشد.

در نهایت، باید element interactions را تنظیم کنیم.

ایده این است که کلاس .is-open را روی Div اضافه و حذف کنیم. بنابراین وقتی روی آیکون پیش‌فرض کلیک می‌کنیم، کلاس .is-open اضافه می‌شود و وقتی روی آیکون فعال کلیک می‌کنیم، کلاس .is-open حذف می‌شود.

برای اینکه این اتفاق در آیکون پیش‌فرض بیفتد، تعامل زیر را تنظیم می‌کنیم:

interaction آیکون پیش‌فرض

روی آیکون فعال تعامل معکوس را تنظیم می‌کنیم:

interaction آیکون فعال

انیمیشن‌ها

می‌توانید المان‌ها را در Bricks از طریق Interactions انیمیت کنید.

Bricks از کتابخانه محبوب Animate.css برای ارائه انیمیشن‌های مختلف CSS خالص استفاده می‌کند.

اکشن: شروع انیمیشن

افزودن تعامل زیر به یک المان، انیمیشن «jello» را هنگام کلیک روی المان اجرا می‌کند.

شروع انیمیشن jello

Trigger: پایان انیمیشن

یک بهبود قابل توجه معرفی‌شده در Bricks نسخه 1.8.4 قابلیت انجام اکشن‌ها هنگام پایان یافتن مجموعه‌ای از انیمیشن‌هاست. این امکانات جدیدی برای ساخت زنجیره‌های بی‌درنگ از انیمیشن‌ها یا تعاملات ایجاد می‌کند.

Trigger پایان انیمیشن

فیلد Target Interaction ID به شما اجازه می‌دهد یک Interaction خاص با اکشن «Start animation» را برای گوش دادن مشخص کنید.

اگر Interaction مشخص‌شده اکشن «Start animation» نداشته باشد یا تنظیم نشده باشد، این تنظیم interaction نادیده گرفته می‌شود و trigger نخواهد شد.

برای گوش دادن به هر Interaction قبلی داخل همان گروه Interaction (چه روی سطح المان تنظیم شده باشد چه روی سطح class)، می‌توانید فیلد را خالی بگذارید.

اگر می‌خواهید یک Interaction را در گروه interaction متفاوتی هدف قرار دهید، باید فیلد Target Interaction ID را بر اساس آن پر کنید.

نحوه کار Target Interaction ID

در مثال بالا، تعامل uzfgcm اکشن خود را پس از پایان انیمیشن xyyyeh اجرا خواهد کرد.

یادداشت

از استفاده از ID تعامل فعلی به‌عنوان Target Interaction ID خودداری کنید. Bricks این تنظیم را نادیده می‌گیرد تا از حلقه‌های interaction بی‌نهایت احتمالی که می‌توانند حافظه مرورگر را بیش از حد مصرف کنند جلوگیری شود.

همچنین می‌توانید به این رویداد گوش دهید تا منطق JavaScript پیچیده‌تری اجرا کنید.

// Listen to animation xyyyeh
document.addEventListener( 'bricks/animation/end/xyyyeh', (event) => {
  // Get the element from the event
  const element = event.detail.el || false

  // Do your magic here
})

Popup ها در Bricks رفتار خاصی در مورد انیمیشن‌ها دارند.

برای باز یا بستن خودکار یک Popup پس از پایان انیمیشن، فقط باید اکشن «Start animation» را با هر انیمیشن In یا Out تعریف کنید. این نیاز به ایجاد یک Interaction جداگانه برای بستن یا باز کردن Popup بر اساس trigger پایان انیمیشن را از بین می‌برد.

توجه ویژه popup

Trigger: Query AJAX loader (شروع/پایان)

یک افزوده عالی معرفی‌شده در Bricks 1.9. این دو trigger جدید برای کاربران پیشرفته جهت ساخت AJAX loader سفارشی هستند، در صورتی که AJAX loader بومی‌داخل تنظیم Query loop نتواند نیازهای طراحی آن‌ها را برآورده کند. این به اجرای اکشن‌ها هنگام آغاز یا پایان یافتن AJAX در Bricks کمک می‌کند.

یادداشت

Bricks AJAX = Infinite Scroll، Load More، AJAX pagination یا Query Filter

مثال: اعمال opacity 0.5 به یک query div هنگام شروع AJAX و برگشت هنگام پایان AJAX
  1. یک layout grid برای query loop خود بسازید، سپس یک کلاس سفارشی با opacity 0.5 برای grid تنظیم کنید.
  2. یک تعامل به grid خود اضافه کنید تا بتوانیم این کلاس را هنگام شروع و پایان AJAX اضافه و حذف کنیم.

CSS سفارشی برای AJAX loader trigger

Interactions برای AJAX loader trigger

می‌توانید تابع JavaScript سفارشی خود را هنگام شروع یا پایان Bricks AJAX از طریق رویدادهای bricks/ajax/start یا bricks/ajax/end اجرا کنید. (از نسخه 1.9)

document.addEventListener('bricks/ajax/start', (event) => {
  // Get the queryId from the event
  const queryId = event.detail.queryId || false

  if (!queryId) {
    return
  }

  // Do your magic here
})

فرم

Bricks نسخه 1.9.2 مجموعه‌ای از قابلیت‌های جدید هیجان‌انگیز معرفی می‌کند که توانایی شما را برای سفارشی‌سازی تعاملات به‌صورت خلاقانه افزایش می‌دهند. در این نسخه، سه trigger تعامل جدید و رویدادهای JavaScript مربوطه برای توانمندسازی شما در ساخت تجربه‌های کاربری پویا معرفی شده‌اند.

Triggerهای جدید فرم

New triggers: Form Submit, Form Success, Form Error

Trigger: Form Submit (ارسال فرم)

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

مثال JavaScript:

document.addEventListener( 'bricks/form/submit', function ( event ) {
  // Access the element ID
  const elementId = event.detail.elementId;

  // Access the form data
  const formData = event.detail.formData;

  // Perform actions using elementId and formData
  console.log('Element ID:', elementId);
  console.log('Form Data:', formData);

  // You can now work with the elementId and formData in your event handler
});

Trigger: Form Success (موفقیت فرم)

هنگامی‌اتفاق می‌افتد که ارسال فرم موفقیت‌آمیز بود.

مثال JavaScript:

document.addEventListener( 'bricks/form/success', function ( event ) {
  // Access the element ID
  const elementId = event.detail.elementId;

  // Access the form data
  const formData = event.detail.formData;

  // Access the raw response from AJAX
  const res = event.detail.res;

  // Do your magic here

});

Trigger: Form Error (خطای فرم)

هنگامی trigger می‌شود که ارسال فرم موفقیت‌آمیز نبود. از این trigger برای مدیریت سناریوهای خطا استفاده کنید.

مثال JavaScript:

document.addEventListener( 'bricks/form/error', function ( event ) {
  // Access the element ID
  const elementId = event.detail.elementId;

  // Access the form data
  const formData = event.detail.formData;

  // Access the raw response from AJAX
  const res = event.detail.res;

  // Do your magic here

});

Trigger: Filter: Empty / Not Empty (فیلتر: خالی / غیرخالی)

معرفی‌شده در نسخه 1.11، این دو trigger تعامل جدید هنگامی‌در دسترس هستند که ویژگی Query Filters فعال باشد.

Triggerهای filter empty/not empty

این trigger ها به شما اجازه می‌دهند المان‌ها را بر اساس اینکه آیا گزینه‌ها یا مقادیر فیلتر مرتبط با شرایط مشخص‌شده مطابقت دارند نمایش یا مخفی کنید. این به‌ویژه هنگامی‌مفید است که گزینه «Hide empty» را برای المان‌های فیلتر فعال می‌کنید.

Filter: Empty هنگامی trigger می‌شود که:

  • Active filters، Checkbox، Radio، Select - هیچ گزینه‌ای در دسترس نیست.
  • Datepicker، Range، Search - مقدار فعلی خالی است.

Filter: Not Empty هنگامی trigger می‌شود که:

  • Active filters، Checkbox، Radio، Select - گزینه‌هایی در دسترس است.
  • Datepicker، Range، Search - مقدار فعلی خالی نیست.

یادداشت

این trigger ها باید با هم برای toggle visibility پویا استفاده شوند. استفاده از فقط یکی ممکن است مشکلاتی ایجاد کند، مثلاً المان target پس از اولین اکشن فیلتر پنهان شود اما در اکشن‌های بعدی دوباره ظاهر نشود، مگر اینکه یک نیاز یا برنامه خاصی داشته باشید.

مثال filter empty/not empty

مثال: اگر Filter - Select هیچ گزینه‌ای بر نگرداند، block wrapper را پنهان کنید تا از نمایش خالی ناخوشایند جلوگیری شود. در غیر این صورت، block قابل مشاهده می‌ماند. این رفتار پویا است و از طریق JavaScript مدیریت می‌شود.