CEL Scripting in Template Builder

คู่มือเชิงปฏิบัติสำหรับการเขียนนิพจน์ CEL ใน CMS

CEL ทำงานอย่างไร

CEL (Common Expression Language) คือภาษาสคริปต์ขนาดเล็กที่มีอยู่ใน CMS ของเรา ช่วยให้คุณเขียนนิพจน์แบบไดนามิกเพื่อดึงข้อมูลจากเอกสาร อ่านพารามิเตอร์ URL และคำนวณค่าได้ทันที

เมื่อสคริปต์ CEL ทำงาน จะเกิดขั้นตอนดังนี้:

สคริปต์ของคุณ                  เอ็นจิน                         ผลลัพธ์
    |                            |                                |
    v                            v                                v
documents.get("article", "intro") --> ดึงข้อมูลจากฐานข้อมูล --> { headline: "Welcome", body: "..." }
         .headline                --> ดึงฟิลด์                   --> "Welcome"

ให้คิดว่า CEL เป็นภาษาสำหรับค้นข้อมูลแบบอ่านอย่างเดียว ไม่สามารถแก้ไขข้อมูลในฐานข้อมูลได้ แต่จะอ่านข้อมูลและส่งคืนผลลัพธ์ที่คำนวณแล้ว จึงปลอดภัยสำหรับการใช้งานทุกที่ใน CMS

ส่วนประกอบพื้นฐาน

นิพจน์ CEL ทุกตัวสามารถเข้าถึงสิ่งต่าง ๆ ได้สามอย่าง:

การอ้างอิงตัวเองด้วย doc

เมื่อเขียนนิพจน์ CEL ภายในตัวแก้ไขเอกสาร คุณสามารถเข้าถึงค่าฟิลด์ของเอกสารปัจจุบันผ่านออบเจ็กต์ doc ซึ่งช่วยให้สร้างฟิลด์คำนวณและการอ้างอิงข้ามฟิลด์ได้

// เข้าถึงฟิลด์ราคาในเอกสารปัจจุบัน
doc.price

// คำนวณยอดรวมจากฟิลด์ในเอกสารปัจจุบัน
doc.price * doc.quantity

// เงื่อนไขตามสถานะของเอกสารปัจจุบัน
doc.status == "published" ? doc.title : "ฉบับร่าง: " + doc.title

ออบเจ็กต์ doc ประกอบด้วยค่าฟิลด์ทั้งหมดจากเอกสารที่กำลังแก้ไข เหมาะสำหรับ:

• ฟิลด์คำนวณ เช่น doc.price * doc.quantity
• ตรรกะการแสดงผลตามสถานะเอกสาร
• นิพจน์สำหรับตรวจสอบความถูกต้อง

การดึงเอกสาร

ความสามารถที่ทรงพลังที่สุดของ CEL คือการดึงเอกสารจากที่ใดก็ได้ใน CMS

การดึงเอกสารเดียว

ไวยากรณ์: documents.get(schemaName, identifier)

สมมติว่าคุณมีเอกสาร article ที่จัดเก็บด้วยตัวระบุ "welcome-post":

// จัดเก็บใน CMS เป็น: article / welcome-post
{
  "headline": "ยินดีต้อนรับสู่แพลตฟอร์มของเรา",
  "author": "Sarah Chen",
  "body": "เรายินดีที่จะประกาศ...",
  "tags": ["ประกาศ", "ข่าว"]
}

ดึงเอกสารทั้งฉบับ:

documents.get("article", "welcome-post")

ดึงเฉพาะพาดหัว:

documents.get("article", "welcome-post").headline

ดึงผู้เขียน:

documents.get("article", "welcome-post").author

การใช้พารามิเตอร์ URL

เมื่อหน้าเว็บมีเส้นทางแบบไดนามิก เช่น /articles/[slug] คุณสามารถใช้ meta.params เพื่ออ่านพารามิเตอร์ URL แล้วดึงเอกสารที่ถูกต้องได้

หากมีผู้เข้าชม /articles/welcome-post:

documents.get("article", meta.params.slug).headline

วิธีนี้ทำให้สร้างหน้าแบบไดนามิกได้ โดยใช้สคริปต์ CEL เดียวกันกับบทความทุกฉบับ และใช้ slug จาก URL เป็นตัวกำหนดเอกสาร

การดึงเอกสารหลายรายการ

ไวยากรณ์: documents.find(schemaName) หรือ documents.find(schemaName, filter)

// ดึงประเทศทั้งหมด
documents.find("country")

// ดึงประเทศด้วยตัวกรอง
documents.find("country", { "where": { "code": "us" } })

