Pisanje skript v graditelju predlog

Praktični vodnik za pisanje izrazov CEL v sistemu CMS.

Kako deluje CEL

CEL (Common Expression Language oziroma skupni jezik izrazov) je lahek skriptni jezik, vgrajen v naš CMS. Omogoča pisanje dinamičnih izrazov, ki lahko pridobivajo podatke iz dokumentov, berejo parametre URL-ja in sproti izračunavajo vrednosti.

Ko se zažene skript CEL:

Vaš skript                     Mehanizem                     Rezultat
    |                              |                              |
    v                              v                              v
documents.get("article", "intro") --> Pridobi iz podatkovne zbirke --> { headline: "Welcome", body: "..." }
         .headline                --> Izlušči polje          --> "Welcome"

CEL si lahko predstavljate kot jezik poizvedb samo za branje. V podatkovni zbirki ne more ničesar spreminjati – podatke samo prebere in vrne izračunan rezultat. Zato ga je varno uporabljati kjer koli v sistemu CMS.

Gradniki

Vsak izraz CEL ima dostop do treh stvari:

Sklicevanje nase z doc

Pri pisanju izrazov CEL v urejevalniku dokumentov lahko do vrednosti polj trenutnega dokumenta dostopate z objektom doc. To omogoča izračunana polja in sklicevanja med polji.

// Dostop do polja price trenutnega dokumenta
doc.price

// Izračun skupne vrednosti iz polj trenutnega dokumenta
doc.price * doc.quantity

// Pogoj glede na stanje trenutnega dokumenta
doc.status == "published" ? doc.title : "Draft: " + doc.title

Objekt doc vsebuje vse vrednosti polj urejanega dokumenta. Uporaben je za:

• izračunana polja (na primer doc.price * doc.quantity),
• logiko pogojnega prikaza glede na stanje dokumenta,
• izraze v slogu preverjanja veljavnosti.

Pridobivanje dokumentov

Najzmogljivejša funkcija CEL je pridobivanje dokumentov s katerega koli mesta v sistemu CMS.

Pridobivanje enega dokumenta

Sintaksa: documents.get(schemaName, identifier)

Recimo, da imate dokument article, shranjen z identifikatorjem "welcome-post":

// Shranjeno v sistemu CMS kot: article / welcome-post
{
  "headline": "Welcome to Our Platform",
  "author": "Sarah Chen",
  "body": "We're excited to announce...",
  "tags": ["announcement", "news"]
}

Pridobitev celotnega dokumenta:

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

Pridobitev samo naslova:

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

Pridobitev avtorja:

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

Uporaba parametrov URL-ja

Ko ima stran dinamične poti (na primer /articles/[slug]), lahko z meta.params pridobite parameter URL-ja in ustrezen dokument.

Če nekdo obišče /articles/welcome-post:

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

Tako ustvarite dinamične strani – isti skript CEL deluje za kateri koli članek, pri čemer uporabi vrednost slug iz URL-ja.

Pridobivanje več dokumentov

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

// Pridobi vse države
documents.find("country")

// Pridobi države s filtrom
documents.find("country", { "where": { "code": "us" } })

Prevod

CEL podpira pridobivanje prevedene vsebine dokumentov na dva načina: samodejni prevod na podlagi lokalne nastavitve in izrecno iskanje prevoda.

Samodejni prevod prek meta.locale

Ko je nastavljen meta.locale (na primer iz parametrov poti ali uporabniških nastavitev), documents.get() samodejno združi prevedeno vsebino:

// Če je meta.locale enak "fr", vrne francoski prevod, združen z osnovnim dokumentom
documents.get("greeting", "welcome").headline

Delovanje:

1. Pridobi vsebino osnovnega dokumenta.
2. Če meta.locale ni "en" ali "en-US", poišče prevod v tabeli translations.
3. Prevedena polja združi z osnovno vsebino: { ...baseContent, ...translatedContent }.

Prevedena polja tako preglasijo osnovna polja, neprevedena polja pa se vrnejo iz osnovnega dokumenta.

Izrecni prevod z documents.translated()

Če morate pridobiti določen prevod ne glede na trenutno lokalno nastavitev:

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

// Vedno pridobi španski prevod
documents.translated("greeting", "welcome", "es").headline

// Pridobi prevod na podlagi parametra URL-ja
documents.translated("product", meta.params.id, meta.params.lang).description

Primeri iz prakse

Primer 1: Naslov uvodnega bloka iz drugega dokumenta

Imate blok hero-block, ki mora prikazati naslov iz dokumenta article.

Skript CEL v polju naslova bloka:

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

Rezultat: Uvodni blok prikaže "Build Faster, Ship Smarter".

Primer 2: Ime države iz kode

Ustvarjate stran na /countries/[code] in želite prikazati polno ime države.

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

Ko nekdo obišče /countries/us:

• meta.params.code = "us"
• rezultat: "United States"

Primer 3: Pogojna vsebina glede na lokalno nastavitev

Prikažite različne naslove glede na lokalno nastavitev uporabnika.

meta.locale == "ar-SA" ? "Welcome, everyone" : "Welcome"

Primer 4: Verižno iskanje dokumentov

Dokument article ima polje countryCode, vi pa želite pridobiti polno ime države.

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

Primer 5: Nadomestne vrednosti

Če dokument morda ne obstaja, lahko navedete nadomestno vrednost:

documents.get("article", meta.params.slug) != null
  ? documents.get("article", meta.params.slug).headline
  : "Article Not Found"

Primer 6: Delo s seznami

Če ima članek oznake in želite preveriti, ali obstaja določena oznaka:

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

Za pridobitev prve oznake:

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

