Плагин tgm4page: интеграция страниц Cotonti с Telegram

Полное руководство по установке, настройке и использованию

Автор: webitproff
Репозиторий c открытым исходным кодом скачать бесплатно

Оглавление

1. Введение
2. Основные возможности
3. Архитектура и структура файлов
4. Установка плагина
5. Настройка Telegram
6. Настройка плагина через админ-панель Cotonti
7. Размещение тегов в шаблонах
8. Работа плагина: добавление, редактирование и удаление страниц
9. Виджет обсуждения на странице сайта
10. Хранение настроек и данных
11. Пошаговый сценарий использования
12. Репозиторий и поддержка
13. Заключение

Введение

tgm4page — плагин для системы управления контентом Cotonti CMF, предназначенный для полной интеграции страниц вашего сайта (модуль Pages) с мессенджером Telegram. Он автоматически публикует информацию о новых и изменённых страницах в ваш Telegram-канал и встраивает на каждую страницу официальный виджет обсуждения Telegram. Это позволяет вашим подписчикам оперативно узнавать о новом контенте, а посетителям сайта — видеть и оставлять комментарии (через Telegram) прямо на странице.

Плагин избавляет вас от ручной публикации постов и модерирования комментариев на сайте: всё происходит автоматически, а обсуждения остаются в привычной среде Telegram.

Основные возможности

• Автоматическая публикация при создании новой страницы: в Telegram-канал отправляется сообщение с названием страницы и ссылкой на неё.
• Гибкое управление при редактировании страницы: можно выбрать, следует ли создать новый пост, обновить существующий или ничего не делать.
• Официальный виджет обсуждения Telegram встраивается в страницу сайта через специальный тег. Комментарии к посту канала отображаются непосредственно на сайте.
• Удаление связи при удалении страницы: запись о соответствии страницы и Telegram-сообщения удаляется из базы данных (само сообщение в канале остаётся).
• Независимая конфигурация через удобную админ-панель: токен бота и данные канала хранятся в отдельной таблице базы данных, а не прописываются в коде.
• Поддержка русского и английского языков в интерфейсе плагина.
• Безопасность: встроенная обработка входных данных, использование htmlspecialchars для предотвращения XSS-атак.

Архитектура и структура файлов

Плагин состоит из нескольких хуковых файлов, которые подключаются к событиям модуля Pages и расширяют его функционал. Настройки вынесены в отдельную таблицу базы данных, а административный интерфейс реализован как инструмент в разделе «Инструменты» (Tools).

Структура папки плагина (plugins/tgm4page/):

tgm4page/
├── tgm4page.setup.php          // Заголовок плагина и регистрация
├── tgm4page.admin.php          // Контроллер страницы настроек
├── tgm4page.admin.tpl          // Шаблон формы настроек
├── tgm4page.global.php         // Файл глобального хука (подключает язык)
├── tgm4page.page.add.add.done.php   // Обработчик завершения добавления страницы
├── tgm4page.page.add.tags.php       // Хук тегов: добавляет радиокнопки в форму добавления
├── tgm4page.page.edit.update.done.php // Обработчик завершения обновления страницы
├── tgm4page.page.edit.delete.done.php // Обработчик удаления страницы
├── tgm4page.page.edit.tags.php      // Хук тегов: добавляет радиокнопки в форму редактирования
├── tgm4page.page.tags.php           // Хук тегов: генерирует виджет обсуждения на странице
├── inc/
│   └── tgm4page.functions.php         // Основные функции: отправка/редактирование сообщений, получение конфигурации
├── lang/
│   ├── tgm4page.ru.lang.php           // Русский языковой файл
│   └── tgm4page.en.lang.php           // Английский языковой файл
└── setup/
    ├── tgm4page.install.sql           // SQL-запросы при установке
    └── tgm4page.uninstall.sql         // SQL-запросы при удалении

Каждый файл строго отвечает за свою часть логики, что упрощает поддержку и модификацию.

Установка плагина

1. Скопируйте папку tgm4page в директорию plugins/ вашего сайта Cotonti.
2. Зайдите в административную панель, перейдите в раздел «Расширения» → «Плагины».
3. Найдите в списке tgm4page и нажмите кнопку «Установить».
   • При установке автоматически создадутся таблицы в базе данных:
     • cot_tgm4page — хранит связку «ID страницы — ID сообщения в Telegram».
     • cot_tgm4page_cfg — хранит настройки: токен бота и юзернеймы канала.
4. После успешной установки плагин станет активным, и вы сможете перейти к его настройке.

Настройка Telegram

Для работы плагина потребуются три сущности в Telegram:

• Бот — будет публиковать сообщения в канал.
• Публичный канал — в него бот будет отправлять посты.
• Группа для комментариев — обсуждения будут проходить в отдельной группе, привязанной к каналу.

Краткая инструкция:

1. Создайте бота через @BotFather. Выполните команду /newbot, задайте имя и юзернейм, заканчивающийся на bot (например, mysite_bot). Полученный токен сохраните — он понадобится для настройки плагина.
2. Создайте публичный канал. При создании обязательно выберите тип «Публичный канал» и задайте юзернейм (например, mysite). Адрес канала будет t.me/mysite. Этот юзернейм понадобится в двух форматах:
   • с символом @ (@mysite) — для отправки сообщений ботом,
   • без символа @ (mysite) — для виджета обсуждения.
3. Создайте группу для комментариев (любую, можно приватную). Откройте созданный канал, перейдите в настройки → «Обсуждение» → «Добавить группу» и выберите созданную группу.
4. Добавьте бота в канал и в группу как администратора. В канале обязательно выдайте право «Публикация сообщений». В группе достаточно права чтения сообщений.

Подробная пошаговая инструкция с картинками (при необходимости) доступна в документации к плагину в репозитории.

Настройка плагина через админ-панель Cotonti

После установки плагина перейдите в «Инструменты» (административная панель Cotonti) и выберите tgm4page. Откроется страница с формой настройки, доступной по адресу:
admin.php?m=other&p=tgm4page

Форма содержит три поля:

• Username канала (без @, для виджета)
  Сюда вводится юзернейм вашего публичного канала без символа @. Например: mysite.
  Это значение используется для формирования HTML-виджета обсуждения на странице сайта.
• @Username канала (для отправки сообщений)
  Сюда вводится тот же юзернейм, но уже с символом @. Например: @mysite.
  Это значение используется при отправке сообщений через API Telegram (бот будет публиковать посты именно в этот канал).
• Токен бота
  Вставьте сюда токен, полученный от @BotFather. Строка вида 123456789:ABCdef....

Нажмите «Сохранить». Все данные запишутся в таблицу cot_tgm4page_cfg с идентификатором cfg_id = 1. При повторном открытии страницы настройки автоматически загрузятся из базы данных.

Эти настройки можно изменять в любой момент. Плагин не хранит их в файлах конфигурации Cotonti, что делает перенос сайта более безопасным.

Размещение тегов в шаблонах

Для работы плагина в шаблонах вашей темы (скина) Cotonti необходимо разместить специальные теги. Все теги генерируются плагином автоматически при наличии необходимых настроек.

1. Тег для формы добавления страницы

Файл: skins/ваш_скин/page.add.tpl
Тег: {TGM4PAGE_ADD_ACTION}

Вставьте его в удобное место (например, перед кнопкой «Сохранить»). Он добавит блок с радиокнопками:

• «Ничего не делать»
• «Опубликовать как новый»

По умолчанию при создании новой страницы выбран вариант «Опубликовать как новый» — это означает, что сообщение будет сразу отправлено в канал. При необходимости вы можете переключиться на «Ничего не делать», чтобы пропустить публикацию.

2. Тег для формы редактирования страницы

Файл: skins/ваш_скин/page.edit.tpl
Тег: {TGM4PAGE_EDIT_ACTION}

Он добавляет три радиокнопки:

• «Ничего не делать»
• «Опубликовать как новый»
• «Обновить существующий»

По умолчанию выбрано «Ничего не делать», чтобы случайно не изменять Telegram-пост. Выбор действия влияет на поведение при сохранении изменений страницы (см. далее).

3. Тег для виджета обсуждения

Файл: skins/ваш_скин/page.tpl (основной шаблон страницы сайта)
Тег: {TGM4PAGE_DISCUSSION}

Вставьте его там, где хотите видеть блок обсуждения. Обычно это после текста страницы или в отдельной вкладке. Плагин сам подгрузит официальный скрипт виджета Telegram, указав нужный ID поста.

Важно: Все теги будут обработаны только при активном плагине и корректных настройках. Если настройки не заполнены или плагин отключён, теги ничего не выведут.

Работа плагина: добавление, редактирование и удаление страниц

Добавление страницы

1. При создании страницы администратор может выбрать действие в форме (радиокнопки). Если выбрано «Ничего не делать», плагин завершает работу.
2. Если выбрано «Опубликовать как новый» (по умолчанию), после успешного сохранения страницы вызывается функция tgm4page_send_message(). Она формирует текст сообщения:
   • Префикс (например, «🆕 Новая страница:») берётся из языкового файла.
   • Название страницы экранируется для безопасности (htmlspecialchars), но в текущей версии используется простая интерполяция строки, так как перенос строки не срабатывал в режиме HTML; предпочтительнее использовать версию с \n и http_build_query.
   • Ссылка на страницу сайта формируется абсолютной.
3. Функция отправляет запрос к Telegram Bot API методом sendMessage, используя @username канала и токен бота из настроек. Telegram возвращает уникальный message_id.
4. Плагин сохраняет в таблицу cot_tgm4page запись с item_id (ID страницы) и message_id.

Редактирование страницы

При редактировании администратор выбирает одно из трёх действий:

• Ничего не делать — плагин не выполняет никаких операций с Telegram.
• Опубликовать как новый — отправляется новое сообщение в канал (аналогично добавлению), а старая связь обновляется: если запись уже была, message_id заменяется, иначе создаётся новая.
• Обновить существующий — если в таблице есть запись для этой страницы, вызывается editMessageText в Telegram API, который изменяет текст ранее опубликованного сообщения. Это удобно, когда нужно поправить описание страницы без создания нового поста.

Удаление страницы

При удалении страницы (в корзину или окончательно) плагин просто удаляет запись из таблицы cot_tgm4page, разрывая связь. Сам пост в Telegram остаётся — таким образом, история публикаций сохраняется.

Виджет обсуждения на странице сайта

Плагин использует официальный виджет обсуждения Telegram. Он встраивается через тег {TGM4PAGE_DISCUSSION} и отображает ветку комментариев к конкретному посту в канале.

Механизм:

• В момент открытия страницы сайта плагин находит в таблице cot_tgm4page запись с item_id страницы.
• Извлекает message_id.
• Из настроек берёт chat_id_market (юзернейм канала без @).

• Генерирует HTML-код:

  <script async src="https://telegram.org/js/telegram-widget.js?22"
          data-telegram-discussion="mysite/12345"
          data-comments-limit="5">
  </script>
  

• Этот скрипт автоматически загружает и отображает комментарии из привязанной к каналу группы.

Таким образом, посетители могут видеть обсуждение и оставлять комментарии, если откроют обсуждение в Telegram (нажав на кнопку «Комментировать» на сайте или в самом мессенджере).

Хранение настроек и данных

Плагин использует две таблицы в базе данных Cotonti:

1. cot_tgm4page_cfg — конфигурация

Структура:

• cfg_id — первичный ключ (всегда 1, единственная запись).
• chat_id_market — юзернейм канала без @ (для виджета).
• chat_id_edit — юзернейм канала с @ (для API).
• bot_token — токен бота Telegram.

Доступ к данным конфигурации осуществляется через функцию tgm4page_get_cfg(), которая выполняет запрос:
SELECT * FROM {$db_x}tgm4page_cfg WHERE cfg_id = 1

Во всех файлах плагина, где нужны настройки, вызывается эта функция, и нужное поле извлекается из массива. Это означает, что в коде нет жёстко прописанных токенов или имён каналов — всё загружается динамически из базы.

2. cot_tgm4page — связи страниц и сообщений

Структура:

• item_id (int, уникальный) — идентификатор страницы в модуле Pages.
• message_id (int) — идентификатор сообщения в Telegram.

Используется для хранения соответствия «какой странице какой пост в канале принадлежит». При формировании виджета и при обновлении поста плагин обращается именно к этой таблице.

Пошаговый сценарий использования

Предположим, вы уже установили плагин и настроили Telegram по инструкции.

1. Заполните настройки плагина
   Перейдите в admin.php?m=other&p=tgm4page, введите mysite в первое поле, @mysite во второе, и токен бота. Нажмите «Сохранить».
2. Добавьте теги в шаблоны
   • В page.add.tpl вставьте {TGM4PAGE_ADD_ACTION}.
   • В page.edit.tpl вставьте {TGM4PAGE_EDIT_ACTION}.
   • В page.tpl вставьте {TGM4PAGE_DISCUSSION} в то место, где хотите видеть обсуждение.
3. Создайте новую страницу
   Перейдите на страницу добавления. Появится панель с выбором действия. По умолчанию выбрано «Опубликовать как новый». Заполните поля, сохраните.
   Проверьте свой Telegram-канал: там должно появиться сообщение с названием страницы и ссылкой.
4. Откройте страницу на сайте
   Вы увидите виджет обсуждения. Если в группе комментариев ещё ничего нет, он отобразит «No messages yet». Теперь ваши подписчики могут комментировать, и комментарии будут отображаться на сайте.
5. Отредактируйте страницу
   При редактировании появится блок с тремя опциями. Вы можете обновить существующий пост или опубликовать новый. Выберите нужное действие и сохраните изменения.
6. Удалите страницу
   При удалении страницы связь с постом пропадёт из базы, но сам пост в канале останется (вы можете удалить его вручную, если нужно).

Репозиторий и поддержка

Плагин полностью открыт и доступен для скачивания в репозитории на GitHub:
https://github.com/webitproff/telegram-page-cotonti

Там же находится архив с последней версией и возможностью сообщить об ошибке или предложить улучшение через Issues. Плагин распространяется под лицензией BSD.

Заключение

tgm4page — мощный и гибкий инструмент для автоматизации взаимодействия вашего сайта на Cotonti с Telegram. Он экономит время администратора, повышает вовлечённость аудитории и делает обсуждение страниц живым и доступным прямо на сайте. Благодаря продуманной архитектуре и простой настройке плагин подходит как небольшим, так и крупным проектам.

Если у вас остались вопросы или вы хотите предложить доработку — обращайтесь в Issues на GitHub. Успешной работы и активных обсуждений!