Плагин Page Reviews для добавления отзывов к статьям на Cotonti CMF

Техническая документация плагина Page Reviews

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

Название: Page Reviews
Код: pagereviews
Версия: 1.0.1
Дата выпуска: 10 мая 2025
Автор: webitprof
Лицензия: BSD
Платформа: Cotonti Siena v0.9.26
Требования: PHP 8.2, модули Cotonti page и users
Описание: Плагин для добавления функционала отзывов к статьям в Cotonti Siena. Поддерживает добавление, редактирование, удаление отзывов, систему жалоб, фильтрацию, сортировку и мультиязычность (русский, английский).

2. Назначение и функциональность

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

2.1. Управление отзывами

• Добавление: Пользователи могут добавлять отзывы с заголовком, текстом и оценкой (1–5 звезд). Администраторы могут задавать автора и дату.
• Редактирование: Пользователи (авторы) и администраторы могут редактировать отзывы.
• Удаление: Пользователи (авторы) и администраторы могут удалять отзывы.
• Ограничение: Один пользователь — один отзыв на статью.

2.2. Система жалоб

• Пользователи могут подавать жалобы на отзывы, указывая причину.
• Администраторы могут просматривать список жалоб, одобрять (удаление отзыва) или отклонять их.
• Уведомления о новых жалобах отправляются администраторам по email.

2.3. Интеграция с Cotonti

• Привязка отзывов к статьям (модуль page) и категориям.
• Генерация тегов для шаблонов (page.tpl) для отображения отзывов и статистики.
• Поддержка мультиязычности через языковые файлы (ru, en).

2.4. Фильтрация и сортировка

• Поиск: Поиск по тексту и заголовку отзыва.
• Фильтры: По пользователю, категории или подкатегориям.
• Сортировка: По дате (возрастание/убывание), рейтингу (возрастание/убывание), актуальности.
• Пагинация: Настраиваемое количество отзывов на странице.

2.5. AJAX-поддержка

• Автодополнение имен пользователей для фильтрации по автору отзыва.

2.6. Администрирование

• Администраторы могут изменять автора и дату отзыва.
• Управление жалобами через интерфейс.
• Уведомления о действиях (добавление, редактирование, удаление отзывов, жалобы) по email.

2.7. Настраиваемые параметры

• Отображение всех отзывов на странице статьи.
• Черный список категорий для исключения из отзывов.
• Количество отзывов на странице списка.
• Мета-заголовки и описания для SEO.

3. Структура плагина

3.1. Общая структура

/pagereviews/
├── pagereviews.setup.php                 # Конфигурация и установка плагина
├── pagereviews.php                       # Точка входа, выбор режима
├── pagereviews.pagetags.main.php         # Генерация тегов статистики отзывов
├── pagereviews.page.tags.php             # Теги для шаблона page.tpl
├── pagereviews.input.php                 # Обработка входных данных
├── pagereviews.global.php                # Подключение языковых файлов
├── pagereviews.ajax.php                  # Обработка AJAX-запросов
├── tpl/
│   ├── pagereviews.claim.tpl             # Шаблон формы жалобы
│   ├── pagereviews.edit.tpl              # Шаблон формы редактирования отзыва
│   ├── pagereviews.last.tpl              # Шаблон последних отзывов
│   ├── pagereviews.list.tpl              # Шаблон списка отзывов
│   ├── pagereviews.main.tpl              # Шаблон отображения одного отзыва
│   ├── pagereviews.page.tpl              # Шаблон интеграции отзывов в статью
│   └── pagereviews.tree.tpl              # Шаблон дерева категорий
├── setup/
│   ├── pagereviews.install.sql           # SQL для создания таблиц
│   └── pagereviews.uninstall.sql         # SQL для удаления таблиц
├── lang/
│   ├── pagereviews.ru.lang.php           # Локализация (русский)
│   └── pagereviews.en.lang.php           # Локализация (английский)
└── inc/
    ├── pagereviews.add.php               # Логика добавления отзыва
    ├── pagereviews.claim.php             # Логика обработки жалоб
    ├── pagereviews.delete.php            # Логика удаления отзыва
    ├── pagereviews.edit.php              # Логика редактирования отзыва
    ├── pagereviews.functions.php         # Основные функции плагина
    ├── pagereviews.list.php              # Логика списка отзывов
    └── pagereviews.main.php              # Логика отображения одного отзыва

