Szkriptelés a sablonkészítőben

Gyakorlati útmutató CEL-kifejezések írásához a CMS-ben.

Hogyan működik a CEL?

A CEL (Common Expression Language) egy könnyű szkriptnyelv, amely be van építve a CMS-ünkbe. Segítségével dinamikus kifejezéseket írhat, amelyek adatokat kérhetnek le dokumentumokból, URL-paramétereket olvashatnak ki, és menet közben értékeket számíthatnak ki.

Ez történik egy CEL-szkript futtatásakor:

A szkriptje                    A motor                       Eredmény
    |                              |                              |
    v                              v                              v
documents.get("article", "intro") --> Lekérés az adatbázisból --> { headline: "Welcome", body: "..." }
         .headline                --> A mező kinyerése     --> "Welcome"

A CEL-re úgy tekintsen, mint egy csak olvasható lekérdezési nyelvre. Nem módosíthat semmit az adatbázisban – csak adatokat olvas, és kiszámított eredményt ad vissza. Ezért biztonságosan használható a CMS bármely részén.

Az építőelemek

Minden CEL-kifejezés három dologhoz fér hozzá:

Önmagára hivatkozás a doc használatával

Amikor dokumentumszerkesztőben ír CEL-kifejezéseket, a doc objektummal elérheti az aktuális dokumentum mezőértékeit. Ez lehetővé teszi a számított mezők és a mezők közötti hivatkozások használatát.

// Az aktuális dokumentum price mezőjének elérése
doc.price

// Összeg kiszámítása az aktuális dokumentum mezőiből
doc.price * doc.quantity

// Feltétel az aktuális dokumentum állapota alapján
doc.status == "published" ? doc.title : "Draft: " + doc.title

A doc objektum a szerkesztett dokumentum összes mezőértékét tartalmazza. Ez hasznos:

• Számított mezőkhöz (például: doc.price * doc.quantity)
• A dokumentum állapotán alapuló feltételes megjelenítési logikához
• Érvényesítéshez hasonló kifejezésekhez

Dokumentumok lekérése

A CEL leghasznosabb funkciója, hogy a CMS bármely részéről képes dokumentumokat lekérni.

Egyetlen dokumentum lekérése

Szintaxis: documents.get(schemaName, identifier)

Tegyük fel, hogy van egy article dokumentuma "welcome-post" azonosítóval:

// A CMS-ben tárolva: article / welcome-post
{
  "headline": "Üdvözöljük platformunkon",
  "author": "Sarah Chen",
  "body": "Örömmel jelentjük be...",
  "tags": ["bejelentés", "hírek"]
}

A teljes dokumentum lekérése:

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

A fejléc lekérése:

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

Az eredmény: "Üdvözöljük platformunkon"

A szerző lekérése:

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

Az eredmény: "Sarah Chen"

URL-paraméterek használata

Ha az oldala dinamikus útvonalakat használ (például /articles/[slug]), a meta.params segítségével lekérheti az URL-paramétert, majd betöltheti a megfelelő dokumentumot.

Ha valaki meglátogatja a /articles/welcome-post címet:

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

Az eredmény: "Üdvözöljük platformunkon"

Így készíthet dinamikus oldalakat: ugyanaz a CEL-szkript működik minden cikkhez, mindig az URL-ben szereplő slugot használva.

Több dokumentum lekérése

Szintaxis: documents.find(schemaName) vagy documents.find(schemaName, filter)

// Az összes ország lekérése
documents.find("country")

// Országok lekérése szűrővel
documents.find("country", { "where": { "code": "us" } })

Fordítások

A CEL kétféleképpen támogatja a lefordított dokumentumtartalom lekérését: automatikus, területi beállításon alapuló fordítással és explicit fordításkereséssel.

Automatikus fordítás a meta.locale használatával

Ha a meta.locale be van állítva (például útvonalparaméterekből vagy felhasználói beállításokból), a documents.get() automatikusan egyesíti a lefordított tartalmat:

// Ha a meta.locale értéke "fr", a francia fordítást egyesíti az alapdokumentummal
documents.get("greeting", "welcome").headline

Működése:

1. Lekéri az alapdokumentum tartalmát
2. Ha a meta.locale nem "en" vagy "en-US", megkeresi a fordítást a translations táblában
3. A lefordított mezőket egyesíti az alaptartalommal: { ...baseContent, ...translatedContent }

Ez azt jelenti, hogy a lefordított mezők felülírják az alapmezőket, a le nem fordított mezők pedig az alapdokumentum értékeire állnak vissza.

Explicit fordítás a documents.translated() használatával