ผลลัพธ์จะเป็นอาร์เรย์ของเอกสารที่ตรงตามเงื่อนไข

การแปลภาษา

CEL รองรับการดึงเนื้อหาเอกสารที่แปลแล้วสองวิธี ได้แก่ การแปลอัตโนมัติตาม locale และการค้นหาคำแปลแบบระบุภาษาโดยตรง

การแปลอัตโนมัติผ่าน meta.locale

เมื่อกำหนด meta.locale เช่นจากพารามิเตอร์เส้นทางหรือการตั้งค่าของผู้ใช้ documents.get() จะผสานเนื้อหาที่แปลแล้วให้อัตโนมัติ:

// หาก meta.locale เป็น "fr" จะคืนคำแปลภาษาฝรั่งเศสที่ผสานกับเอกสารพื้นฐาน
documents.get("greeting", "welcome").headline

การทำงานคือ:

1. ดึงเนื้อหาของเอกสารพื้นฐาน
2. หาก meta.locale ไม่ใช่ en หรือ en-US จะค้นหาคำแปลในตาราง translations
3. ผสานฟิลด์ที่แปลทับเนื้อหาพื้นฐานด้วย { ...baseContent, ...translatedContent }

ฟิลด์ที่มีคำแปลจะมีลำดับความสำคัญสูงกว่า ส่วนฟิลด์ที่ยังไม่ได้แปลจะใช้ค่าจากเอกสารพื้นฐาน

การแปลแบบระบุผ่าน documents.translated()

หากต้องการดึงคำแปลภาษาใดภาษาหนึ่งโดยไม่ขึ้นกับ locale ปัจจุบัน:

ไวยากรณ์: documents.translated(schemaName, identifier, locale)

// ดึงคำแปลภาษาสเปนเสมอ
documents.translated("greeting", "welcome", "es").headline

// ดึงคำแปลตามพารามิเตอร์ URL
documents.translated("product", meta.params.id, meta.params.lang).description

// เปรียบเทียบคำแปล
documents.translated("article", "intro", "en").title + " / " + documents.translated("article", "intro", "fr").title

ตัวอย่างการใช้งานจริง

ตัวอย่างที่ 1: ชื่อบล็อก Hero จากเอกสารอื่น

หากมี hero-block ที่ต้องแสดงพาดหัวจากเอกสาร article:

documents.get("article", "homepage-hero").headline

ผลลัพธ์คือบล็อก Hero จะแสดงพาดหัวของบทความ

ตัวอย่างที่ 2: ชื่อประเทศจากรหัส

สำหรับหน้าที่ /countries/[code] ให้ใช้:

documents.get("country", meta.params.code).name

เมื่อเข้าชม /countries/us ค่า meta.params.code คือ "us" และผลลัพธ์คือชื่อประเทศที่ตรงกัน

ตัวอย่างที่ 3: เนื้อหาตาม locale

meta.locale == "ar-SA" ? "ยินดีต้อนรับทุกคน" : "ยินดีต้อนรับ"

ตัวอย่างที่ 4: การค้นหาเอกสารต่อเนื่อง

documents.get("country", documents.get("article", "us-news").countryCode).name

การทำงานคือดึงบทความ อ่านค่า countryCode จากนั้นดึงเอกสารประเทศและอ่านฟิลด์ name

ตัวอย่างที่ 5: ค่าเริ่มต้นเมื่อไม่พบเอกสาร

documents.get("article", meta.params.slug) != null
  ? documents.get("article", meta.params.slug).headline
  : "ไม่พบบทความ"

หรือตรวจสอบฟิลด์เฉพาะ:

documents.get("article", "intro").author != null
  ? documents.get("article", "intro").author
  : "ไม่ทราบผู้เขียน"

ตัวอย่างที่ 6: การทำงานกับรายการ

"featured" in documents.get("article", "welcome-post").tags

คืนค่า true หากบทความมีแท็กดังกล่าว

documents.get("article", "welcome-post").tags[0]
size(documents.get("article", "welcome-post").tags)

ใช้ [0] เพื่อดึงรายการแรก และใช้ size() เพื่อนับจำนวนรายการ

เส้นทางแบบพารามิเตอร์และ meta.params

เส้นทางแบบพารามิเตอร์เป็นหัวใจของการสร้างหน้าแบบไดนามิกและรองรับหลายภาษา เมื่อกำหนดรูปแบบ เช่น /{lang}/landingPage CMS จะดึงค่าพารามิเตอร์จาก URL และทำให้เข้าถึงได้ผ่าน meta.params

การทำงานของพารามิเตอร์เส้นทาง