Za štetje oznak:

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

Parametrične poti in meta.params

Parametrične poti so ključne za izdelavo dinamičnih, lokaliziranih strani. Ko določite vzorec poti, kot je /{lang}/landingPage, CMS iz URL-ja izlušči parametre in jih omogoči prek meta.params.

Delovanje parametrov poti

Poti uporabljajo sintakso :paramName ali {paramName} za določanje dinamičnih segmentov:

Vsak parameter poti je mogoče povezati s shemo dokumenta za preverjanje veljavnosti.

meta.segments – dostop do surove poti URL-ja

meta.segments zagotavlja surovo pot URL-ja kot polje, kar je uporabno pri dostopu po položaju brez poimenovanih parametrov.

Kdaj uporabiti meta.segments in kdaj meta.params

Popoln pregled objekta meta

Objekt meta vsebuje ves kontekst trenutne zahteve:

meta.params

Parametri poti so vedno nizi. CMS jih pred vrednotenjem preveri glede na povezane sheme:

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

documents.ref() – verižno iskanje

Za čistejšo sintakso, kadar je shema znana, identifikator pa dinamičen:

// Tradicionalni pristop
documents.get("airports", meta.params.code).name

// Uporaba ref() - shema je ločena od dinamičnega identifikatorja
documents.ref("airports").get(meta.params.code).name

Oba pristopa sta enakovredna, vendar ref() jasneje izpostavi dinamični del.

Hiter pregled

Pridobivanje dokumentov

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 spremenljivke

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

Operatorji

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

Pogoste funkcije

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

Sporočila o napakah

Če gre kaj narobe, se lahko prikaže eno od teh sporočil:

Nasveti

1. Uporabite samodokončanje – vnesite documents. ali meta. in urejevalnik bo prikazal možnosti.
2. Začnite preprosto – najprej preizkusite documents.get("schema", "id"), nato dodajte .fieldName.
3. Preverite vrednost null – če dokument morda ne obstaja, dodajte nadomestno vrednost z != null ? ... : ....
4. Ne pridobivajte preveč podatkov – vsak klic documents.get() ali documents.find() šteje v omejitev 50 pridobitev.
5. Dajte prednost meta.params pred meta.segments – poimenovani parametri so preverjeni in zanesljivejši.
6. Za neobvezne parametre uporabite has() – pred dostopom preverite has(meta.params.category).
7. Za dinamične identifikatorje uporabite documents.ref().
8. Za sklicevanje na trenutni dokument uporabite doc.fieldName.

Sklici med dokumenti

Ta razdelek opisuje napredne vzorce za povezovanje dokumentov in izdelavo povezanih vsebinskih struktur.

Osnovni vzorec sklica

Najpreprostejša oblika: en dokument se na drugega sklicuje z identifikatorjem.

// Članek hrani ID avtorja; pridobi ime avtorja
documents.get("author", documents.get("article", "intro").authorId).name

Večnivojski sklici

Globoke povezave lahko ustvarite z veriženjem več iskanj:

// Letališče → država → regija → celina
documents.get("continent",
  documents.get("region",
    documents.get("country",
      documents.get("airport", meta.params.code).countryCode
    ).regionCode
  ).continentCode
).name

Najboljše prakse za sklice

1. Omejite globino verige – vsaka raven poveča zakasnitev in število pridobitev.
2. Predpomnite vmesne rezultate – če isto ugnezdeno vrednost potrebujete dvakrat, nadrejeni dokument pridobite samo enkrat.
3. Uporabljajte preverjanje null – sklici se lahko prekinejo, če so dokumenti izbrisani.
4. Dajte prednost kodam pred UUID-ji – kode so v izrazih berljive in stabilne med okolji.
5. Spremljajte omejitve pridobivanja – zapletene verige lahko hitro dosežejo omejitev 50 pridobitev.

Dodatek A: Celoten primer parametrične poti

Ta vodič ustvari večjezično ciljno stran, dostopno na /{lang}/landingPage.

1. korak: Ustvarite shemo dokumenta greeting

V skrbniškem vmesniku CMS ustvarite shemo po meri z imenom greeting.

2. korak: Ustvarite pozdravne dokumente

Ustvarite dokument za vsak jezik.

3. korak: Ustvarite stran

Ustvarite stran z naslednjo konfiguracijo:

• Pot/vzorec: /{lang}/landingPage
• Stanje: Objavljeno
• Preslikave dinamičnih segmentov: preslikajte lang v komponento language.

4. korak: Dodajte bloke s skripti 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. korak: Uporabite v Next.js

Dodajte univerzalno pot. ParametricRoutePage razreši stran, iz URL-ja izlušči meta.params, na strežniški strani ovrednoti vaše vezave CEL in vsak blok izriše prek registra.

6. korak: Preizkusite poti

Obiščite URL-je in preverite lokalizirano vsebino.

Dodatek B: Tehnični pregled

Vmesnik CelMeta (TypeScript)

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

Algoritem izluščanja parametrov

Funkcija extractParams obdela poti URL-ja tako, da normalizira poti, jih razdeli na segmente, primerja njihovo število, izlušči dinamične segmente ter vrne parametre.

Prednostni vrstni red iskanja dokumentov

Pri pridobivanju prek documents.get(schema, identifier) sistem uporabi naslednji vrstni red:

1. Ujemanje UUID-ja: če je identifikator veljaven UUID, poišče po id.
2. Polje code: preveri polje content.code.
3. Polje slug: preveri polje content.slug.
4. Ujemanje naslova: preveri polje title.

To omogoča prilagodljivo sklicevanje na dokumente s katerim koli enoličnim identifikatorjem.