Скрипти у конструкторі шаблонів

Практичний посібник із написання виразів 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 : "Draft: " + doc.title

Об’єкт doc містить усі значення полів документа, який редагується. Це корисно для:

• Обчислюваних полів (наприклад, doc.price * doc.quantity)
• Умовної логіки відображення на основі стану документа
• Виразів у стилі валідації

Отримання документів

Найпотужніша можливість CEL — отримання документів із будь-якого місця вашої CMS.

Отримання одного документа

Синтаксис: documents.get(schemaName, identifier)

Припустімо, у вас є документ article, збережений з ідентифікатором "welcome-post":

// Збережено в CMS як: article / welcome-post
{
  "headline": "Welcome to Our Platform",
  "author": "Sarah Chen",
  "body": "We're excited to announce...",
  "tags": ["announcement", "news"]
}

Щоб отримати весь документ:

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

Повертає:

{
  "headline": "Welcome to Our Platform",
  "author": "Sarah Chen",
  "body": "We're excited to announce...",
  "tags": ["announcement", "news"]
}

Щоб отримати лише заголовок:

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

Повертає: "Welcome to Our Platform"

Щоб отримати автора:

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

Повертає: "Sarah Chen"

Використання параметрів URL

Якщо ваша сторінка має динамічні маршрути (наприклад, /articles/[slug]), можна використовувати meta.params, щоб отримати параметр URL і завантажити потрібний документ.

Якщо хтось відвідує /articles/welcome-post:

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

Повертає: "Welcome to Our Platform"

Так створюються динамічні сторінки — той самий сценарій CEL працює для будь-якої статті, використовуючи значення slug із URL.

Отримання кількох документів

Синтаксис: documents.find(schemaName) або documents.find(schemaName, filter)

// Отримати всі країни
documents.find("country")

Повертає:

[
  { "code": "us", "name": "United States", "flag": "US" },
  { "code": "sa", "name": "Saudi Arabia", "flag": "SA" },
  { "code": "gb", "name": "United Kingdom", "flag": "GB" }
]

// Отримати країни з фільтром
documents.find("country", { "where": { "code": "us" } })

Повертає:

[
  { "code": "us", "name": "United States", "flag": "US" }
]

Переклади

CEL підтримує отримання перекладеного вмісту документів двома способами: автоматичний переклад на основі локалі та явний пошук перекладу.

Автоматичний переклад через 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()

Якщо потрібно отримати певний переклад незалежно від поточної локалі:

Синтаксис: 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. Користуйтеся автодоповненням — введіть documents. або meta., і редактор покаже доступні параметри
2. Починайте з простого — спочатку протестуйте documents.get("schema", "id"), а потім додайте .fieldName
3. Перевіряйте null — якщо документа може не існувати, додайте запасне значення через != null ? ... : ...
4. Не отримуйте зайві дані — кожен виклик documents.get() або documents.find() враховується в ліміті 50 отримань
5. Надавайте перевагу meta.params перед meta.segments — іменовані параметри перевіряються й є надійнішими
6. Використовуйте has() для необов’язкових параметрів — перевіряйте has(meta.params.category) перед доступом
7. Використовуйте documents.ref() для динамічних ідентифікаторів — це зрозуміліший синтаксис, коли схема статична, а ідентифікатор динамічний
8. Використовуйте doc.fieldName для посилань на поточний документ — отримуйте поля поточного документа в обчислюваних виразах