เส้นทางใช้ไวยากรณ์ :paramName หรือ {paramName} เพื่อกำหนดส่วนแบบไดนามิก:

พารามิเตอร์แต่ละตัวสามารถผูกกับ schema เพื่อใช้ตรวจสอบความถูกต้องได้:

{
  "pattern": "/{lang}/landingPage",
  "param_bindings": {
    "lang": "language"
  }
}

CMS จะดึงส่วน lang จาก URL ตรวจสอบกับ schema language และทำให้เอกสารฉบับเต็มพร้อมใช้งานในพารามิเตอร์ที่แก้ไขแล้ว

ตัวอย่างหน้า Landing Page ตามภาษา

documents.get("greeting", meta.params.lang).headline

เมื่อเข้าชม /ko/landingPage ค่า meta.params.lang คือ "ko" และระบบจะดึงเนื้อหาภาษาเกาหลี

รูปแบบขั้นสูง: เส้นทางประเทศและภาษา

สำหรับ /{country}/{lang}/products:

{
  "pattern": "/{country}/{lang}/products",
  "param_bindings": {
    "country": "country",
    "lang": "language"
  }
}

// ดึงชื่อประเทศ
documents.get("country", meta.params.country).name

// ดึงรายการสินค้าตามประเทศ
documents.find("product", { "where": { "country": meta.params.country } })

// แสดงคำต้อนรับตามประเทศและภาษา
documents.get("greeting", meta.params.lang).headline + " จาก " + documents.get("country", meta.params.country).name

CMS จะตรวจสอบพารามิเตอร์ตามลำดับชั้น โดยตรวจสอบประเทศก่อน จากนั้นภาษา และอาจตรวจสอบเพิ่มเติมว่าภาษานั้นอยู่ในอาร์เรย์ country.languages[] หรือไม่

meta.segments - การเข้าถึงพาธ URL ดิบ

meta.segments ให้พาธ URL ดิบในรูปอาร์เรย์ เหมาะสำหรับการเข้าถึงตามตำแหน่งโดยไม่ใช้ชื่อพารามิเตอร์

ควรใช้ meta.segments หรือ meta.params

ตัวอย่าง:

meta.segments[0]
size(meta.segments) > 2 ? "ลึก" : "ตื้น"
"admin" in meta.segments ? "โหมดผู้ดูแลระบบ" : "โหมดสาธารณะ"
has(meta.params.lang) ? meta.params.lang : meta.segments[0]

อ้างอิงออบเจ็กต์ meta ทั้งหมด

ออบเจ็กต์ meta มีบริบททั้งหมดของคำขอปัจจุบัน:

meta.locale

รหัส locale ใช้รูปแบบ BCP 47:

meta.locale == "ar-SA" || meta.locale == "he-IL" ? "rtl" : "ltr"
meta.locale.split("-")[0]

meta.params

พารามิเตอร์เส้นทางเป็นสตริงเสมอ และ CMS จะตรวจสอบกับ schema ที่ผูกไว้ก่อนประเมินผล:

meta.params.lang
meta.params.country
meta.params.slug
has(meta.params.category)
documents.get("greeting", meta.params.lang)
documents.ref("airports").get(meta.params.code)

meta.segments

meta.segments[0]
meta.segments[1]
size(meta.segments)
"products" in meta.segments

meta.docId และ meta.title

meta.docId != null ? "กำลังแก้ไข" : "กำลังสร้างใหม่"
meta.docId != null ? documents.get("article", meta.docId).status : "ฉบับร่าง"
"กำลังแก้ไข: " + meta.title
meta.title.contains("Draft") ? "กำลังดำเนินการ" : "เผยแพร่แล้ว"

documents.ref() - การค้นหาแบบต่อเนื่อง

เมื่อทราบ schema แต่ตัวระบุเป็นแบบไดนามิก สามารถเขียนให้กระชับขึ้นได้:

documents.get("airports", meta.params.code).name
documents.ref("airports").get(meta.params.code).name

ทั้งสองแบบให้ผลเหมือนกัน แต่ ref() ทำให้ส่วนที่เป็นไดนามิกอ่านได้ชัดเจนกว่า

ข้อมูลอ้างอิงฉบับย่อ

documents.get("schema", "identifier")
documents.get("schema", "id").fieldName
documents.find("schema")
documents.find("schema", { "where": {...}})
documents.ref("schema").get(identifier)
documents.translated("schema", "id", "fr")

ตัวแปรบริบท:

meta.locale
meta.params.xyz
meta.segments
meta.segments[0]
meta.docId
meta.title
doc.fieldName

