Разработчику: основы кастомизации (JS / HTML / CSS)

Этот раздел — для сторонних разработчиков, которые через панель пользовательского кода в личном кабинете расширяют PlanPlace своим JavaScript, HTML и CSS. Здесь предполагается знание соответствующего языка. Если вы не пишете код — это не для вас; обычная настройка доступна без программирования.

Перед началом. Сделайте резервную копию, тестируйте на отдельном аккаунте/проекте и всегда проверяйте результат на сцене с жёсткой перезагрузкой. Ошибка в custom.js может сломать загрузку сцены.

Где живёт ваш код

Панель пользовательского кода сохраняет введённое в три файла рядом со сценой:

assets/custom.js — ваш JavaScript;
assets/custom.css — ваши стили;
assets/custom.html — произвольная HTML-разметка.

(Отдельный custom_admin.js относится к админ-панели, а не к сцене.)

Куда они попадают на странице сцены:

custom.html вставляется в конец <body> — можно добавлять свои блоки, шаблоны, контейнеры для модалок.
custom.css подключается последним <link> — ваши правила перекрывают стили сцены.
custom.js подключается обычным <script> раньше основного движка сцены.

Важно: точка входа — событие `PP_ready`

Поскольку custom.js грузится до скриптов движка, в момент его разбора главных объектов сцены ещё нет. Нельзя писать логику «в лоб» в теле файла — будет ошибка «переменная не определена».

Правильно — дождаться готовности сцены. Движок в конце инициализации диспатчит DOM-событие PP_ready, передавая ссылку на главный объект API:

document.addEventListener('PP_ready', function (e) {
    const pp = e.detail.pp; // главный объект API
    // здесь весь ваш код
    console.log('PlanPlace готов, ядро:', pp.core);
});

Это самый надёжный способ. Всё, что описано в этом разделе, пишите внутри обработчика PP_ready.

Главный объект `pp`

pp — это точка доступа ко всему API сцены. Берите его из e.detail.pp (он доступен по имени, а не как window.pp). Основные ветки:

pp.core — версия ядра (для версии 2.0 это 2).
pp.libs — все библиотеки каталога: материалы/декоры, модули, фасады, ручки, столешницы, фурнитура и т. д. У каждой есть методы get_item(id), find_item(...), get_category(...). Например, pp.libs.decors.find_item(id) вернёт декор по идентификатору.
pp.events — система хуков (точки, куда можно вклиниться в логику). Подробно — ниже и в отдельных статьях раздела.
pp.interface.root — корневой Vue-инстанс интерфейса. Через него показывают модальные окна и уведомления.
pp.spec_settings — настройки цен (включены ли цены, наценки).
pp.project_settings — данные текущего проекта.

Для своих данных в проекте есть пара функций: set_custom_userdata(data) и get_custom_userdata() — они сохраняются вместе с проектом. Итоговую цену проекта отдаёт get_price_total().

Хуки: как вклиниться в логику

Хуки в PlanPlace — это именованные слоты-функции. Вы присваиваете свою функцию в нужный слот pp.events.<группа>.<имя>, и движок вызовет её в соответствующий момент. Примеры групп:

pp.events.global — общие моменты: after_scene_load (проект загружен) и др.
pp.events.cabinet — спецификация и цена: before_create_spec_item, after_create_spec_item, get_specs_end (см. «Спецификация и артикулы»).
pp.events.module — события модуля: before_build, after_build.
pp.events.custom — именованные обработчики уровня отдельного элемента: вы регистрируете pp.events.custom['мой_обработчик'] = fn, а в админ-настройках элемента (вкладка «События») указываете имя мой_обработчик. Точные ключи событий элемента — on_before_params, on_before_build, on_after_build, on_drag_end (см. «Условия отображения и события»).

Пример — выполнить код после загрузки проекта:

document.addEventListener('PP_ready', function (e) {
    const pp = e.detail.pp;
    pp.events.global.after_scene_load = function () {
        console.log('Проект загружен на сцену');
    };
});

Осторожно с хуками спецификации. Если вы задали хотя бы один хук спецификации (before_create_spec_item / after_create_spec_item и т. п.), движок отключает автоматический раскрой материалов по вариантам, чтобы не мешать вашей логике. Это нормально и сделано намеренно.

CSS и HTML

CSS (custom.css) — скрывайте лишние элементы, меняйте оформление под фирменный стиль. Ваши правила идут последними, поэтому перекрывают стандартные. Для надёжности используйте конкретные селекторы.
HTML (custom.html) — кладите сюда контейнеры и шаблоны, к которым обращается ваш JS (например, разметку собственной модалки или панели).

Что дальше — статьи раздела

«Справочник API core_2» — полный перечень доступных объектов и методов: pp.libs, доступ к проекту, спецификации, цене, состоянию сцены и интерфейсу.
«Модальные окна и уведомления» — как показать диалог, произвольную модалку и уведомление дизайнеру.
«Спецификация и артикулы: модификация на лету» — как изменить позиции спецификации, цену и артикул, в том числе в PDF и Excel.
«Артикул из комбинации параметров» — практический сценарий: цена по уникальному артикулу «модуль + размер + цвет» и «фрезеровка + размер + декор».

Коротко

Ваш код хранится в assets/custom.js / custom.css / custom.html. JS подключается до движка, поэтому всю логику оборачивайте в document.addEventListener('PP_ready', e => { const pp = e.detail.pp; ... }). Объект pp даёт доступ к библиотекам каталога (pp.libs), хукам (pp.events), интерфейсу (pp.interface.root) и проекту. Вклинивание в логику — через присваивание функций в слоты pp.events.<группа>.<имя>.