Ha az aktuális területi beállítástól függetlenül egy adott fordítást szeretne lekérni:

Szintaxis: documents.translated(schemaName, identifier, locale)

// Mindig a spanyol fordítás lekérése
documents.translated("greeting", "welcome", "es").headline

// Fordítás lekérése URL-paraméter alapján
documents.translated("product", meta.params.id, meta.params.lang).description

// Fordítások összehasonlítása
documents.translated("article", "intro", "en").title + " / " + documents.translated("article", "intro", "fr").title

Valós példák

1. példa: Hősszekció címe egy másik dokumentumból

Van egy hero-block blokkja, amelynek egy article dokumentumból származó címsort kell megjelenítenie.

A CEL-szkript a hősszekció címmezőjében:

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

Eredmény: A hősszekció a "Build Faster, Ship Smarter" szöveget jeleníti meg.

2. példa: Országnév kód alapján

A /countries/[code] oldalon a teljes országnevet szeretné megjeleníteni.

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

Ha valaki a /countries/us címet látogatja meg:

• meta.params.code = "us"
• Eredmény: "United States"

3. példa: Területi beállításon alapuló feltételes tartalom

meta.locale == "ar-SA" ? "Üdvözlünk mindenkit" : "Üdvözöljük"

4. példa: Láncolt dokumentumkeresések

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

A kifejezés először lekéri a cikket, kinyeri a countryCode mezőt, majd lekéri az országot és annak nevét.

5. példa: Tartalékértékek

Ha előfordulhat, hogy egy dokumentum nem létezik, megadhat tartalékértéket:

documents.get("article", meta.params.slug) != null
  ? documents.get("article", meta.params.slug).headline
  : "A cikk nem található"

6. példa: Listák kezelése

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

true értéket ad vissza, ha a cikk tartalmazza a "featured" címkét.

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

A címkék számát adja vissza.

Paraméterezett útvonalak és a meta.params

A paraméterezett útvonalak dinamikus, lokalizált oldalak készítésének alapjai. Amikor olyan útvonalmintát határoz meg, mint a /{lang}/landingPage, a CMS kinyeri a paramétereket az URL-ből, és elérhetővé teszi őket a meta.params segítségével.

Az útvonalparaméterek működése

Az útvonalak a :paramName vagy {paramName} szintaxist használják a dinamikus szegmensek meghatározására:

Példa: nyelvfüggő céloldal

Útvonal-konfiguráció:

• Útvonal: /{lang}/landingPage
• Paraméter-hozzárendelés: { "lang": "language" }

Lokalizált tartalom lekérése:

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

meta.segments – A nyers URL-elérési út

A meta.segments a nyers URL-útvonalat tömbként biztosítja. Akkor hasznos, ha név szerinti paraméterek helyett pozíció alapján szeretne hozzáférni a szegmensekhez.

Mikor használja a meta.segments és mikor a meta.params értéket?

A teljes meta objektum referenciája

A meta objektum az aktuális kérés teljes környezetét tartalmazza:

meta.locale

A területi kód a BCP 47 formátumot követi:

meta.locale == "ar-SA" || meta.locale == "he-IL" ? "rtl" : "ltr"

meta.params

Az útvonalparaméterek mindig karakterláncok. A CMS kiértékelés előtt ellenőrzi őket a hozzárendelt sémák alapján:

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

meta.segments

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

meta.docId

meta.docId != null ? "szerkesztés" : "új létrehozása"

meta.title

"Szerkesztés: " + meta.title
meta.title.contains("Draft") ? "folyamatban" : "közzétéve"

documents.ref() – Láncolt keresések

Ha a séma ismert, de az azonosító dinamikus, a ref() tisztább szintaxist biztosít:

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

A két megoldás egyenértékű, de a ref() egyértelműbben jelzi a dinamikus részt.

Gyors referencia

Dokumentumok lekérése

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")

Környezeti változók

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

Operátorok

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

Gyakori függvények

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

Hibaüzenetek

Ha valami nem működik, az alábbi hibák egyikét láthatja:

Bővíthetőség és jövőbeli lehetőségek

A CEL-motor bővíthetőségre készült. A tervezett jövőbeli lehetőségek közé tartoznak:

Tervezett: MCP-szerverintegráció

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

Tervezett: MI-képességek

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"])

Ezeket a képességeket a regisztrált függvényrendszeren keresztül adjuk hozzá, miközben megőrizzük a meglévő szkriptek visszamenőleges kompatibilitását.

Tippek

