BardSongbooks

BardSongbooks

Скачать

• BardSongbooks-0.2.1.zip
• BardSongbooks-0.2.1.tar.gz
• SHA256SUMS

912ffa91633b28f474cdbc8514497888e5afdc6f3378cd478580279d9767d08e  BardSongbooks-0.2.1.zip
b5c1d2223fbf2b91d13c15aa1cf4f5f6ff05caf02097b2f631c3174da7e03c13  BardSongbooks-0.2.1.tar.gz

BardSongbooks — самописное расширение MediaWiki для личных песенников Бард-Вики. Зарегистрированный пользователь может создать несколько приватных или публичных песенников, добавить в них страницы песен, расположить песни в любом порядке и подготовить печатную версию или PDF.

Текущая версия: 0.2.1.

Изменения 0.2.1

• Убраны кнопки вверх/вниз. Порядок сохраняется перетаскиванием.
• Вместо «Убрать» — SVG-корзина в отдельной правой колонке. Длинные подписи переносятся, не сдвигая корзину.
• Данные и настройки книг, приватность, поиск и печать не меняются.

Возможности

• несколько песенников у одного пользователя;
• добавление песни прямо со страницы песни;
• управление добавлением в служебной колонке темы: справа в инструментах страницы Vector 2022 и слева в старых Vector/MonoBook;
• добавление из поиска в редакторе песенника;
• поиск по основному, альтернативному и оригинальному названию, композиторам, авторам текста, первой строке и всему индексированному тексту песни;
• одновременный запрос по разным полям: например, по автору и словам из текста;
• результаты в формате Название (авторы) — Первая строка;
• произвольная перестановка песен перетаскиванием;
• ссылки на исходные страницы песен в списке и печатном представлении;
• печать песен подряд или каждой с новой страницы;
• от одной до трёх колонок внутри каждой песни;
• размер шрифта от 8 до 16 пунктов;
• сохранение строф при разбиении на колонки;
• возможность скрыть сведения о песне;
• режим «Только первый раздел песни», исключающий последующие разделы, например «Аккорды»;
• дополнительное нумерованное оглавление без номеров страниц со ссылками на песни внутри печатного представления;
• печать и сохранение в PDF средствами браузера.

Новые и существующие песенники по умолчанию приватны. Владелец может опубликовать выбранную книгу для чтения всеми посетителями; право редактирования остаётся только у владельца.

Требования

• MediaWiki 1.43 или новее;
• PHP 8.1 или новее; рабочая конфигурация проверена на PHP 8.3;
• MySQL или MariaDB, поддерживаемые установленной версией MediaWiki;
• расширение Cargo и таблица cargo__song;
• стандартная таблица полнотекстового индекса MediaWiki searchindex.

Расширение ожидает в Cargo-таблице песен поля:

• Name;
• AlterName__full;
• OriginalName__full;
• Composer__full;
• Lyric__full;
• FirstString;
• _pageID.

Это расширение сделано для структуры Бард-Вики. На другой вики с иной схемой Cargo поиск потребуется адаптировать.

Установка

1. Сделайте резервную копию базы данных и LocalSettings.php.
2. Распакуйте архив так, чтобы файл extension.json находился по пути:

  ```text
  extensions/BardSongbooks/extension.json
  ```

1. Добавьте в LocalSettings.php:

  ```php
  wfLoadExtension( 'BardSongbooks' );
  ```

1. Из корня MediaWiki выполните:

  ```bash
  php maintenance/run.php update --quick
  ```

1. Откройте Служебная:Версия и убедитесь, что BardSongbooks показан в списке расширений.
2. Войдите как обычный зарегистрированный пользователь и откройте Служебная:Мои песенники.

Обновление

Переход с 0.2.0 на 0.2.1 меняет только интерфейс: миграция БД и запуск updater не требуются.