3.2. Описание файлов

Основные файлы

• pagereviews.setup.php: Определяет зависимости (Cotonti v0.9.26, PHP 8.2, модули page, users), настройки (отображение отзывов, пагинация, черный список категорий, мета-теги).
• pagereviews.php: Точка входа, определяет режим работы (main, list, add, edit, claim, delete) на основе параметров запроса.
• pagereviews.pagetags.main.php: Генерирует теги статистики (REVIEWS_STARS_SUMM, REVIEWS_TOTAL_COUNT, REVIEWS_AVG_STARS) для шаблона страницы.
• pagereviews.page.tags.php: Генерирует теги (PAGE_REVIEWS, PAGE_REVIEWS_COUNT, PAGE_REVIEWS_URL) для интеграции отзывов в page.tpl.
• pagereviews.input.php: Обрабатывает входные данные плагина.
• pagereviews.global.php: Подключает языковые файлы для глобального использования.
• pagereviews.ajax.php: Обрабатывает AJAX-запросы для автодополнения имен пользователей.

Шаблоны (tpl)

• pagereviews.claim.tpl: Форма подачи жалобы на отзыв, отображение списка жалоб для администраторов.
• pagereviews.edit.tpl: Форма редактирования отзыва (заголовок, текст, оценка, автор, дата).
• pagereviews.last.tpl: Отображение последних отзывов (с привязкой к статьям).
• pagereviews.list.tpl: Список всех отзывов с фильтрацией и сортировкой.
• pagereviews.main.tpl: Отображение одного отзыва с деталями (заголовок, текст, оценка, автор, дата).
• pagereviews.page.tpl: Интеграция отзывов в страницу статьи.
• pagereviews.tree.tpl: Дерево категорий для фильтрации отзывов.

SQL-скрипты (setup)

• pagereviews.install.sql: Создает таблицы:
  • cot_pagereviews: Хранит отзывы (item_id, item_userid, item_pageid, item_text, item_title, item_score, item_date).
  • cot_pagereviews_complaints: Хранит жалобы (complaint_id, complaint_userid, complaint_itemid, complaint_text, complaint_date, complaint_resolved_date, complaint_status).
• pagereviews.uninstall.sql: Удаляет таблицы cot_pagereviews и cot_pagereviews_complaints.

Языковые файлы (lang)

• pagereviews.ru.lang.php: Локализация на русском для интерфейса, сообщений и конфигурации.
• pagereviews.en.lang.php: Локализация на английском.

Логика (inc)

• pagereviews.add.php: Логика добавления отзыва, включая валидацию, сохранение и уведомления.
• pagereviews.claim.php: Логика подачи и обработки жалоб (пользовательская форма, админский список, одобрение/отклонение).
• pagereviews.delete.php: Логика удаления отзыва с проверкой прав и уведомлениями.
• pagereviews.edit.php: Логика редактирования отзыва, включая форму и валидацию.
• pagereviews.functions.php: Основные функции:
  • cot_generate_stars_page: Генерация звезд для рейтинга.
  • cot_get_pagereview_scores: Подсчет статистики отзывов (сумма, средний рейтинг).
  • cot_pagereviews_list: Вывод списка отзывов с пагинацией и формой добавления.
  • cot_pagereviews_last: Вывод последних отзывов.
  • cot_get_pagereview_counts_by_categories: Подсчет отзывов по категориям.
  • cot_pagereviews_selectcat: Формирование выпадающего списка категорий (Select2).
  • cot_pagereviews_build_structure_tree: Построение дерева категорий.
• pagereviews.list.php: Отображение списка отзывов с фильтрацией, сортировкой и пагинацией.
• pagereviews.main.php: Отображение одного отзыва на отдельной странице.

4. Установка

4.1. Требования

• Платформа: Cotonti Siena v0.9.26.
• PHP: 8.2.
• Модули: page, users.
• Зависимости: Поддержка extrafields, uploads, forms.

4.2. Процесс установки