1. Használja az automatikus kiegészítést – írja be a documents. vagy meta. előtagot, és a szerkesztő megjeleníti az elérhető lehetőségeket
2. Kezdje egyszerűen – először tesztelje a documents.get("schema", "id") kifejezést, majd adja hozzá a .fieldName részt
3. Ellenőrizze a null értékeket – ha a dokumentum nem biztos, hogy létezik, adjon meg tartalékértéket a != null ? ... : ... mintával
4. Ne kérjen le felesleges adatokat – minden documents.get() vagy documents.find() hívás beleszámít az 50-es lekérési korlátba
5. Részesítse előnyben a meta.params használatát a meta.segments helyett – a név szerinti paraméterek ellenőrzöttek és megbízhatóbbak
6. Opcionális paraméterekhez használja a has() függvényt – hozzáférés előtt ellenőrizze a has(meta.params.category) értéket
7. Dinamikus azonosítókhoz használja a documents.ref() függvényt – egyértelműbb, ha a séma állandó, az azonosító viszont dinamikus
8. Önmagára hivatkozáshoz használja a doc.fieldName formát – így számított kifejezésekben elérheti az aktuális dokumentum mezőit

Dokumentumok közötti hivatkozások

Ez a rész a dokumentumok összekapcsolásának és relációs tartalmi struktúrák kialakításának fejlettebb mintáit ismerteti.

Alapvető hivatkozási minta

A legegyszerűbb esetben az egyik dokumentum azonosító alapján hivatkozik egy másikra.

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

Láncolt keresések a documents.ref() segítségével

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

Többszintű hivatkozási láncok

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

Hivatkozás fordítással

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

Hivatkozások bevált gyakorlatai

1. Minimalizálja a lánc mélységét – minden szint növeli a késleltetést és a lekérések számát
2. Gyorsítótárazza a köztes eredményeket – ha ugyanarra a beágyazott értékre kétszer van szüksége, a szülőt csak egyszer kérje le
3. Használjon null-ellenőrzéseket – a hivatkozások megszakadhatnak, ha dokumentumokat törölnek
4. UUID-k helyett részesítse előnyben a kódokat – a kódok olvashatóbbak a kifejezésekben és stabilabbak a környezetek között
5. Figyelje a lekérési korlátokat – az összetett hivatkozási láncok gyorsan elérhetik az 50-es korlátot

A függelék: Teljes paraméterezett útvonali példa

Ez a bemutató egy többnyelvű céloldalt hoz létre, amely a /{lang}/landingPage címen érhető el.

1. lépés: A greeting dokumentumséma létrehozása

Hozzon létre a CMS adminisztrációs felületén egy greeting nevű egyéni sémát.

2. lépés: Greeting dokumentumok létrehozása

Hozzon létre dokumentumokat minden nyelvhez.

3. lépés: Az oldal létrehozása

• Útvonal/minta: /{lang}/landingPage
• Állapot: Éles
• Dinamikus szegmens-hozzárendelések: a lang hozzárendelése a language komponenshez

4. lépés: Blokkok hozzáadása CEL-szkriptekkel

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. lépés: Használat Next.js-ben

Adjon hozzá egy minden útvonalat kezelő útvonalat. A ParametricRoutePage feloldja az oldalt, kinyeri a meta.params értékeket az URL-ből, szerveroldalon kiértékeli a CEL-hozzárendeléseket, majd a regisztráción keresztül megjeleníti az egyes blokkokat.

6. lépés: Az útvonalak tesztelése

B függelék: Műszaki referencia

CelMeta interfész (TypeScript)

interface CelMeta {
  locale: string;
  params: Record<string, string>;
  segments: string[];
  docId: string | null;
  title: string;
}

Paraméterkinyerési algoritmus

Az extractParams függvény feldolgozza az URL-útvonalakat:

Minta:    /{country}/{lang}/products
Útvonal:  /us/en/products

Algoritmus:
1. Mindkettő normalizálása (záró perjelek eltávolítása)
2. Szegmensekre bontás
3. A szegmensek számának egyeztetése
4. Minden szegmenspár feldolgozása
5. Eredmény: { country: "us", lang: "en" }

Támogatott paraméter-hozzárendelési formátumok

{ "lang": "language" }

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

Dokumentumkeresési prioritás

A documents.get(schema, identifier) használatakor:

1. UUID-egyezés: érvényes UUID esetén lekérés az id alapján
2. Code mező: a content.code mező ellenőrzése
3. Slug mező: a content.slug mező ellenőrzése
4. Cím szerinti egyezés: a title mező ellenőrzése

Ez rugalmas dokumentumhivatkozást tesz lehetővé bármely egyedi azonosító használatával.