1. Сделайте резервную копию текущего каталога extensions/BardSongbooks и базы данных.
2. Замените каталог расширения файлами новой версии.
3. Выполните php maintenance/run.php update --quick. Для 0.2.0 он добавляет bsb_is_public с DEFAULT 0 и индекс публичного каталога, не меняя существующие книги, порядок или настройки.
4. Сбросьте кеш браузера или добавьте ?debug=1, если интерфейс продолжает использовать старые JavaScript/CSS-ресурсы.
5. Проверьте создание тестового песенника, поиск, перестановку песен и печатное представление.

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

Создание песенника

После входа в систему откройте ссылку «Мои песенники» в меню пользователя или страницу Служебная:Мои песенники. Введите название и нажмите «Создать».

Один пользователь может иметь не более 50 песенников. Названия песенников одного пользователя не должны повторяться.

Добавление песен

Песню можно добавить двумя способами:

1. открыть страницу песни и воспользоваться появившимся элементом добавления в песенник;
2. открыть редактор песенника, ввести запрос в поле «Добавить песню» и выбрать результат.

В Vector 2022 блок выбора песенника находится внутри служебной панели «Инструменты»: при закреплённых инструментах — в правой колонке, при незакреплённых — в раскрывающемся меню «Инструменты». В старом Vector и MonoBook блок помещается в левую служебную колонку после обычных инструментов. Над содержимым статьи блок не выводится. Для других тем, где подходящей служебной области нет, используется запасной полноширинный вариант в начале содержимого.

В один песенник нельзя дважды добавить одну и ту же страницу. Максимум — 500 песен в песеннике.

Поиск

Запрос разбивается максимум на десять слов. Каждое слово должно встретиться хотя бы в одном из поддерживаемых полей, но разные слова могут находиться в разных полях. Поэтому запрос может одновременно содержать имя автора, часть названия и слова из текста.

Поиск охватывает:

• основное название;
• альтернативные названия;
• оригинальные названия;
• композиторов и авторов текста;
• первую строку;
• весь индексированный MediaWiki текст страницы песни.

Минимальная длина запроса — два символа. За один запрос возвращается до 30 результатов.

Порядок песен

Песни можно перетаскивать мышью; кнопки вверх и вниз убраны. Новый полный порядок сохраняется только для данного песенника. Чтобы убрать песню, нажмите значок корзины в отдельной правой колонке её строки. Корзина доступна с клавиатуры и имеет подсказку «Убрать песню из песенника». Убирается только запись в песеннике, исходная страница песни остаётся в Wiki.

Приватность, публикация и ссылка

В редакторе откройте «Доступ к песеннику», выберите «Публичный — доступен всем» и нажмите «Сохранить доступ». До нажатия кнопки состояние книги не меняется. Новые книги и все книги после обновления с 0.1.9 остаются приватными; автоматической публикации нет.

После публикации появляется поле «Ссылка на песенник» и кнопка «Копировать ссылку». Ссылка ведёт на обычную Служебная:Песенник/<id> и работает без входа. Название можно менять: ID и адрес книги сохраняются. При недоступном Clipboard API ссылка выделяется для обычного Ctrl+C.

Получатель видит упорядоченный список песен, ссылки на исходные страницы и печатное представление/PDF. У него нет поиска/добавления, перестановки, переименования, удаления, настроек или изменения видимости чужой книги. Все операции записи по-прежнему проверяют зарегистрированного владельца, POST и CSRF.

Для закрытия выберите «Приватный — только я» и сохраните. Книга исчезнет из каталога, её HTML, печать и API станут недоступны остальным, даже по старой ссылке. Уже скачанные PDF и сделанные другими людьми копии вернуть невозможно. Права чтения исходных страниц Wiki не расширяются: недоступные конкретному читателю песни исключаются из списка и печати.

Общий каталог всех пользователей

Служебная:Публичные песенники доступна без входа. Ссылки на неё есть в инструментах страницы и на странице «Мои песенники». Каталог показывает публичные книги всех пользователей, а не только текущего.

Четыре колонки: «Название песенника» (ссылка), «Пользователь» (имя в Wiki, без email/настоящего имени), «Количество песен», «Дата последнего изменения». Сортировка — сначала недавно изменённые, при равенстве дат по ID. По 20 книг на страницу. Приватные книги не попадают в каталог.

