BardSongbooks

Скачать

5626f68e59f0612e1ff24c9abddc7e67517b126e74aac864458ac826e1fee969  BardSongbooks-0.2.3.zip
4491f343ad65f4f4325c111d3c5dfef27e88876ec15795731de0b8d7ac006342  BardSongbooks-0.2.3.tar.gz

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

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

Изменения 0.2.3

Настройки showNotes и showPerformance сохраняются в существующем JSON bsb_settings, без миграции БД.
«Показывать примечания»: при выключении удаляются раздел/список примечаний и ссылки-номера Cite в тексте; обычные надстрочные символы сохраняются.
«Показывать исполнение»: при выключении убираются заголовок и таблица исполнения из Template:Song либо одноимённый раздел.
«Только первый раздел» исключает аккорды и остальные варианты текста, но оставляет явно выбранные примечания/исполнение.
В старых и новых песенниках showNotes/showPerformance по умолчанию true; существующие сохранённые параметры не переписываются.
Параметры печати разделены на верхнюю строку полей и сетку галочек, с адаптацией для узкого экрана.
Название в общем каталоге публичных песенников открывает печатную версию; права владельца и приватность не меняются.

Примечания и исполнение

«Показывать примечания» управляет разделом примечаний и номерами сносок в песне вместе. При выключении исчезают ссылки-номера Cite, список и заголовок примечаний; обычные надстрочные символы текста не удаляются.

«Показывать исполнение» управляет заголовком и таблицей исполнения, которые создаёт шаблон Song, а также отдельным одноимённым разделом, если он есть.

Обе галочки включены по умолчанию и сохраняются для каждого песенника в bsb_settings как showNotes и showPerformance. Для старых настроек без этих ключей используется true. Исходные страницы песен и старые сохранённые настройки при обновлении не переписываются. При снятой галочке значение false сохраняется и в приватном, и в публичном печатном просмотре.

«Только первый раздел песни» исключает аккорды и последующие варианты текста. Примечания и исполнение выбираются независимо: отмеченные дополнения остаются и при включённом первом разделе. Оглавление и количество колонок 1/2/3 работают как прежде.

Название в общем каталоге публичных песенников ведёт сразу на Special:SongbookPrint/<id>. Ссылка для общего доступа Special:Songbook/<id> остаётся прежней, менять книгу по-прежнему может только владелец.

Обновление с 0.2.1 на 0.2.3 не требует миграции БД или запуска updater. Версия 0.2.2 не выпускалась (отменённый частный черновик).

Изменения 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 поиск потребуется адаптировать.

Установка

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

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

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

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

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

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

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

Обновление

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

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

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

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

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

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

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

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

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

В 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.3

песенники привязаны к текущим версиям страниц песен и не фиксируют конкретную ревизию;
совместное редактирование отсутствует: публичность даёт только чтение и печать;
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.