1. Скопируйте папку pagereviews в директорию plugins сайта Cotonti.
2. В админ-панели Cotonti перейдите в "Расширения" → "Установить плагин" → выберите Page Reviews.
3. Скрипт pagereviews.install.sql автоматически создаст таблицы cot_pagereviews и cot_pagereviews_complaints.
4. Настройте параметры в админ-панели:
   • pageall (radio): Показывать все отзывы на странице статьи (1 — да, 0 — нет).
   • reviews_per_page (string): Количество отзывов на странице списка (по умолчанию 10).
   • blacklistcattree (string): Категории, исключенные из отзывов (через запятую, например: system,unvalidated,info).
   • metatitletext (string): Мета-заголовок страницы отзывов.
   • metadescrtext (string): Мета-описание страницы отзывов.
5. Добавьте в шаблон page.tpl теги:
   • {PAGE_REVIEWS}: Список отзывов.
   • {PAGE_REVIEWS_COUNT}: Количество отзывов.
   • {PAGE_REVIEWS_URL}: URL страницы с отзывами.
   • {REVIEWS_STARS_SUMM}, {REVIEWS_TOTAL_COUNT}, {REVIEWS_AVG_STARS}: Статистика рейтинга.

4.3. Проверка

• Перейдите на страницу статьи (index.php?r=page&id=X) и убедитесь, что форма добавления отзыва отображается.
• Проверьте список отзывов по URL index.php?e=pagereviews&m=list.

5. Использование

5.1. Добавление отзыва

• На странице статьи авторизованный пользователь видит форму (ADD_FORM) с полями:
  • Заголовок (rtitle).
  • Текст (rtext).
  • Оценка (rscore, 1–5).
  • Для администраторов: выбор пользователя (ruserid) и даты (rdate).
• После отправки данные валидируются, сохраняются в cot_pagereviews, администраторы получают уведомление.

5.2. Редактирование и удаление

• Авторы и администраторы могут редактировать (m=edit) или удалять (m=delete) отзывы.
• Форма редактирования аналогична форме добавления.

5.3. Подача жалоб

• Пользователи могут подать жалобу (m=claim) на отзыв, указав причину (complaint_text).
• Жалоба сохраняется в cot_pagereviews_complaints, администраторы получают уведомление.

5.4. Администрирование жалоб

• Администраторы видят список жалоб (m=claim) с возможностью одобрения (action=approve, удаляет отзыв) или отклонения (action=reject).
• Уведомления отправляются при обработке жалобы.

5.5. Список отзывов

• Страница m=list отображает отзывы с фильтрами:
  • Поиск (sq): По тексту и заголовку.
  • Категория (c): Выбор категории и подкатегорий.
  • Пользователь (user): Фильтр по автору.
  • Сортировка (sort): dateasc, datedesc, scoreasc, scoredesc, mostrecent.
• Пагинация настраивается через reviews_per_page.

5.6. Отображение одного отзыва

• Режим m=main показывает отдельный отзыв с деталями (заголовок, текст, оценка, автор, дата).

6. Технические детали

6.1. База данных

• cot_pagereviews:
  • item_id (INT, PK): ID отзыва.
  • item_userid (INT): ID автора.
  • item_pageid (INT): ID статьи.
  • item_text (TEXT): Текст отзыва.
  • item_title (VARCHAR): Заголовок отзыва.
  • item_score (INT): Оценка (1–5).
  • item_date (INT): Дата отзыва.
  • Индексы: idx_userid, idx_pageid.
• cot_pagereviews_complaints:
  • complaint_id (INT, PK): ID жалобы.
  • complaint_userid (INT): ID автора жалобы.
  • complaint_itemid (INT): ID отзыва.
  • complaint_text (TEXT): Текст жалобы.
  • complaint_date (INT): Дата подачи.
  • complaint_resolved_date (INT): Дата обработки.
  • complaint_status (ENUM): pending, rejected, approved.
  • Индексы: idx_userid, idx_itemid.

6.2. Безопасность

• Права доступа: Используется cot_auth для проверки прав (R, W, A).
• Валидация: cot_import, cot_check для проверки входных данных.
• Защита от спама: cot_shield_protect предотвращает повторные действия.
• Ограничения: Проверка на существование страницы, отзыва, пользователя; запрет дублирования отзывов и жалоб.

6.3. Интерфейс