API

• action=bardsongbooks&mode=public&limit=20&offset=0 — общий каталог, без входа;
• action=bardsongbooks&mode=items&book=<id> — содержимое: владелец для приватной книги, любой читатель для публичной;
• mode=list и mode=search сохраняют прежнее требование входа и права bard-songbooks-use;
• action=bardsongbookedit&op=visibility&book=<id>&public=1&token=<csrf> — публикация, только POST зарегистрированного владельца;
• для закрытия выполните тот же POST без параметра public. Boolean-параметры API MediaWiki истинны по присутствию; public=0 тоже означает присутствие и не закрывает книгу.

Чтение видимости и публичного каталога использует primary DB для немедленного закрытия доступа без задержки реплик. Ответы HTML и API не предназначены для общего кеширования.

Печать и PDF

В редакторе песенника задаются:

• песни подряд или каждая с новой страницы;
• 1, 2 или 3 колонки внутри текста каждой песни;
• шрифт 8–16 пунктов;
• показ сведений о песне;
• печать только первого раздела песни.

Строфы распределяются между колонками целиком и не должны разрываться внутри строфы. Заголовок песни остаётся ссылкой на исходную страницу. Кнопка «Печать / сохранить в PDF» открывает диалог браузера; создание PDF выполняет сам браузер.

Режим «Только первый раздел песни» сохраняет основной раздел и отбрасывает содержимое начиная со следующего прямого заголовка H2–H6. Он предназначен, в частности, для исключения раздела «Аккорды».

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

Данные и безопасность

Расширение создаёт две собственные таблицы:

• bard_songbook — песенники, владелец, название, параметры печати и bsb_is_public (0/1, по умолчанию 0);
• bard_songbook_item — страницы песен и их порядок в песеннике.

Страницы песен, формы PageForms, шаблоны, Lua-модули и данные Cargo не изменяются.

Право bard-songbooks-use по умолчанию выдано группе user. Анонимные посетители видят только публичные песенники. Приватные названия, состав и параметры закрыты в HTML, печати и API. Все операции изменения требуют входа, проверки владельца, POST-запроса и CSRF-токена MediaWiki.

Удаление и откат

Для отката замените каталог расширения сохранённой предыдущей версией. Новую колонку/индекс удалять не требуется. Код 0.1.9 снова закрывает все книги для посторонних; при повторном обновлении до 0.2.0 сохранённый выбор публичности вернётся. Полный откат данных выполняется отдельно по проверенной резервной копии.

Для отключения удалите или закомментируйте строку wfLoadExtension( 'BardSongbooks' ); в LocalSettings.php. Собственные таблицы при этом остаются в базе, поэтому песенники можно вернуть повторным включением расширения.

Если расширение удаляется окончательно, таблицы bard_songbook_item и bard_songbook можно удалить вручную только после отдельной проверенной резервной копии. Сначала удаляется таблица элементов, затем таблица песенников.

Ограничения версии 0.2.1

• песенники привязаны к текущим версиям страниц песен и не фиксируют конкретную ревизию;
• совместное редактирование отсутствует: публичность даёт только чтение и печать;
• PDF создаётся браузером, серверного PDF-генератора нет;
• качество поиска полного текста зависит от актуальности стандартного индекса MediaWiki;
• схема поиска зависит от полей Cargo, используемых в Бард-Вики.

Структура расширения

• includes/SongbookStore.php — хранение, права владельца и поиск;
• includes/SongPrintRenderer.php — подготовка песен для печати;
• includes/Special/ — страницы списка, редактора и печати;
• includes/Api/ — API чтения и изменения песенников;
• modules/ — JavaScript и CSS интерфейса;
• sql/mysql/tables-generated.sql — схема собственных таблиц;
• i18n/ — сообщения интерфейса;
• CHANGELOG.md — история выпусков.

Лицензия

GPL-2.0-or-later. Краткое уведомление находится в LICENSE.md, полный текст GNU GPL версии 2 — в COPYING.