ตัวดำเนินการ:

==  !=  <  <=  >  >=
&&  ||  !
condition ? valueIfTrue : valueIfFalse
"value" in listOrMap

ฟังก์ชันที่ใช้บ่อย:

size(list)
size(string)
"text".startsWith("te")
"text".endsWith("xt")
"text".contains("ex")
has(object.property)
hasProperty(obj, "key")

ข้อความแสดงข้อผิดพลาด

ความสามารถในการขยายและฟีเจอร์ในอนาคต

เอ็นจิน CEL ออกแบบมาให้ขยายความสามารถได้ ฟีเจอร์ที่วางแผนไว้ ได้แก่:

แผนในอนาคต: การเชื่อมต่อ MCP Server

mcp.translate(meta.params.text, "en", meta.params.lang)
mcp.analyze(documents.get("article", meta.params.id).body)

แผนในอนาคต: ความสามารถด้าน AI

ai.summarize(documents.get("article", meta.params.id).body, 100)
ai.translate(meta.params.text, meta.params.targetLang)
ai.classify(meta.params.input, ["positive", "negative", "neutral"])

ความสามารถเหล่านี้จะเพิ่มผ่านระบบฟังก์ชันที่ลงทะเบียนไว้ โดยยังคงเข้ากันได้กับสคริปต์เดิม

เคล็ดลับ

1. ใช้การเติมข้อความอัตโนมัติ - พิมพ์ documents. หรือ meta. เพื่อดูตัวเลือกที่มี
2. เริ่มจากสิ่งง่าย ๆ - ทดสอบ documents.get("schema", "id") ก่อน แล้วค่อยเพิ่ม .fieldName
3. ตรวจสอบค่า null - หากเอกสารอาจไม่มี ให้เพิ่มค่า fallback ด้วย != null ? ... : ...
4. อย่าดึงข้อมูลเกินจำเป็น - ทุก documents.get() หรือ documents.find() นับรวมในขีดจำกัด 50 ครั้ง
5. เลือกใช้ meta.params มากกว่า meta.segments - พารามิเตอร์ที่มีชื่อผ่านการตรวจสอบและเชื่อถือได้มากกว่า
6. ใช้ has() กับพารามิเตอร์ทางเลือก - ตรวจสอบ has(meta.params.category) ก่อนเข้าถึง
7. ใช้ documents.ref() กับตัวระบุแบบไดนามิก - อ่านง่ายกว่าเมื่อ schema คงที่แต่ตัวระบุเปลี่ยนแปลง
8. ใช้ doc.fieldName สำหรับการอ้างอิงตัวเอง - เข้าถึงฟิลด์ของเอกสารปัจจุบันในนิพจน์คำนวณ

การอ้างอิงระหว่างเอกสาร

ส่วนนี้ครอบคลุมรูปแบบขั้นสูงสำหรับการเชื่อมโยงเอกสารและสร้างโครงสร้างเนื้อหาแบบสัมพันธ์กัน

รูปแบบการอ้างอิงพื้นฐาน

เอกสารหนึ่งเก็บตัวระบุของอีกเอกสารหนึ่งไว้:

documents.get("author", documents.get("article", "intro").authorId).name

การค้นหาหลายระดับ

สามารถสร้างความสัมพันธ์หลายชั้นได้ด้วยการต่อคำสั่งค้นหา:

documents.get("continent",
  documents.get("region",
    documents.get("country",
      documents.get("airport", meta.params.code).countryCode
    ).regionCode
  ).continentCode
).name

การอ้างอิงพร้อมคำแปล

documents.translated("country",
  documents.get("airport", meta.params.code).countryCode,
  meta.params.lang
).name

แนวทางปฏิบัติที่ดี

1. ลดความลึกของสายการค้นหา - แต่ละระดับเพิ่มเวลาและจำนวนครั้งในการดึงข้อมูล
2. เก็บผลลัพธ์ระหว่างทางไว้ใช้ซ้ำ - หากต้องใช้ค่าซ้อนเดิมสองครั้ง ให้ดึงเอกสารหลักเพียงครั้งเดียว
3. ตรวจสอบค่า null - การอ้างอิงอาจล้มเหลวเมื่อเอกสารถูกลบ
4. เลือกใช้รหัสแทน UUID - รหัสอ่านง่ายและคงที่ระหว่างสภาพแวดล้อม
5. ระวังขีดจำกัดการดึงข้อมูล - สายการอ้างอิงซับซ้อนอาจแตะขีดจำกัด 50 ครั้งได้อย่างรวดเร็ว

