Pisanje skripti u alatu za izradu predložaka

Praktični vodič za pisanje CEL izraza u CMS-u.

Kako CEL funkcionira

CEL (Common Expression Language) lagani je skriptni jezik ugrađen u naš CMS. Omogućuje pisanje dinamičkih izraza koji mogu dohvaćati podatke iz dokumenata, čitati parametre URL-a i izračunavati vrijednosti u hodu.

Što se događa kada se CEL skripta izvrši:

Vaša skripta                  Pokretač                       Rezultat
    |                              |                              |
    v                              v                              v
documents.get("article", "intro") --> Dohvaća iz baze podataka --> { headline: "Dobro došli", body: "..." }
         .headline                --> Izdvaja polje          --> "Dobro došli"

CEL možete zamisliti kao jezik upita samo za čitanje. Ne može mijenjati ništa u bazi podataka – samo čita podatke i vraća izračunati rezultat. Zato je siguran za upotrebu bilo gdje u CMS-u.

Osnovni elementi

Svaki CEL izraz ima pristup trima stvarima:

Referenciranje trenutačnog dokumenta pomoću doc

Pri pisanju CEL izraza unutar uređivača dokumenta vrijednostima polja trenutačnog dokumenta možete pristupiti pomoću objekta doc. To omogućuje izračunata polja i reference među poljima.

// Pristup polju cijene trenutačnog dokumenta
doc.price

// Izračun ukupnog iz polja trenutačnog dokumenta
doc.price * doc.quantity

// Uvjet na temelju statusa trenutačnog dokumenta
doc.status == "published" ? doc.title : "Nacrt: " + doc.title

Objekt doc sadrži sve vrijednosti polja uređivanog dokumenta. Koristan je za:

• izračunata polja (npr. doc.price * doc.quantity)
• uvjetnu logiku prikaza na temelju stanja dokumenta
• izraze za provjeru valjanosti

Dohvaćanje dokumenata

Najmoćnija je značajka CEL-a dohvaćanje dokumenata iz bilo kojeg dijela CMS-a.

Dohvaćanje pojedinačnog dokumenta

Sintaksa: documents.get(schemaName, identifier)

Ako imate dokument article s identifikatorom "welcome-post":

{
  "headline": "Dobro došli na našu platformu",
  "author": "Sarah Chen",
  "body": "Uzbuđeni smo što možemo objaviti...",
  "tags": ["objava", "vijesti"]
}

Dohvaćanje cijelog dokumenta:

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

Dohvaćanje samo naslova:

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

Vraća: "Dobro došli na našu platformu"

Dohvaćanje autora:

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

Upotreba parametara URL-a

Kada stranica ima dinamičke rute poput /articles/[slug], pomoću meta.params možete dohvatiti parametar URL-a i odgovarajući dokument.

Ako netko posjeti /articles/welcome-post:

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

Vraća: "Dobro došli na našu platformu"

Tako se izrađuju dinamičke stranice – ista CEL skripta radi za svaki članak, koristeći vrijednost slug iz URL-a.

Dohvaćanje više dokumenata

Sintaksa: documents.find(schemaName) ili documents.find(schemaName, filter)

// Dohvati sve države
documents.find("country")

// Dohvati države uz filtar
documents.find("country", { "where": { "code": "us" } })

Prijevodi

CEL podržava dohvaćanje prevedenog sadržaja na dva načina: automatskim prijevodom na temelju lokalizacije i eksplicitnim dohvatom prijevoda.

Automatski prijevod putem meta.locale

Kada je postavljen meta.locale, documents.get() automatski spaja prevedeni sadržaj:

documents.get("greeting", "welcome").headline

Ako je meta.locale postavljen na "fr", vraća se francuski prijevod spojen s osnovnim dokumentom. Prevedena polja imaju prednost, a polja bez prijevoda preuzimaju se iz osnovnog dokumenta.

Eksplicitni prijevod pomoću documents.translated()

Za dohvaćanje određenog prijevoda neovisno o trenutačnoj lokalizaciji upotrijebite:

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

// Uvijek dohvaća španjolski prijevod
documents.translated("greeting", "welcome", "es").headline

// Dohvaća prijevod na temelju parametra URL-a
documents.translated("product", meta.params.id, meta.params.lang).description

Primjeri iz prakse

Primjer 1: Naslov hero bloka iz drugog dokumenta

Ako hero blok treba prikazati naslov iz dokumenta article:

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

Rezultat: hero prikazuje naslov "Brže izgradite, pametnije objavite".

Primjer 2: Naziv države iz koda

Za stranicu /countries/[code] upotrijebite:

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

Za /countries/us vrijednost meta.params.code jest "us", a rezultat "Sjedinjene Američke Države".

Primjer 3: Uvjetni sadržaj na temelju lokalizacije

meta.locale == "ar-SA" ? "Dobro došli svima" : "Dobro došli"

Primjer 4: Lančano dohvaćanje dokumenata

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

