Фреймы
Фрейм — HTML-верстка страницы или ее части. Сайт на OnPress целиком состоит из фреймов. Шаблон статьи, шапка и подвал, блок вопросов и ответов, лендинг главной или встроенное приложение — это все отдельные фреймы. Вы загружаете их на сайт и правите как обычный код. Фреймы загружает, читает, меняет и ставит на страницы один эндпоинт /frames.
AI-агенту не нужно разбираться в скрытой логике шаблонов, потому что API хранит фрейм ровно таким, каким агент его прислал. Значения платформа подставляет только при сборке страницы: в вызовы фреймов и в поля данных. Агент правит один фрейм, а платформа сама пересобирает все страницы, где этот фрейм стоит.
Во всех примерах API — https://onpress.pro/api/v2, SITE — id сайта (SITE_ID), OP_TOKEN — токен op_XXXX. Полный перечень эндпоинтов — в справочнике API.
Зачем они нужны
Допустим, в шапке нужно поменять логотип и порядок ссылок. Агент читает фрейм site__header, правит разметку и записывает ее обратно, и новая шапка появляется на всех страницах сайта.
Другой пример — готовый лендинг одним HTML-файлом. Агент загружает его фреймом и ставит на страницу, а платформа добавляет к нему SEO-разметку, счетчики аналитики и hreflang.
А если странице нужен калькулятор или доска задач, агент кладет рядом с разметкой фрейма script.js. Скрипт работает в браузере посетителя и через объект onpress.data читает и записывает данные сайта от имени вошедшего администратора. Так устроены приложения.
Имя фрейма
Имя фрейма — слаг по схеме БЭМ: блок__элемент--модификатор. Блок site объединяет общее для всего сайта, остальные блоки называйте по сущности, которой они служат: article, docs, landing. Элемент — часть блока, модификатор — ее вариант, слова внутри части соединяйте одиночным дефисом. Например:
| Слаг | Блок | Элемент | Модификатор |
|---|---|---|---|
article | article | — | — |
article__faq | article | faq | — |
article__faq--simple | article | faq | simple |
site__header | site | header | — |
site-simple__header | site-simple | header | — |
Загрузить фрейм
POST /frames загружает новый фрейм и сразу собирает его. Например, шапка с названием сайта и меню:
curl -s -X POST "$API/site/$SITE/frames" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"slug": "site__header", "html": "<header class=\"site-header\"><span>{{site.name}}</span><!-- frame/menu {\"place\":\"header\"} /--></header>"}'
API хранит разметку байт в байт, вместе с комментариями и встроенными <script>. JSON в значении атрибута, например в data-op-repeat, пишите в одинарных кавычках, иначе первая двойная кавычка оборвет атрибут. Разметка одного фрейма — до 2 МБ, стили и скрипты вынесите в файлы фрейма. Если слаг занят, замените разметку через PUT.
Прочитать
GET /frames возвращает список фреймов сайта без разметки, а GET /frames/{ref} — один фрейм с разметкой по слагу или id. Например, шапка сайта:
curl -s "$API/site/$SITE/frames/site__header" -H "Authorization: Bearer $OP_TOKEN"
Кроме разметки, в ответе есть pages — id страниц, на которых стоит фрейм, referenced_by — фреймы, которые его вкладывают, и preview_page — первая опубликованная страница, где фрейм виден посетителю.
Изменить разметку
PUT /frames/{ref} заменяет разметку целиком, а файлы фрейма не трогает. Например, шапка без меню:
curl -s -X PUT "$API/site/$SITE/frames/site__header" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"html": "<header class=\"site-header\"><span>{{site.name}}</span></header>"}'
После записи API пересобирает фреймы, которые вкладывают этот, и перечисляет их в rebaked. Если фрейм был системным, правка делает его пользовательским, подробнее — в разделе «Типы».
Переименовать
PATCH /frames/{ref} меняет слаг фрейма, другие поля он не правит. Например:
curl -s -X PATCH "$API/site/$SITE/frames/shapka-sajta" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"slug": "site__header"}'
API заменяет старый слаг во всех вставках этого фрейма: и в других фреймах сайта, и в тексте страниц. Остальную разметку и текст API не трогает, а измененные фреймы и страницы пересобирает.
Поставить на страницу
Своего адреса у фрейма нет, посетитель видит его только на странице, на которую вы его поставили. У страницы ровно один фрейм, и новый заменяет прежний. Поставьте фрейм свойством frame при публикации страницы, ключом frame в теле PATCH /pages/{ref} или запросом со стороны фрейма. Например, оболочка статьи на странице «Тарифы»:
curl -s -X POST "$API/site/$SITE/frames/article/assign" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"page": "/tarify/"}'
С "clear": true тот же запрос снимает фрейм со страницы. Ключ static в ответе показывает, что стало со статической копией страницы, о копиях подробно рассказывает страница «Сборка и копии».
Вложить фрейм во фрейм
Фреймы связывает один механизм — вызов <!-- frame/имя /-->, где имя — слаг или id фрейма. Например, оболочка лендинга с общей шапкой и подвалом:
<!-- frame/site__header /-->
<main class="landing">
<h1>{{page.title}}</h1>
<!-- frame/landing__features /-->
</main>
<!-- frame/site__footer /-->
Ту же строку вы пишете и прямо в тексте страницы, например чтобы поставить в статью врезку или видео. Вложенный фрейм получает ту же страницу и тот же язык, что и внешний. Платформа выводит до 8 уровней вложения и до 64 вызовов фреймов за одну сборку, а фрейм, который уже стоит выше по цепочке, второй раз не выводит, поэтому кольцо вызовов не вешает страницу. Если вложенного фрейма на сайте нет, вызов выводит пустое место. Повторитель с "empty":"frame" убирает весь фрейм, когда его список пуст, подробно — в справочнике «Повторитель».
Чтобы у лендингов была другая шапка, сделайте отдельную оболочку, которая вызывает другой фрейм шапки, например site-simple__header. Текст страницы, списки и условия во фрейме вы ставите атрибутами data-op-* из раздела «Поля данных», а готовые фреймы для текста страницы описывает раздел «Готовые фреймы».
Параметры
Вызов передает фрейму параметры — все ключи JSON после имени, кроме служебных name, ref, frame, slug, id и class. Внутри фрейма параметр доступен как frame.<ключ>. Например, кнопка с текстом из вызова:
<!-- вызов на странице -->
<!-- frame/site__cta {"label":"Попробовать бесплатно"} /-->
<!-- разметка фрейма site__cta -->
<a class="site-cta" href="/signup/">{{frame.label}}</a>
Через параметр вызов называет и данные для повторителя, поэтому фрейм с data-op-repeat="frame.source" выводит тот набор, который выбрал вызов. Все правила вызова описывает справочник «Вставка фрейма», готовые фреймы с параметрами — справочник «Готовые фреймы», а как переделать готовый фрейм под себя, рассказывает страница «Свой фрейм из готового».
Содержимое
Парная вставка <!-- frame/имя -->…<!-- /frame --> передает фрейму содержимое — markdown между этими строками. Фрейм выводит содержимое вставки атрибутом data-op-html="frame.content" на нужном теге или разбирает его на вопросы и ответы, как фрейм faq. Например, врезка с текстом из вставки:
<!-- вставка на странице -->
<!-- frame/callout--info -->
Новые тарифы действуют с 1 ноября.
<!-- /frame -->
<!-- разметка фрейма callout--info -->
<aside class="callout callout--info" data-op-html="frame.content"></aside>
Готовые фреймы с текстом внутри перечисляет справочник «Готовые фреймы», все правила содержимого — справочник «Вставка фрейма».
Готовые фреймы
На новом сайте уже есть готовые фреймы для текста страницы: вопросы и ответы, врезки, шаги, кнопки, карточки, вкладки и видео. Чтобы поставить такой фрейм, напишите в тексте страницы одну строку вставки, а цвета и шрифты фрейм возьмет из стилей сайта. Например, вопросы и ответы в конце статьи:
<!-- frame/faq -->
### Сколько это стоит?
Бесплатно на любом тарифе.
### Нужна ли карта?
Нет, карта нужна только для платного тарифа.
<!-- /frame -->
Каждый заголовок H3 станет вопросом, текст под ним — ответом, который посетитель открывает кликом:

Врезка выделяет важное цветной плашкой, цвет задает имя фрейма, а заголовок — параметр title:
<!-- frame/callout--warning {"title":"Проверьте перед отправкой"} -->
В черновике могут быть неверные имена и даты.
<!-- /frame -->

Кнопки фрейм buttons берет из списка в параметрах вставки, у каждой кнопки надпись, адрес и вид:
<!-- frame/buttons {"data":{"items":[{"text":"Начать бесплатно","link":"/signup/","class":"btn btn--icon-after","icon":"arrow_forward"},{"text":"Тарифы","link":"/pricing/","class":"btn btn--outline"}]}} /-->

Все готовые фреймы со снимками, параметрами и примерами перечисляет справочник «Готовые фреймы».
Поля данных
Поля данных подставляют во фрейм значения страницы, сайта или параметров вставки: название страницы в заголовок, рубрику в ссылку. Напишите имя поля в двойных фигурных скобках прямо в тексте тега или в значении атрибута, в том числе рядом с обычным текстом:
<h1>{{page.title || Заголовок страницы}}</h1>
<a class="tag tag--{{page.category_slug || none}}" href="{{page.category_url}}">{{page.category_name || Без рубрики}}</a>
Текст после || — заглушка: ее показывает превью в консоли, а на странице она появляется, если у поля нет значения. Пробелы вокруг || и по краям скобок OnPress не учитывает. На странице «Тарифы» в рубрике «Цены» получится <h1>Тарифы</h1> и ссылка на рубрику с текстом «Цены».
Атрибуты data-op-* на теге показывают его по условию, повторяют для каждого элемента набора или вставляют в него HTML. Например, подзаголовок со строчным markdown появится, только если он есть у элемента:
<p class="hero__lead" data-op-md="item.lead" data-op-if="item.lead">Подзаголовок</p>
Поля и атрибуты работают и в разметке фрейма, и в тексте страницы. Все поля и правила описывает страница «Поля данных».
Файлы фрейма
Стили и скрипты фрейма лежат рядом с разметкой, в файлах style.css, script.js и других .css и .js, до 16 файлов по 512 КБ. Имя файла передайте параметром name. Например, стили шапки:
curl -s -X PUT "$API/site/$SITE/frames/site__header/files?name=style.css" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"content": ".site-header{display:flex;gap:24px}\n"}'
Стили всех фреймов страницы платформа собирает в один блок <style> в конце <head>, а скрипт каждого фрейма подключает отдельным файлом перед </body>. Правка файла, как и правка разметки, делает системный фрейм пользовательским. Картинки и шрифты загрузите в медиатеку и ссылайтесь на них по адресу. В скрипте фрейма есть объект onpress.data: если посетитель вошел на сайт администратором, скрипт читает и меняет через него данные сайта с правами этого посетителя. Подробно — в разделе «Запись администратором».
Типы
Фреймы бывают системные и пользовательские. Системные приходят из общей библиотеки OnPress, и новый сайт получает все фреймы системными. Когда в библиотеке выходит новая версия системного фрейма, сайт сразу выводит ее, а страницы с этим фреймом пересобираются сами.
Если изменить у системного фрейма разметку, файлы или слаг, он станет пользовательским: ваша правка останется, а новые версии из библиотеки до него больше не дойдут. О том, что вышла версия новее, скажет поле system_update_available. Фреймы, которые вы загрузили сами, тоже пользовательские, даже если слаг у них такой же, как у системного, и библиотека их не обновляет.
Чтобы вернуть измененный фрейм к системной версии, сбросьте его — правки сайта пропадут. Например, шапку:
curl -s -X POST "$API/site/$SITE/frames/site__header/reset" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' -d '{}'
Фрейм, который вы загрузили сами со слагом системного, сбросом не вернуть: замените его системным через POST /frames/{ref}/revert.
Как узнать тип фрейма и поставить фрейм из библиотеки, описывает справочник.
Удалить
DELETE /frames/{ref} удаляет фрейм вместе с файлами и снимает его со всех страниц. Например, раздел вопросов статьи:
curl -s -X DELETE "$API/site/$SITE/frames/article__faq" -H "Authorization: Bearer $OP_TOKEN"
Страницы, с которых API снял фрейм, начинают отвечать 404, их id приходят в unbound_pages. Поэтому сначала поставьте на них другой фрейм. Фреймы, которые вкладывали удаленный, API не правит и называет в referenced_by, их вызов выводит пустое место, пока фрейм с таким слагом не появится снова.
Фрейм — целый документ
Фрейм может быть полным HTML-документом с <!doctype html>, <head> и <body>, например готовым лендингом. Платформа отдает страницу с таким фреймом как обычную страницу сайта и добавляет в ее <head> и <body> SEO-разметку (canonical, robots, Open Graph, JSON-LD), иконки, счетчики аналитики и hreflang. Заполненные у страницы seo_title и seo_description заменяют <title> и description из разметки, а пустые оставляют авторские.
У фрейма-документа два правила. Не вкладывайте его в другой фрейм, иначе страница получит второй <body>. Держите его независимым от страницы, без текста страницы, полей данных с page.* и прочего из списка на странице «Сборка и копии». Тогда платформа отдает страницу статической копией, а фрейм-документ, который зависит от страницы, платформа вкладывает в документ темы, и страница получает два <html>. Как опубликовать лендинг целиком, рассказывает отдельная страница.
Вопросы и ответы
Чем фрейм отличается от iframe?
Фрейм выводит свою разметку прямо в страницу, а iframe показывает другую страницу во встроенном окне.
Почему на месте вложенного фрейма пусто?
Чаще всего такого фрейма на сайте нет, и отчет о загрузке называет его в frame_refs_missing. Поставьте фрейм из библиотеки или загрузите пользовательский фрейм с этим слагом. Еще одна причина — повторитель с "empty":"frame", у которого пустой список.
Как перенести фрейм на другой сайт?
Фреймы одного сайта другим сайтам не видны. Прочитайте фрейм через GET /frames/{ref} на одном сайте и загрузите через POST /frames на другом, а файлы фрейма перенесите так же, по одному.
Можно ли писать комментарии в коде фрейма?
Да. API хранит комментарии в разметке, стилях и скриптах как есть, и на странице они остаются. Исключение — css-файлы фрейма: на страницу уходит их сжатая копия без комментариев, кроме /*! … */.
Где коды ошибок?
В справочнике API. Ответ с ошибкой сам называет причину.