Версия от 15:10, 6 октября 2026

BardSongbooks

Скачать

88ce1e49927439a4bed65e4a27d6b2a0e695dd98d34a7f3104c3426c02658798  BardSongbooks-0.2.0.zip
18e8e1823a41c15d2c6777ce546041db76ab613374ab2c48bfa8cbdb1260db1a  BardSongbooks-0.2.0.tar.gz

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

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

Возможности

несколько песенников у одного пользователя;
добавление песни прямо со страницы песни;
управление добавлением в служебной колонке темы: справа в инструментах страницы 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 показан в списке расширений.
Войдите как обычный зарегистрированный пользователь и откройте Служебная:Мои песенники.

Обновление

Сделайте резервную копию текущего каталога 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 результатов.

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

Песни можно перетаскивать мышью. Для клавиатуры и точной перестановки доступны кнопки вверх и вниз. Новый полный порядок сохраняется только для данного песенника.

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

В редакторе откройте «Доступ к песеннику», выберите «Публичный — доступен всем» и нажмите «Сохранить доступ». До нажатия кнопки состояние книги не меняется. Новые книги и все книги после обновления с 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.0

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

BardSongbooks: различия между версиями