#זרימת אירועים

#מבוא

אם ברצונכם להפעיל פעולות מותאמות אישית כאשר טופס מסוים משתנה, תוכלו להשתמש בזרימת אירועים (Event flow) כדי להשיג זאת. בנוסף לטפסים, גם דפים, בלוקים, כפתורים ושדות יכולים להשתמש בזרימת אירועים כדי להגדיר פעולות מותאמות אישית.

#איך משתמשים

להלן דוגמה פשוטה להמחשת אופן הגדרת זרימת אירועים. נממש קישור בין שתי טבלאות: בעת לחיצה על שורה מסוימת בטבלה השמאלית, הנתונים בטבלה הימנית יסוננו אוטומטית.

שלבי ההגדרה הם כדלקמן:

1. לחצו על סמל ה"ברק" בפינה הימנית העליונה של בלוק הטבלה השמאלי כדי לפתוח את ממשק הגדרת זרימת האירועים.
2. לחצו על "הוסף זרימת אירועים (Add event flow)", ובחרו ב"לחיצה על שורה (Row click)" כ"אירוע מפעיל (Trigger event)", המציין שהזרימה תופעל בעת לחיצה על שורת טבלה.
3. הגדירו את "תזמון הביצוע (Execution timing)", המשמש לשליטה בסדר של זרימת אירועים זו ביחס לתהליכים המובנים במערכת. בדרך כלל ניתן להשאיר את ברירת המחדל; אם ברצונכם להציג הודעה או לבצע ניווט לאחר סיום הלוגיקה המובנית, ניתן לבחור ב"לאחר כל הזרימות (After all flows)". לפרטים נוספים ראו להלן תזמון ביצוע.
4. "תנאי הפעלה (Trigger condition)" משמש להגדרת תנאים; זרימת האירועים תופעל רק כאשר התנאים מתקיימים. כאן אין צורך להגדיר תנאים, שכן אנו רוצים שהזרימה תופעל בכל לחיצה על שורה.
5. רחפו עם העכבר מעל "הוסף שלב (Add step)" כדי להוסיף שלבי פעולה. נבחר ב"הגדר טווח נתונים (Set data scope)" כדי להגדיר את טווח הנתונים של הטבלה הימנית.
6. העתיקו את ה-UID של הטבלה הימנית והזינו אותו בתיבת הקלט "UID של בלוק יעד (Target block UID)". מיד לאחר מכן יופיע ממשק הגדרת תנאים, שבו ניתן להגדיר את טווח הנתונים של הטבלה הימנית.
7. בואו נגדיר תנאי, כפי שמוצג באיור להלן:
8. לאחר הגדרת טווח הנתונים, יש לרענן את הבלוק כדי להציג את התוצאות המסוננות. כעת נגדיר את רענון בלוק הטבלה הימני. הוסיפו שלב "רענן בלוקי יעד (Refresh target blocks)" והזינו את ה-UID של הטבלה הימנית.
9. לבסוף, לחצו על כפתור השמירה בפינה הימנית התחתונה, וההגדרה הושלמה.

#פירוט אירועים

#לפני רינדור (Before render)

אירוע כללי הניתן לשימוש בדפים, בלוקים, כפתורים או שדות. באירוע זה ניתן לבצע פעולות אתחול. לדוגמה, הגדרת טווחי נתונים שונים תחת תנאים שונים.

#לחיצה על שורה (Row click)

אירוע ייחודי לבלוקי טבלה. מופעל בעת לחיצה על שורת טבלה. בעת ההפעלה, יתווסף להקשר (Context) אובייקט "Clicked row record", שבו ניתן להשתמש כמשתנה בתנאים ובשלבים.

#שינוי ערכי טופס (Form values change)

אירוע ייחודי לבלוקי טופס. מופעל כאשר ערך של שדה בטופס משתנה. ניתן לקבל את ערכי הטופס דרך המשתנה "Current form" בתנאים ובשלבים.

#לחיצה (Click)

אירוע ייחודי לכפתורים. מופעל בעת לחיצה על הכפתור.

#תזמון ביצוע

בהגדרת זרימת אירועים, ישנם שני מושגים שקל להתבלבל ביניהם:

• אירוע מפעיל (Trigger event): מתי להתחיל בביצוע (למשל: לפני רינדור, לחיצה על שורה, לחיצה, שינוי ערכי טופס וכו').
• תזמון ביצוע (Execution timing): לאחר התרחשות אירוע מפעיל מסוים, היכן זרימת האירועים המותאמת אישית שלכם תוכנס ביחס לתהליך המובנה של המערכת.

#מהו "תהליך מובנה / שלב מובנה"?

דפים, בלוקים או פעולות רבות כוללים סט מובנה של תהליכי טיפול במערכת (למשל: שליחה, פתיחת חלון קופץ, בקשת נתונים וכו'). כאשר אתם מוסיפים זרימת אירועים מותאמת אישית לאותו אירוע (למשל "לחיצה"), "תזמון הביצוע" קובע:

• האם לבצע קודם את זרימת האירועים שלכם או את הלוגיקה המובנית;
• או להכניס את זרימת האירועים שלכם לפני או אחרי שלב מסוים בתהליך המובנה.

#כיצד להבין את אפשרויות תזמון הביצוע בממשק?

• לפני כל הזרימות (Before all flows - ברירת מחדל): מבוצע ראשון. מתאים לביצוע "חסימה/הכנה" (כגון אימות, אישור כפול, אתחול משתנים וכו').
• לאחר כל הזרימות (After all flows): מבוצע לאחר סיום הלוגיקה המובנית. מתאים לביצוע "סיום/משוב" (כגון הודעות חיווי, רענון בלוקים אחרים, ניווט דפים וכו').
• לפני זרימה מסוימת / לאחר זרימה מסוימת: נקודת הכנסה מדויקת יותר. לאחר הבחירה, יש לבחור את ה"תהליך המובנה" הספציפי.
• לפני שלב בזרימה מסוימת / לאחר שלב בזרימה מסוימת: נקודת הכנסה המדויקת ביותר. לאחר הבחירה, יש לבחור הן את ה"תהליך המובנה" והן את ה"שלב המובנה" הספציפי.

רמז: אם אינכם בטוחים באיזה תהליך/שלב מובנה לבחור, העדיפו להשתמש בשתי האפשרויות הראשונות ("לפני / אחרי כל הזרימות").

#פירוט שלבים

#משתנה מותאם אישית (Custom variable)

משמש להגדרת משתנה מותאם אישית לשימוש בהקשר.

#טווח השפעה (Scope)

למשתנים מותאמים אישית יש טווח השפעה; למשל, משתנה שהוגדר בזרימת אירועים של בלוק ניתן לשימוש רק באותו בלוק. אם ברצונכם להשתמש בו בכל הבלוקים בדף הנוכחי, יש להגדירו בזרימת האירועים של הדף.

#משתנה טופס (Form variable)

שימוש בערך של בלוק טופס מסוים כמשתנה. ההגדרה היא כדלקמן:

• Variable title: כותרת המשתנה
• Variable identifier: מזהה המשתנה
• Form UID: ה-UID של הטופס

#משתנים אחרים

תמיכה במשתנים נוספים תתווסף בהמשך, אנא המתינו לעדכונים.

#הגדר טווח נתונים (Set data scope)

הגדרת טווח הנתונים של בלוק היעד. ההגדרה היא כדלקמן:

• Target block UID: ה-UID של בלוק היעד
• Condition: תנאי סינון

#רענן בלוקי יעד (Refresh target blocks)

רענון בלוקי יעד, מאפשר הגדרת מספר בלוקים. ההגדרה היא כדלקמן:

• Target block UID: ה-UID של בלוק היעד

#ניווט לכתובת URL (Navigate to URL)

מעבר לכתובת URL מסוימת. ההגדרה היא כדלקמן:

• URL: כתובת היעד, תומך בשימוש במשתנים
• Search parameters: פרמטרי שאילתה ב-URL
• Open in new window: אם מסומן, יפתח דף דפדפן חדש בעת המעבר

#הצג הודעה (Show message)

הצגת מידע משוב על פעולות באופן גלובלי.

#מתי להשתמש

• ניתן לספק מידע משוב כגון הצלחה, אזהרה ושגיאה.
• ההודעה מוצגת במרכז החלק העליון ונעלמת אוטומטית; זוהי דרך קלה למתן התראות מבלי להפריע לפעולת המשתמש.

#הגדרה ספציפית

• Message type: סוג ההודעה
• Message content: תוכן ההודעה
• Duration: משך התצוגה בשניות

#הצג התראה (Show notification)

הצגת מידע התראה גלובלי.

#מתי להשתמש

הצגת התראות בארבע פינות המערכת. משמש לעיתים קרובות במקרים הבאים:

• תוכן התראה מורכב יחסית.
• התראות עם אינטראקציה, המציעות למשתמש נקודות פעולה להמשך.
• דחיפת מידע יזומה על ידי המערכת.

#הגדרה ספציפית

• Notification type: סוג ההתראה
• Notification title: כותרת ההתראה
• Notification description: תיאור ההתראה
• Placement: מיקום, האפשרויות הן: למעלה משמאל, למעלה מימין, למטה משמאל, למטה מימין

#הפעל JavaScript (Execute JavaScript)

ביצוע קוד JavaScript.

#דוגמה

#טופס: קריאה ל-API של צד שלישי ומילוי שדות

תרחיש: הפעלת זרימת אירועים בטופס, שליחת בקשה ל-API של צד שלישי, וקבלת נתונים למילוי אוטומטי של שדות הטופס.

שלבי הגדרה:

1. פתחו את הגדרות זרימת האירועים בבלוק הטופס והוסיפו זרימת אירועים חדשה;
2. בחרו ב"לפני רינדור (Before render)" כאירוע המפעיל;
3. בחרו ב"לאחר כל הזרימות (After all flows)" כתזמון הביצוע;
4. הוסיפו שלב "הפעל JavaScript (Execute JavaScript)", הדביקו ושנו את הקוד הבא לפי הצורך:

const res = await ctx.api.request({
  method: 'get',
  url: 'https://jsonplaceholder.typicode.com/users/2',
  skipNotify: true,
  // Note: ctx.api will include the current NocoBase authentication/custom headers by default
  // Here we override it with an "empty Authorization" to avoid sending the token to a third party
  headers: {
    Authorization: 'Bearer ',
  },
});

const username = res?.data?.username;

// replace it with actual field name
ctx.form.setFieldsValue({ username });