ทุกการเรียก documents.get(), documents.find() และ documents.ref().get() จะถูกติดตามเพื่อทำให้แคชไม่ถูกต้องโดยอัตโนมัติเมื่อเอกสารอ้างอิงเปลี่ยนแปลง

ภาคผนวก A: ตัวอย่างเส้นทางแบบพารามิเตอร์ฉบับสมบูรณ์

ตัวอย่างนี้สร้างหน้า Landing Page หลายภาษาที่เข้าถึงได้ผ่าน /{lang}/landingPage

ขั้นตอนที่ 1: สร้าง schema เอกสาร Greeting

ในส่วนผู้ดูแลระบบ CMS ให้สร้าง schema แบบกำหนดเองชื่อ greeting พร้อมฟิลด์ code, headline, subheadline, ctaText และ ctaUrl

ขั้นตอนที่ 2: สร้างเอกสาร Greeting

สร้างเอกสารสำหรับแต่ละภาษา โดยใช้ตัวระบุ เช่น greeting/ko, greeting/en และ greeting/ja

ขั้นตอนที่ 3: สร้างหน้า

กำหนดค่า:

• พาธ/รูปแบบ: /{lang}/landingPage
• สถานะ: ใช้งานจริง
• การจับคู่ส่วนไดนามิก: map lang ไปยังคอมโพเนนต์ language

ขั้นตอนที่ 4: เพิ่มบล็อกด้วยสคริปต์ CEL

documents.get("greeting", meta.params.lang).headline
documents.get("greeting", meta.params.lang).subheadline
documents.get("greeting", meta.params.lang).ctaText
documents.get("greeting", meta.params.lang).ctaUrl

ขั้นตอนที่ 5: ใช้งานใน Next.js

เพิ่มเส้นทางแบบ catch-all โดย ParametricRoutePage จะ resolve หน้า ดึง meta.params จาก URL ประเมิน binding ของ CEL ฝั่งเซิร์ฟเวอร์ และเรนเดอร์แต่ละบล็อกผ่าน registry

ขั้นตอนที่ 6: ทดสอบเส้นทาง

เมื่อผู้ใช้เข้าชม /ko/landingPage CMS จะจับคู่เส้นทาง ดึง meta.params.lang = "ko" ตรวจสอบค่า ประเมิน CEL และส่งบล็อกที่แปลแล้วกลับไปยังไคลเอนต์

ภาคผนวก B: ข้อมูลอ้างอิงทางเทคนิค

อินเทอร์เฟซ CelMeta (TypeScript)

interface CelMeta {
  /** รหัส locale ปัจจุบัน */
  locale: string;
  /** พารามิเตอร์เส้นทางที่ดึงจาก URL */
  params: Record<string, string>;
  /** ส่วนต่าง ๆ ของพาธ URL */
  segments: string[];
  /** ID เอกสารปัจจุบัน */
  docId: string | null;
  /** ชื่อเอกสารปัจจุบัน */
  title: string;
}

อัลกอริทึมการดึงพารามิเตอร์

ฟังก์ชัน extractParams ประมวลผลพาธ URL ดังนี้:

รูปแบบ: /{country}/{lang}/products
พาธ:     /us/en/products

อัลกอริทึม:
1. ทำให้ทั้งสองรูปแบบเป็นมาตรฐาน โดยลบ slash ท้ายออก
2. แยกเป็นส่วนต่าง ๆ
3. ตรวจสอบว่าจำนวนส่วนเท่ากัน
4. หากส่วนของรูปแบบขึ้นต้นด้วย : หรือ {} ให้ดึงเป็นพารามิเตอร์ มิฉะนั้นต้องตรงกันทุกประการ
5. ส่งคืน: { country: "us", lang: "en" }

รูปแบบการผูกพารามิเตอร์ที่รองรับ

{ "lang": "language" }

{
  "lang": {
    "schemaName": "language",
    "slugField": "code"
  },
  "slug": {
    "schemaName": "article",
    "slugField": "slug"
  }
}

ลำดับความสำคัญในการค้นหาเอกสาร

เมื่อดึงข้อมูลผ่าน documents.get(schema, identifier):

1. ตรงกับ UUID: หากตัวระบุเป็น UUID ที่ถูกต้อง ให้ค้นหาด้วย id
2. ฟิลด์ Code: ตรวจสอบฟิลด์ content.code
3. ฟิลด์ Slug: ตรวจสอบฟิลด์ content.slug
4. ตรงกับชื่อเรื่อง: ตรวจสอบฟิลด์ title

จึงสามารถอ้างอิงเอกสารด้วยตัวระบุเฉพาะที่เหมาะสมได้อย่างยืดหยุ่น