#โฟลว์เหตุการณ์

#บทนำ

หากคุณต้องการทริกเกอร์การดำเนินการที่กำหนดเองเมื่อมีการเปลี่ยนแปลงในฟอร์ม คุณสามารถใช้โฟลว์เหตุการณ์เพื่อทำให้สำเร็จได้ครับ/ค่ะ นอกจากฟอร์มแล้ว หน้าเพจ, บล็อก, ปุ่ม และฟิลด์ต่างๆ ก็สามารถใช้โฟลว์เหตุการณ์เพื่อกำหนดค่าการดำเนินการที่กำหนดเองได้เช่นกันครับ/ค่ะ

#วิธีใช้งาน

ด้านล่างนี้คือตัวอย่างง่ายๆ เพื่ออธิบายวิธีการตั้งค่าโฟลว์เหตุการณ์ครับ/ค่ะ เราจะมาสร้างการเชื่อมโยงระหว่างสองตาราง โดยเมื่อคลิกที่แถวใดแถวหนึ่งในตารางด้านซ้าย ระบบจะทำการกรองข้อมูลในตารางด้านขวาโดยอัตโนมัติครับ/ค่ะ

ขั้นตอนการตั้งค่ามีดังนี้ครับ/ค่ะ:

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)

เป็นเหตุการณ์ทั่วไปที่สามารถใช้ได้ในหน้าเพจ, บล็อก, ปุ่ม หรือฟิลด์ ในเหตุการณ์นี้สามารถใช้ทำงานเริ่มต้น (initialization) ได้ เช่น การกำหนดขอบเขตข้อมูลที่แตกต่างกันภายใต้เงื่อนไขที่ต่างกันครับ/ค่ะ

#คลิกแถว (Row click)

เหตุการณ์เฉพาะสำหรับบล็อกตาราง จะทำงานเมื่อมีการคลิกแถวในตาราง เมื่อทริกเกอร์แล้วจะมีการเพิ่ม Clicked row record เข้าไปในบริบท (context) ซึ่งสามารถนำไปใช้เป็นตัวแปรในเงื่อนไขและขั้นตอนต่างๆ ได้ครับ/ค่ะ

#ค่าฟอร์มเปลี่ยนแปลง (Form values change)

เหตุการณ์เฉพาะสำหรับบล็อกฟอร์ม จะทำงานเมื่อค่าในฟิลด์ของฟอร์มมีการเปลี่ยนแปลง สามารถรับค่าของฟอร์มผ่านตัวแปร "Current form" ในเงื่อนไขและขั้นตอนต่างๆ ได้ครับ/ค่ะ

#คลิก (Click)

เหตุการณ์เฉพาะสำหรับปุ่ม จะทำงานเมื่อมีการคลิกปุ่มครับ/ค่ะ

#จังหวะการดำเนินการ

ในการตั้งค่าโฟลว์เหตุการณ์ มีสองแนวคิดที่อาจสับสนได้ง่ายครับ/ค่ะ:

• ทริกเกอร์เหตุการณ์ (Trigger event): จะเริ่มทำงานเมื่อไหร่ (เช่น: ก่อนเรนเดอร์, คลิกแถว, คลิก, ค่าฟอร์มเปลี่ยนแปลง เป็นต้น)
• จังหวะการดำเนินการ (Execution timing): หลังจากเกิดทริกเกอร์เหตุการณ์เดียวกัน โฟลว์เหตุการณ์ที่กำหนดเอง ของคุณจะถูกแทรกเข้าไปทำงานในตำแหน่งใดของ ขั้นตอนภายใน (Built-in flow) ครับ/ค่ะ

#"ขั้นตอนภายใน / สเต็ปภายใน" คืออะไร?

หน้าเพจ, บล็อก หรือการดำเนินการหลายอย่างมีขั้นตอนการประมวลผลที่ระบบกำหนดไว้ภายในอยู่แล้ว (เช่น: การส่งข้อมูล, การเปิดหน้าต่าง Pop-up, การดึงข้อมูล เป็นต้น) เมื่อคุณเพิ่มโฟลว์เหตุการณ์ที่กำหนดเองสำหรับเหตุการณ์เดียวกัน (เช่น "คลิก") "จังหวะการดำเนินการ" จะใช้เพื่อตัดสินใจว่า:

• จะเริ่มทำงานก่อนขั้นตอนภายใน หรือหลังขั้นตอนภายใน
• หรือจะแทรกโฟลว์ของคุณเข้าไปก่อนหรือหลังขั้นตอนย่อยเฉพาะเจาะจงภายในขั้นตอนภายในนั้นครับ/ค่ะ

#ตัวเลือกจังหวะการดำเนินการใน UI เข้าใจอย่างไร?

• ก่อนโฟลว์ทั้งหมด (ค่าเริ่มต้น): ทำงานเป็นอันดับแรก เหมาะสำหรับการ "สกัดกั้น/เตรียมการ" (เช่น การตรวจสอบความถูกต้อง, การยืนยันซ้ำ, การกำหนดค่าตัวแปรเริ่มต้น เป็นต้น)
• หลังโฟลว์ทั้งหมด: ทำงานหลังจากขั้นตอนภายในเสร็จสิ้นแล้ว เหมาะสำหรับการ "ปิดท้าย/ตอบสนอง" (เช่น ข้อความแจ้งเตือน, การรีเฟรชบล็อกอื่น, การเปลี่ยนหน้าเพจ เป็นต้น)
• ก่อนโฟลว์ที่ระบุ / หลังโฟลว์ที่ระบุ: จุดแทรกที่ละเอียดขึ้น เมื่อเลือกแล้วจำเป็นต้องเลือก "ขั้นตอนภายใน" ที่เฉพาะเจาะจงครับ/ค่ะ
• ก่อนสเต็ปของโฟลว์ที่ระบุ / หลังสเต็ปของโฟลว์ที่ระบุ: จุดแทรกที่ละเอียดที่สุด เมื่อเลือกแล้วจำเป็นต้องเลือกทั้ง "ขั้นตอนภายใน" และ "สเต็ปภายใน" ครับ/ค่ะ

คำแนะนำ: หากคุณไม่แน่ใจว่าควรเลือกขั้นตอน/สเต็ปภายในใด ให้เลือกใช้สองตัวเลือกแรก ("ก่อน / หลัง ทั้งหมด") เป็นหลักครับ/ค่ะ

#รายละเอียดขั้นตอน

#ตัวแปรที่กำหนดเอง (Custom variable)

ใช้สำหรับกำหนดตัวแปรขึ้นมาเองเพื่อนำไปใช้ในบริบท (context) ครับ/ค่ะ

#ขอบเขต (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: 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 });