Общая информация

Виджет представляет собой асинхронное JavaScript-приложение, которое работает на стороне вашего сайта и общается с Timepad по API. Виджет устроен таким образом, чтобы ни в коем случае не замедлять скорость загрузки ваших страниц и не конфликтовать с теми стилями и скриптами, которые уже используются у вас на сайте (см. подраздел «Как отображается виджет»).

В зависимости от настроек, виджет может быть вставлен либо в виде формы прямо в теле страницы, либо в виде попап-окна, открывающегося при нажатии на кнопку.

Кастомизация виджета 

Любой виджет из Timepad можно индивидуально настроить и изменить ему как внешний вид, так и поведение. 

Кастомизация на стороне TimePad 

Наборы настроек, шаблонов, стилей и кодов виджета на стороне Timepad мы для себя (и далее в этом руководстве) называем «кастомизациями» или просто «кастомами».

Такие кастомизации создаются и поддерживаются нашими сотрудниками. При этом вам не нужно менять код вставки виджета, даже если изменения делаются на уже запущенном в продажу событии.

Кастомизации хранятся в базе данных Timepad и подключаются к каждому виджету через уникальный ID кастомизации. Если вы не указали ID кастомизации самостоятельно (об этом написано в разделе «Как устроен код вставки»), значит, к виджету была применена кастомизация по умолчанию. Стандартные шаблоны, стили, скрипты и так далее.

При этом события и кастомизации связаны не жестко. Одну кастомизацию можно подключить к разным событиям, а к одному событию в разных условиях можно применять разные кастомизации (например, если у вас два разных сайта с разным дизайном, на которых вы публикуете одни и те же события).

Внимание! В некоторых случаях кастомизации могут полагаться на специфические настройки события. Если сотрудниками Timepad для вас была разработана персональная кастомизация, перед ее подключением к другому событию (и уж тем более — к другой организации, если у вас их несколько) лучше уточните ее ограничения и особенности в службе поддержки (support@timepad.ru). Для этого пришлите ссылку на событие и ID кастомизации.

Кастомизация на вашей стороне 

Однако вы и сами можете менять внешний вид и поведение виджета, располагая измененный код у себя на сайте, неподалеку от кода вставки. В частности, менять стили, редактировать тексты (включая локализацию), и верстать свой html (используя шаблоны Mustache). 

Впрочем, сперва советуем сориентироваться, где что.

Вы также можете использовать jQuery, чтобы манипулировать виджетом напрямую.

Прежде чем обращаться к виджету через jQuery, обязательно прочтите эту инструкцию.

Архитектура

В сильно упрощенном варианте современные виджеты TimePad состоят из следующих частей:

• Загрузчик (loader)
• JQuery, mustache и easyXDM как дополнительные библиотеки
• Код виджета
• Темплейты (шаблоны) на mustache
• Файлы локализации
• less-таблицы стилей
• Файл описания моделей данных

Виджет использует упрощённый MVC.

• В коде виджета обозначаются «роуты», например, форма регистрации, страничка с вариантами оплаты, страничка сообщения об успешной регистрации.
• Роутам по названию сопоставляются шаблоны, написанные на mustache.
• В качестве модели используется JS-объект, который достаточно просто изменяется и дополняется данными. Он целиком кидается в mustache.

Как отображается виджет (ответ: через iframe)

Чтобы у css и js не возникало конфликтов с сайтом-потребителем, все отображение происходит в src-less iframe. Если виджету необходимо отобразить попап, то для него создается отдельный iframe. Целевой элемент, окно и документ для отрисовки иногда меняются по ходу работы виджета, то есть происходит переключение контекста.

Именно из-за того что виджет живет своей асинхронной жизнью в разных айфреймах с непредсказуемым названием, нельзя надежно добраться до его элементов просто вызвав доллар-функцию jQuery. Чтобы что-то делать, нужно вешаться на события виджета  (и, повторимся, уточнить, как работать с jQuery.

Как загружается виджет

1. Загружается loader
2. loader ищет коды вставки виджетов, и на каждый из них
   2.1 Создает область отрисовки на месте кода вставкиЗагружает код нужного виджета
   2.2. Загружает библиотеки нужного виджета
   2.3. Загружает пакет кастомизаций, если он указан в коде вставки (атрибут data-timepad-customized)
   2.4. Собирает настройки
   2.5. Создаёт src-less iframe
   2.6. Возникает событие switchedToNewRenderTarget
   2.7. Запускает код виджета, переходя на роут по умолчанию

Как модифицировать стандартное поведение и добавить свое, будет рассказано дальше в этом руководстве.