• Стилизация: Использует Bootstrap (form-control, form-select) для форм.
• Select2: Поддержка выбора категорий и пользователей.
• Шаблоны: Используют XTemplate для рендеринга.

6.4. Уведомления

• Отправляются по email администраторам (группа user_maingrp = 5) при:
  • Добавлении отзыва.
  • Редактировании отзыва.
  • Удалении отзыва.
  • Подаче жалобы.
  • Обработке жалобы.
• Сообщения включают детали (заголовок, текст, оценка, автор, статья, дата, ссылки).

7. Удаление

1. В админ-панели Cotonti перейдите в "Расширения" → "Отключить плагин" → выберите Page Reviews.
2. Скрипт pagereviews.uninstall.sql удалит таблицы cot_pagereviews и cot_pagereviews_complaints.
3. Удалите папку pagereviews из директории plugins.

8. Ограничения и рекомендации

• Ограничения:
  • Требуется авторизация для добавления отзывов и жалоб.
  • Один отзыв на пользователя на статью.
  • Нет поддержки вложенных комментариев к отзывам.
• Рекомендации:
  • Настройте blacklistcattree для исключения системных категорий.
  • Используйте Select2 и Bootstrap для улучшения UX.
  • Регулярно проверяйте жалобы в админ-панели.

9. Поддержка и обновления

• Автор: webitprof.
• Лицензия: BSD.
• Обновления: Следите за версиями на официальном репозитории Cotonti или сайте автора.
• Поддержка: Обратитесь к документации Cotonti или сообществу для решения проблем.

10. Примеры использования

• Добавление отзыва: Перейдите на страницу статьи (index.php?r=page&id=X), заполните форму (заголовок, текст, оценка) и отправьте.
• Подача жалобы: На странице отзыва (m=main) нажмите "Пожаловаться", укажите причину.
• Фильтрация отзывов: На странице index.php?e=pagereviews&m=list используйте поиск, фильтры по категории или пользователю, сортировку.
• Администрирование: В режиме m=claim просмотрите и обработайте жалобы.

Примеры интеграции плагина Page Reviews в шаблоны Cotonti

Ниже приведены примеры интеграции функционала плагина Page Reviews в основные шаблоны Cotonti: page.tpl, index.tpl и page.list.tpl. Каждый пример включает условные проверки активности плагина (cot_plugin_active('pagereviews')) и прав доступа, а также использование тегов, предоставляемых плагином для отображения отзывов, статистики и элементов управления.

1. Интеграция в page.tpl

Шаблон page.tpl используется для отображения отдельной страницы (статьи). Плагин предоставляет теги для отображения списка отзывов, их количества, статистики рейтинга и формы добавления отзыва.

<!-- IF {PHP|cot_plugin_active('pagereviews')} -->
<div class="reviews-section">
    <h2>{PHP.L.pagereviews_reviews}</h2>
    
    <!-- Статистика отзывов -->
    <!-- IF {REVIEWS_TOTAL_COUNT} > 0 -->
    <div class="reviews-stats">
        <p>{PHP.L.pagereviews_pageCountReviewsTotalValue}: {REVIEWS_TOTAL_COUNT}</p>
        <p>{PHP.L.pagereviews_pageAverageRatingValue}: {REVIEWS_AVG_STARS}</p>
        <p>{PHP.L.pagereviews_pageCountStarsTotalValue}: {REVIEWS_STARS_SUMM}</p>
    </div>
    <!-- ELSE -->
    <p>{PHP.L.pagereviews_no_reviews}</p>
    <!-- ENDIF -->
    
    <!-- Список отзывов -->
    <!-- IF {PHP|cot_auth('plug', 'pagereviews', 'R')} -->
    {PAGE_REVIEWS}
    <!-- ENDIF -->
    
    <!-- Форма добавления отзыва (для авторизованных пользователей) -->
    <!-- IF {PHP|cot_auth('plug', 'pagereviews', 'W')} AND {PHP.usr.id} > 0 -->
    <div class="add-review-form">
        <h3>{PHP.L.pagereviews_add_review}</h3>
        {PAGE_REVIEWS_FORM}
    </div>
    <!-- ENDIF -->
    
    <!-- Ссылка на все отзывы -->
    <a href="{PAGE_REVIEWS_URL}" class="btn btn-primary">{PHP.L.pagereviews_view_all}</a>
    
    <hr>
