Подробная документация к библиотеке. Всё о модификациях, расширяющих возможности Тильды — от установки до использования и распространенных ошибок.
Как работает библиотека
Общие механики
Библиотека устанавливается в <head> сайта и автоматически загружает используемые на странице модификации после их вызова в блоках T123. Модификации загружаются асинхронно, чтобы снизить нагрузку на страницу, и запускаются после полной загрузки дерева DOM.
Вызов модификаций осуществляется через функцию вида mod.init(selector, params), где mod — название модификации, init() — метод её инициализации, а selector и params — передаваемые аргументы.
<script>mod.init(selector, params)</script>Синхронизация обновлений
По умолчанию модификации загружаются с CDN-серверов, что позволяет избежать дублирования кода и избавиться от необходимости обновлять его при возникновении ошибок. На данный момент загрузка модификаций возможна с двух источников:
- cdn.postnikovmd.com — оригинальный CDN-ресурс, предоставляемый Selectel. Подходит для большинства проектов — Тильда размещает свои страницы у того же провайдера.
- cdn.jsdelivr.net – альтернативный CDN-ресурс, предоставляемый Cloudflare. Подходит для зарубежных проектов и загружает модификации из независимого репозитория.
Для случаев, когда провайдер блокирует подключение к обоим источникам или в проекте важно избегать любых сбоев, существует альтернативный подход — встроить статичную версию модификации в <head> сайта или в блок T123 непосредственно перед её вызовом.
Такой способ позволяет полностью избавиться от внешних зависимостей и запускать код непосредственно на сайте. Единственный нюанс — обновлять статичные модификации можно только через переустановку кода вручную. Переключиться на статичный режим можно по соответствующей кнопке в первом пункте инструкции к каждому моду.
Генератор кода
Для быстрой настройки модификаций можно использовать генератор кода. Он позволяет получить код инициализации с необходимыми параметрами, указав их в соответствующих полях на странице мода.
При необходимости дополнительной настройки, можно обратиться к разделу документации в конце страницы — в нём указаны все методы, функции и параметры, необходимые для работы мода.
Примеры модификаций
Все возможности библиотеки собраны в каталоге примеров — больше 90 готовых страниц, от базовых слайдеров, вкладок и аккордеонов до комбинаций нескольких модов и продвинутых сценариев. Любой пример можно скопировать к себе как готовый шаблон и разобрать, как он устроен.
Подробнее: Каталог примеров
Диагностика и просмотр ошибок
Ошибки, возникающие при установке модификаций, можно посмотреть через параметр ?showerrors в конце ссылки на страницу: https://example.com?showerrors. Дианостика собирает их в едином окне – по клику на ошибки можно посмотреть детальную информацию о проблеме и получить рекомендации по её исправлению.
Для большинства ошибок диагностика также отображает связанные параметры (например, если слайдер не листается, диагностика покажет нужный класс и количество слайдов внутри него), а также позволяет посмотреть полные параметры модификации: от классов до внутренних состояний.
Данная функция работает на любом сайте с установленной библиотекой.
Расширение для браузера
Расширение добавляет модификации в привычный интерфейс редактора и позволяет получить к ним быстрый доступ:
- Добавляет в редактор Тильды вкладку «Модификации» с полным каталогом библиотеки, видео-превью, поиском и вставкой кода на сайт.
- Отображает информацию о модификациях в блоках и подсказывает, где посмотреть их инструкцию/документацию.
- Показывает ошибки и рекомендации по их исправлению прямо на сайте — аналог ?showerrors, но без необходимости добавлять его к ссылке.
Расширение работает только в Тильде и на сайтах с установленной библиотекой, не собирает и не передаёт данные и совместимо с плагинами других авторов.
Подробнее: Расширение Chrome
Особенности библиотеки
Все модификации разработаны для Тильды и учитывают её особенности и ограничения.
- Модификации написаны на чистом JavaScript и загружаются в минифицированном виде. Вес установочного скрипта составляет 17 Кб, а весь остальной код подгружается по мере вызова модов.
- При сбое подключения к основному CDN моды загружаются с альтернативного источника, поэтому библиотека продолжит работать, даже если основной сервер недоступен.
- В большинстве случаев модификации совмещаются друг с другом автоматически. При необходимости их порядок можно задать вручную через пользовательские события — например, чтобы связать их со сторонним кодом.
- Модификации учитывают все особенности Тильды и аккуратно встраиваются в неё, используя нативные функции для поддержки масштабирования, автолэйаутов и анимаций.
- Библиотека регулярно обновляется под изменения Тильды, чтобы модификации продолжали работать после обновлений платформы.
- Код модификаций распространяется свободно по лицензии MIT — его можно использовать в любых проектах с указанием авторства.
Модификации
Всего в библиотеке 36 уникальных модификаций, каждая из которых закрывает свою функциональную область. Модификации сгруппированы в 4 кластера:
Функционал и компоненты
Ключевой кластер — компоненты с настраиваемым поведением, состояниями и анимацией — слайдеры, вкладки, аккордеоны, хэдеры, формы, поп-апы и др. Они закрывают основной функционал сайтов и позволяют реализовать его в кастомной логике.
Анимации и эффекты
Модификации, добавляющие элементам визуальные эффекты и микровзаимодействия. Запускаются по наведению, клику или прокрутке — с их помощью можно расставить визуальные акценты и показать отклик на действия пользователя прямо в Zero-блоке.
Личный кабинет
Помимо отдельных модификаций, в библиотеку входят два крупных модуля — Личный кабинет и Интернет-магазин. Каждый из них состоит из нескольких модификаций и инициализируется через своё ядро.
Личный кабинет позволяет собрать свои страницы авторизации, профиля, курсов и истории заказов из Zero-блока, которые работают поверх стандартного функционала Тильды. В отличие от остальных модификаций, он подключается отдельным скриптом members.min.js и работает автономно — как вместе с mods.min.js, так и без него:
<script src="https://cdn.postnikovmd.com/tilda@1.6/members.min.js"></script>Интернет-магазин
Интернет-магазин позволяет перенести каталог и карточку товара в Zero-блок со своей вёрсткой и синхронизацией данных в реальном времени. Модуль добавляет продвинутую логику общения с API Тильды — модификация сама достаёт и обрабатывает товары с сервера, а также вводит гибкую систему клонирования карточек, которая сохраняет оригинальную структуру и позволяет добавлять в блок неограниченное количество товаров.
Начало работы
Установка библиотеки
Для работы модификаций необходимо подключить библиотеку в <head> сайта. Скрипт устанавливается только один раз и автоматически загружает нужный мод при вызове функции. Актуальная версия библиотеки – 1.6.
<script src="https://cdn.postnikovmd.com/tilda@1.6/mods.min.js"></script>Альтернативный способ установки предполагает встраивание исполняемого кода непосредственно перед инициализацией модификации. Подробнее: Синхронизация обновлений в модификациях
Дальнейшая настройка производится по инструкции к каждому моду.
Инициализация модификаций
Для того, чтобы установочный скрипт загрузил модификацию, её нужно инициализировать в коде. Это делается при помощи вызова функции init():
<script>mod.init(selector, params)</script>В данном примере mod – название выбранной модификации, init() – функция его инициализации, а selector и params – передаваемые в неё аргументы.
Если модификация вызывается для блоков, которые скрыты настройками видимости, её выполнение будет пропущено. Подробнее о функциях инициализации можно прочитать в детальной документации к каждому моду.
Совмещение нескольких модов
Пользовательские события позволяют управлять последовательностью инициализации модификаций и используются для совмещения нескольких модов или стороннего кода. По умолчанию библиотека автоматически определяет порядок запуска — например, встроить слайдер во вкладки можно при обычном вызове двух функций.
Пользовательские события нужны для более тонкой настройки — их можно использовать, чтобы:
Запустить мод по срабатыванию события
Отложить инициализацию модификации можно с помощью параметров event и timeout. Например, запустить слайдер через 100ms после срабатывания customEvent можно таким образом:
Отложить инициализацию модификации можно с помощью параметров event и timeout. Например, запустить слайдер через 100ms после срабатывания customEvent можно таким образом:
slider.init(".uc-slider", { event: "customEvent", timeout: 100 })Если модификация должна запуститься после срабатывания сразу нескольких событий, достаточно перечислить их через запятую: event: "customEvent1, customEvent2, customEvent3".
Запустить сторонний код после отрисовки модификации
Если код нужно выполнить после того, как модификация полностью запустится, добавьте слушатель события modinit-id, где modinit – событие отрисовки модификации mod, id – передаваемый в качестве аргумента selector без префикса uc или rec. Например, если у блока со слайдером класс .uc-slider1, то слушатель события добавляется следующим образом:
Если код нужно выполнить после того, как модификация полностью запустится, добавьте слушатель события modinit-id, где modinit – событие отрисовки модификации mod, id – передаваемый в качестве аргумента selector без префикса uc или rec. Например, если у блока со слайдером класс .uc-slider1, то слушатель события добавляется следующим образом:
window.addEventListener("sliderinit-slider1", function(){ ... })Запустить другую модификацию после отрисовки первой
Логика работы пользовательских событий одинакова для всех модификаций и помогает интегрировать их друг с другом. Например, запустить переворот карточек после отрисовки слайдера можно через событие sliderinit:
Логика работы пользовательских событий одинакова для всех модификаций и помогает интегрировать их друг с другом. Например, запустить переворот карточек после отрисовки слайдера можно через событие sliderinit:
flip.init(".flip-slide", { event: "sliderinit-slider" })Распространенные проблемы
Ни одна модификация не работает
Данная проблема может возникать по нескольким причинам:
Провайдер блокирует подключение к модификациям
На данный момент единственный способ обхода блокировки — отключить синхронизацию обновлений и использовать статичную версию модов. Она полностью встраивается в код сайта и не зависит от внешних ресурсов.
На данный момент единственный способ обхода блокировки — отключить синхронизацию обновлений и использовать статичную версию модов. Она полностью встраивается в код сайта и не зависит от внешних ресурсов.
Подробнее: Синхронизация обновлений
Между модификациями возникает конфликт версий
Если в <head> сайта установлено сразу несколько установочных скриптов mods.min.js, они могут нарушать работу друг друга. То же самое касается случаев, когда такие скрипты имеют разные версии. Для решения проблемы необходимо оставить в <head> один установочный скрипт и убедиться, что его версия является актуальной.
Если в <head> сайта установлено сразу несколько установочных скриптов mods.min.js, они могут нарушать работу друг друга. То же самое касается случаев, когда такие скрипты имеют разные версии. Для решения проблемы необходимо оставить в <head> один установочный скрипт и убедиться, что его версия является актуальной.
Возникает конфликт со сторонним кодом
Модификации, переопределяющие стандартные функции t_onReady и t_onFuncLoad, будут конфликтовать с библиотекой. Также не допускается изменение объектов, содержащих исполняемые функции модификаций. Если такая проблема возникла, поможет поблочное отключение стороннего кода, чтобы выявить источник конфликта.
Если при установке возникли другие ошибки
Добавьте параметр ?showerrors в конец ссылки, чтобы увидеть ошибки и рекомендации по их исправлению. Данная функция работает на любом сайте с установленной библиотекой.
Если диагностика на сайте не помогла, распространенные ошибки и способы их решения можно также посмотреть в документации к каждому моду.