Unutarnji poziv dohvaća članak, .countryCode izdvaja kôd države, a vanjski poziv dohvaća naziv države.

Primjer 5: Rezervne vrijednosti

documents.get("article", meta.params.slug) != null
  ? documents.get("article", meta.params.slug).headline
  : "Članak nije pronađen"

Primjer 6: Rad s popisima

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

Parametarske rute i meta.params

Parametarske su rute ključ za izradu dinamičkih, lokaliziranih stranica. Kada definirate uzorak rute poput /{lang}/landingPage, CMS izdvaja parametre iz URL-a i čini ih dostupnima putem meta.params.

Rute mogu koristiti sintaksu :paramName ili {paramName}:

Parametar se može povezati sa shemom dokumenta radi provjere valjanosti:

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

CMS tada izdvaja segment lang, provjerava ga prema shemi language i, ako je valjan, stavlja dokument na raspolaganje u razriješenim parametrima.

meta.segments – pristup sirovoj putanji URL-a

meta.segments daje putanju URL-a kao polje, što je korisno za pristup po poziciji:

meta.segments[0]
size(meta.segments) > 2 ? "duboka" : "plitka"
"admin" in meta.segments ? "administratorski način" : "javni način"
has(meta.params.lang) ? meta.params.lang : meta.segments[0]

Potpuna referenca objekta meta

Primjeri:

meta.locale == "ar-SA" || meta.locale == "he-IL" ? "rtl" : "ltr"
meta.params.lang
meta.params.country
meta.params.slug
has(meta.params.category)
meta.docId != null ? "uređivanje" : "izrada novog"
"Uređivanje: " + meta.title

documents.ref() – lančano dohvaćanje

Kada je shema poznata, a identifikator dinamičan, možete upotrijebiti:

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

To je ekvivalentno izrazu documents.get("airports", meta.params.code).name, ali jasnije odvaja shemu od dinamičkog identifikatora.

Brzi pregled

Dohvaćanje dokumenata

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

Kontekstne varijable

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

Operatori

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

Uobičajene funkcije

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

Poruke o pogreškama

Savjeti

1. Koristite automatsko dovršavanje – upišite documents. ili meta. kako biste vidjeli dostupne mogućnosti
2. Počnite jednostavno – najprije testirajte documents.get("schema", "id"), a zatim dodajte .fieldName
3. Provjeravajte null vrijednosti – dodajte rezervnu vrijednost pomoću != null ? ... : ...
4. Ne dohvaćajte previše podataka – svaki documents.get() ili documents.find() računa se u ograničenje od 50 dohvaćanja
5. Dajte prednost meta.params pred meta.segments – imenovani su parametri provjereni i pouzdaniji
6. Za neobavezne parametre koristite has()
7. Za dinamičke identifikatore koristite documents.ref()
8. Za samoreferenciranje koristite doc.fieldName

Reference između dokumenata

Dokumenti se mogu povezivati identifikatorima i dohvaćati u lancu:

// Članak sadrži ID autora; dohvatite njegovo ime
documents.get("author", documents.get("article", "intro").authorId).name

// Lanac zračna luka → država → regija → kontinent
documents.get("continent",
  documents.get("region",
    documents.get("country",
      documents.get("airport", meta.params.code).countryCode
    ).regionCode
  ).continentCode
).name

Reference se mogu kombinirati s prijevodima:

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

Najbolje prakse:

1. smanjite dubinu lanaca
2. predmemorirajte međurezultate
3. koristite provjere null vrijednosti
4. prednost dajte kodovima pred UUID-ovima
5. pazite na ograničenje od 50 dohvaćanja

Dodatak: primjer parametarske rute

Višejezična odredišna stranica može biti dostupna na /{lang}/landingPage. CEL skripta za dohvaćanje lokaliziranog sadržaja glasi:

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

Za rutu /{lang}/landingPage konfigurirajte povezivanje:

{
  "lang": "language"
}

U aplikaciji Next.js komponenta ParametricRoutePage razrješava stranicu, izdvaja meta.params iz URL-a, izvršava CEL povezivanja na poslužitelju i prikazuje blokove kroz registar.

export const dynamic = 'force-static';

export default async function Page({ params }) {
  const { slug } = await params;
  return <ParametricRoutePage params={Promise.resolve({ slug })} />;
}

Kada korisnik posjeti /ko/landingPage, CMS pronalazi rutu, postavlja meta.params.lang = "ko", provjerava parametar i vraća lokalizirane blokove.

Tehnička referenca

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

Algoritam izdvajanja parametara normalizira putanju, dijeli je na segmente, uspoređuje broj segmenata, izdvaja dinamičke segmente i vraća objekt poput { country: "us", lang: "en" }.

Podržani oblici povezivanja:

{ "lang": "language" }

ili detaljni oblik s prilagođenim poljem:

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

Prioritet dohvaćanja dokumenta putem documents.get(schema, identifier) jest: podudaranje UUID-a, polje content.code, polje content.slug, a zatim podudaranje naslova.