</div>
<!-- ENDIF -->

Пояснения:

• Проверка {PHP|cot_plugin_active('pagereviews')} обеспечивает отображение блока только при активном плагине.
• Теги REVIEWS_TOTAL_COUNT, REVIEWS_AVG_STARS, REVIEWS_STARS_SUMM берутся из pagereviews.pagetags.main.php и показывают статистику (количество отзывов, средний рейтинг, сумма звезд).
• {PAGE_REVIEWS} отображает список отзывов, сгенерированный функцией cot_pagereviews_list (из pagereviews.functions.php), включая пагинацию.
• {PAGE_REVIEWS_FORM} выводит форму добавления отзыва (доступна для авторизованных пользователей с правами на запись).
• {PAGE_REVIEWS_URL} — ссылка на страницу списка всех отзывов (m=list).
• Проверка прав {PHP|cot_auth('plug', 'pagereviews', 'R')} и {PHP|cot_auth('plug', 'pagereviews', 'W')} ограничивает доступ к чтению и записи.

2. Интеграция в index.tpl

Шаблон index.tpl используется для главной страницы сайта. Здесь можно вывести блок с последними отзывами, используя функцию cot_pagereviews_last.

<!-- IF {PHP|cot_plugin_active('pagereviews')} AND {PHP|cot_auth('plug', 'pagereviews', 'R')} -->
<div class="latest-reviews">
    <h2>{PHP.L.pagereviews_last_index}</h2>
    
    <!-- Вывод последних отзывов -->
    {PHP|cot_pagereviews_last(5)}
    
    <!-- Ссылка на полный список отзывов -->
    <a href="{PHP|cot_url('plug', 'e=pagereviews&m=list')}" class="btn btn-secondary">{PHP.L.pagereviews_view_all}</a>
    
    <hr>
</div>
<!-- ENDIF -->

Пояснения:

• {PHP|cot_pagereviews_last(5)} вызывает функцию cot_pagereviews_last из pagereviews.functions.php, отображая 5 последних отзывов.
• Проверка {PHP|cot_auth('plug', 'pagereviews', 'R')} ограничивает доступ для пользователей с правом чтения.
• {PHP|cot_url('plug', 'e=pagereviews&m=list')} генерирует URL для страницы списка всех отзывов.
• Языковые строки ({PHP.L.pagereviews_last_index}, {PHP.L.pagereviews_view_all}) берутся из файлов pagereviews.ru.lang.php или pagereviews.en.lang.php.

3. Интеграция в page.list.tpl

Шаблон page.list.tpl используется для списка страниц в категории. Здесь можно добавить количество отзывов и средний рейтинг для каждой страницы.

<!-- IF {PHP|cot_plugin_active('pagereviews')} -->
<div class="page-list">
    <!-- BEGIN: PAGES_ROW -->
    <div class="page-item">
        <h3><a href="{PAGES_ROW_URL}">{PAGES_ROW_TITLE}</a></h3>
        <p>{PAGES_ROW_DESC}</p>
        
        <!-- Статистика отзывов для страницы -->
        <!-- IF {PAGES_ROW_REVIEWS_COUNT} > 0 -->
        <div class="page-reviews-stats">
            <p>{PHP.L.pagereviews_pageCountReviewsTotalValue}: {PAGES_ROW_REVIEWS_COUNT}</p>
            <p>{PHP.L.pagereviews_pageAverageRatingValue}: {PAGES_ROW_AVG_STARS}</p>
            <a href="{PAGES_ROW_REVIEWS_URL}" class="btn btn-sm btn-info">{PHP.L.pagereviews_view_all}</a>
        </div>
        <!-- ELSE -->
        <p>{PHP.L.pagereviews_no_reviews}</p>
        <!-- ENDIF -->
    </div>
    <hr>
    <!-- END: PAGES_ROW -->
</div>
<!-- ENDIF -->

Пояснения:

• Теги PAGES_ROW_REVIEWS_COUNT, PAGES_ROW_AVG_STARS, PAGES_ROW_REVIEWS_URL генерируются в pagereviews.page.tags.php для каждой страницы в списке.
• {PAGES_ROW_REVIEWS_COUNT} показывает количество отзывов для страницы.
• {PAGES_ROW_AVG_STARS} отображает средний рейтинг (звезды).
• {PAGES_ROW_REVIEWS_URL} — ссылка на страницу статьи с отзывами.
• Условие {PAGES_ROW_REVIEWS_COUNT} > 0 проверяет наличие отзывов, чтобы избежать пустых блоков.

4. Дополнительные шаблоны (опционально)

4.1. Интеграция в пользовательский профиль (users.details.tpl)

Для отображения отзывов конкретного пользователя в его профиле:

<!-- IF {PHP|cot_plugin_active('pagereviews')} AND {PHP|cot_auth('plug', 'pagereviews', 'R')} -->
<div class="user-reviews">
    <h2>{PHP.L.pagereviews_reviews} ({PHP.L.pagereviews_author}: {USERS_DETAILS_NAME})</h2>
    
    <!-- Список отзывов пользователя -->
    {PHP|cot_pagereviews_list(0, false, {USERS_DETAILS_ID})}
    
    <!-- Ссылка на все отзывы пользователя -->
    <a href="{PHP|cot_url('plug', 'e=pagereviews&m=list&user={USERS_DETAILS_ID}')}" class="btn btn-secondary">{PHP.L.pagereviews_view_all}</a>
    
    <hr>
</div>
<!-- ENDIF -->

Пояснения:

• {PHP|cot_pagereviews_list(0, false, {USERS_DETAILS_ID})} вызывает функцию cot_pagereviews_list с фильтром по ID пользователя (USERS_DETAILS_ID), отображая его отзывы.
• {PHP|cot_url('plug', 'e=pagereviews&m=list&user={USERS_DETAILS_ID}')} ведет на страницу списка отзывов с фильтром по пользователю.

4.2. Интеграция в категорию (page.list.tpl с деревом категорий)

Для отображения дерева категорий с количеством отзывов:

<!-- IF {PHP|cot_plugin_active('pagereviews')} AND {PHP|cot_auth('plug', 'pagereviews', 'R')} -->
<div class="category-tree">
    <h2>{PHP.L.pagereviews_categories}</h2>
    
    <!-- Дерево категорий -->
    {PHP|cot_pagereviews_build_structure_tree('', {PHP.c})}
    
    <hr>
</div>
<!-- ENDIF -->

Пояснения:

• {PHP|cot_pagereviews_build_structure_tree('', {PHP.c})} вызывает функцию cot_pagereviews_build_structure_tree из pagereviews.functions.php, отображая дерево категорий с количеством отзывов (ROW_REVIEWCOUNT).
• {PHP.c} — текущая категория, переданная в шаблон.

5. Примечания по интеграции

• Проверка активности плагина: Всегда используйте <!-- IF {PHP|cot_plugin_active('pagereviews')} --> для предотвращения ошибок, если плагин не установлен.
• Права доступа: Проверки {PHP|cot_auth('plug', 'pagereviews', 'R')} и {PHP|cot_auth('plug', 'pagereviews', 'W')} ограничивают доступ к просмотру и добавлению отзывов.
• Языковые строки: Используйте {PHP.L.<key>} для локализованных текстов (pagereviews_reviews, pagereviews_no_reviews, etc.) из pagereviews.ru.lang.php или pagereviews.en.lang.php.
• Стилизация: Теги генерируют HTML с классами Bootstrap (form-control, form-select, btn), поэтому убедитесь, что тема сайта включает Bootstrap.
• Select2: Для выпадающих списков категорий и пользователей (SEARCH_CAT, SEARCH_USER) подключите библиотеку Select2, как указано в cot_pagereviews_selectcat.

6. Рекомендации

• Добавьте CSS для стилизации блоков отзывов и форм в соответствии с дизайном сайта.
• Проверьте права доступа в админ-панели (plug/pagereviews): гости — R, пользователи — RW, администраторы — RWA.
• Настройте параметр reviews_per_page в конфигурации плагина для оптимальной пагинации.
• Используйте черный список категорий (blacklistcattree) для исключения системных разделов.

• Repository: https://github.com/webitproff/cot-pagereviews