Инструменты пользователя

Инструменты сайта


Боковая панель

Этот перевод старее, чем оригинальная страница, и может быть неактуальным. Смотрите, что было изменено.
Перевод этой страницы?:

О «Докувики»

Дополнительные возможности

Corporate Use

Наше сообщество


Следуйте за нами на Фейсбуке, в Твиттере и других социальных сетях.

Конфиденциальность (англ.)

ru:plugin:database2

Плагин DataBase2

Совместим с «Докувики»

  • 2018-04-22 "Greebo" неизвестно
  • 2017-02-19 "Frusterick Manners" неизвестно
  • 2016-06-26 "Elenor Of Tsort" неизвестно
  • 2015-08-10 "Detritus" да

plugin Обеспечивает интеграцию управляемых базами данных таблиц непосредственно со страницами вики

Последнее обновление:
2014-11-25
Предоставляет
Syntax, Admin
Репозиторий
Исходный код
Конфликтует с
tabinclude

Похож на database

Теги: database, tables

Домашняя страница Демонстрация Обсуждение (англ.) Скачать Локализация

Экскурс

В феврале 2009 года я начал разрабатывать свой собственный плагин для «Докувики», обеспечивающего интеграцию таблиц баз данных, например, выводить их данные или редактировать их в контексте страницы вики. Плагин называется database21).

  • Статус: в разработке

Благодарности

Спасибо

  • Джейсону Келтцу (Jason Keltz) за тестирование, нахождение ошибок и предложений по их устранению;
  • Дину Мюррею (Dean Murray) за предложения;
  • Марио Юнгу (Mario Jung) за указание на отсутствие поддержки кодировки UTF-8;
  • Тому Тренкеру (Tom Trenker) за отчёт об ошибке и правомочные пожелания;
  • Фабрицио Заччи (Fabrizio Zacché) за предложения и отчёты об ошибках;
  • гостям обсуждения Нику, Девону и Майклу (NIk, Devon, Michael) за их предложения и пожелания;
  • Джессе Аламе (Jesse Alama) за отчёты об ошибках;
  • Андерсу Вестербергу (Anders Westerberg) за отчёты об ошибках и интересное предложение;
  • Вильяму Кингсберри (William Kyngesburye) за отчёты об ошибках и пожелания;
  • Питеру Вогту (Pieter Voogt) за отчёт об ошибке;
  • Алексу Кахмару (Alex Kachmar) за отчёт об ошибке и [related code provision];
  • Фредерику Бойеру (Frederic Boyer) за отчёт об ошибке и [related code provision];
  • Михаэлю Вюртцу (Michael Würtz) за отчёт об ошибке;
  • Стефану Беллону (Stefan Bellon) за отчёт об ошибке;
  • гостю обсуждения Джуст (Joost) за отчёт об ошибке;
  • гостю обсуждения Дэймону (Damon) за случайно выявленную опасную уязвимость в версии 0.4.0, отчёт об ошибке и пожелания;
  • Джефри Сакко (Jeffrey Sacco) за пожелания улучшения пользовательского интерфейса и денежное пожертвование;
  • Маркусу Броцио (Markus Brozio) за пожелание улучшения юзабилити.

Возможности

Ниже приводится небольшой список текущих возможностей плагина:

  • поддержка локальных и удалённых баз данных:
    • локальные базы данных хранятся в метапапке текущей страницы посредством SQLite2);
    • базовая поддержка нескольких удалённых баз данных посредством PDO (протестировано: MySQL);
  • интеграция одной таблицы для тега из связанных баз данных;
  • вывод списка всех записей в виде таблицы с поддержкой следующих возможностей:
    • ограничение числа записей на странице, пролистывание страниц, возможность выбора нужной страницы;
    • сортировка по колонке в порядке возрастания/убывания;
    • выбор подмножества выводимых колонок;
    • выбор виртуальных полей, дающих дополнительные имена вычисляемым данным;
  • фильтрация выведенных записей:
    • многокомпонентный фильтр с поддержкой операторов пересечения и объединения;
    • «зашитое» в коде определение (первого) фильтра;
    • дополнительные средства управления фильтром: доступные всегда или требующие авторизации для получения доступа к данной функциональности;
  • вывод одной записи для просмотра содержимого всех её колонок;
  • действия3):
    • добавление новых записей;
    • редактирование существующих записей;
    • удаление существующих записей;
    • копирование существующих записей;
  • несколько типов значений (связанных однозначным соответствием с типами SQL), влияющих на вид и поведение элементов редактора записей:
    • текстовые поля;
    • чекбоксы (флажки);
    • селекторы;
    • загрузка изображений и файлов;
    • «внешние ключи»;
  • блокировка только одной редактируемой записи, позволяющая нескольким пользователям одновременно работать с одной и той же таблицей;
  • авторизация для действий на уровне таблиц, строк, колонок для контроля доступа к поддерживаемым функциям;
  • логгирование (журналирование) всех изменений данных в отдельной таблице;
  • расширенный доступ к данным:
    • экспорт всех или выбранных записей в CSV-файл;
    • экспорт истории изменения в CSV-файл для контроля времени и авторства недавних изменений;
    • вывод специальной версии для печати со списком всех соответствующих записей в виде простого документа4);
  • возможность вывода данных для просмотра с использованием пользовательского оператора SELECT;
  • возможность вывода для просмотра значений, вычисляемых выражений с помощью встроенных функций SQL;
  • опциональная поддержка языка разметки «Докувики» в текстовых значениях;
  • консоль для администрирования SQLite.

Планируемые возможности

  • Поиск и фильтрация.
  • Экспорт в CSV-файл.
  • Хеширование вводимого текста (например, для ввода паролей);
  • Добавление в таблицу недостающих колонок и полей;
  • Окно редактирования для ввода пользовательских SQL-выражений.
  • Поддержка разметки «Докувики» в текстовых выражениях.
  • Добавление Log Viewer (просмотровщика логов) для отслеживания недавних изменений в таблице.
  • По возможности, проверка интеграции с «Докувики».

Известные уязвимости

ПредупреждениеПлагины типа Discussion используются для обеспечения возможности неавторизованным пользователям оставлять комментарии, содержащие любые типы вики-разметки, тем самым позволяя комментирующим использовать теги database2 для записи данных в базы SQLite со страниц вики.

В версиях ниже 0.4.0 отсутствует возможность защиты вашей вики при одновременном использовании плагинов database2 и Discussion (и его аналогов). Поэтому не рекомендуется устанавливать оба плагина одновременно.

Начиная с версии 0.4.0 поддержка database2 должна быть явно разрешена для выбранных страниц вики. Теперь возможно одновременное использование обоих плагинов. Однако на страницах, поддерживающих database2, возможность обсуждения должна быть отключена.

Демонстрация

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

Скачивание и установка

Скопируйте и вставьте следующий адрес в поле менеджера плагинов или нажмите на ссылку для скачивания плагина.

https://github.com/soletan/database2/archive/master.zip

Ссылка для скачивания: .zip

ИнформацияОбратная связь от тестировщиков с радостью принимается по адресу soletan [at] nihilum [dot] de.

Системные требования

  • требуется PHP 5 в связи с использованием:
    • строгой типизации параметров;
    • параметров, передаваемых по ссылке, а также функций;
  • PDO для подключения к базе данных.
    Внимание! Данное требование подразумевает наличие необходимых драйверов для подключения к выбранной базе данных.

Ручная установка (без использования менеджера плагинов)

Установка данного плагина аналогична установке других плагинов: распакуйте скачанный архив в папку lib/plugins «Докувики». Готово!

Текущая версия

Последняя доступная версия 0.4.3 выпущена 18 декабря 2009 года. Список изменений см. в истории версий.

ПредупреждениеТак как с каждым релизом функционал плагина наращивается, становится всё труднее тестировать всю функциональность, реализованную ранее. Несмотря на моё стремление тщательно тестировать новые версии перед каждым релизом, некоторые баги всё же ускользают от моего взгляда. Пожалуйста, не стесняйтесь писать мне, если вам кажется, что в новой версии есть баги.
ПредупреждениеПри обновлении с версии 0.1.x до 0.2.x или более поздней, необходимо поправить настройки всех используемых удалённых баз данных. Как это сделать описано в соответствующем разделе ниже.
ПредупреждениеПри обновлении с версии, предшествующей 0.2.2, необходимо изменить определение статических фильтров, поскольку теперь они не требуют кодирования URL’ов. Достаточно заключить их в двойные кавычки!

Обсуждение

Для обсуждения существует отдельная страница (англ.).

Как использовать плагин?

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

Включение database2

После успешной установки плагина или обновления с версий до 0.4.0, необходимо включить плагин для каждой страницы, где это необходимо. В настройках вики найдите секцию плагина (database2).

Включение плагина на всех страницах

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

Включение плагина на выбираемых страницах

Если универсальная опция, описанная выше, отключена (off), вы можете создать один или несколько шаблонов для выборочного использования тегов database2 на отдельных страницах. Каждый шаблон создаётся в отдельной строке. Каждый шаблон может представлять собой регулярное выражение стандарта PCRE, заключенное в слэши, или шаблон оболочки (shell pattern) с групповыми символами * и ?.

/^software:database2:demo/i
*:database2

Синтаксис

Плагин интегрируется на страницу при помощи специального тега database следующим образом:

<database имя_таблицы [атрибут=значение...]>
описание столбца
описание столбца
...
</database>

Внутри тега находится набор из определений колонок. Также тег должен содержать имя таблицы из подключенной базы данных и может содержать дополнительные опции. Далее в этом документе эти опции называются опциями таблицы, которые следует отличать от опций колонки, т. к. у каждой колонки может быть отдельный набор опций.

Опции таблиц

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

В версии 0.2.1 и ниже использовать закавыченные указанным образом значения нельзя, а значит и нельзя использовать пробелы в строках с присваиваемым значением.

Особым параметром является обязательное имя таблицы, которое принимается без предшествующего ключа и оператора присваивания. Данный параметр может появляться в любом месте списка параметров.

Атрибуты таблицы
Ключ Доступно с версии Описание Примеры
addonclick 0.4.1 Логический «флаг» для выбора, если используется опция колонки onclick, расширяет или заменяет соответствующую команду для текущей строки. addonclick=yes
auth Имя слота в настройках вики, содержащее имя пользователя и пароль, необходимые для доступа к удалённому серверу баз данных. Т. к. исходный код страницы доступен всем, включая неавторизованных пользователей, явное указание пароля и имени пользователя на странице не поддерживается по соображениям безопасности. См. раздел о настройке доступа к удалённой базе ниже! auth=mydbsrv1
basefilter 0.1.8 / 0.3.3 Описание фильтра, используемого первоначально. Ниже идёт секция с описанием синтаксиса для значений этого параметра. Указав фильтр и не показывая элементы управления фильтром, можно выводить список подмножества записей таблицы.
Начиная с версии 0.3.3 строковые значения могут включать разметку по типу той, что описана для значений по умолчанию в соответствующем разделе ниже.
basefilter="email like %.com|surname like bo"
database Явно выбирает локальный файл базы данных или удалённый сервер баз данных для соединения. Значением является или идентификатор страницы для выбора соответствующего файла базы данных, или абсолютный путь к файлу базы данных SQLite, или DSN удалённого сервера базы данных, вводимые после @. См. страницу инструкции PHP по PDO, чтобы узнать больше о DSN! database=/dbfiles/custom.db
mayadmin 0.3.0 См. раздел об авторизациях ниже! mayadmin=!@all
maydelete См. раздел об авторизациях ниже! maydelete=@editor
maydownload См. раздел об авторизациях ниже! maydownload=@user
maydrop См. раздел об авторизациях ниже! maydrop=@admin,manager
mayedit См. раздел об авторизациях ниже! mayedit=@crm
mayexport 0.1.11 Разрешает пользователям и/или группам экспортировать записи в доступный к скачиванию файл для последующей обработки и создания резервных копий. mayexport=@manager
mayfilter 0.1.8 См. раздел об авторизациях ниже! Устанавливает доступность элементов управления фильтром. mayfilter=@manager
mayinsert См. раздел об авторизациях ниже! mayinsert=@crm,!newbie
mayinspect См. раздел об авторизациях ниже! mayinspect=userB
mayprint 0.1.12 Разрешает выводить версию страницы для печати. mayprint=@ALL
mayview См. раздел об авторизациях ниже! mayview=@user,!userA
mayviewlog 0.1.12 Разрешает экспорт истории изменений таблицы в доступный для скачивания CSV-файл. mayviewlog=@ALL
rowsperpage 0.2.3 Задаёт первоначальное максимальное количество записей на странице (доступ к остальным записям в списке осуществляется переходом на следующие страницы). Значения менее 10 игнорируются. rowsperpage=35
simplenav 0.1.20 Логический флаг, отключающий включенную по умолчанию поддержку расширенной навигации в редакторе записи. simplenav=yes
sort 0.2.18 / 0.3.3 Выбирает тип сортировки. Присваиваемое значение является или именем колонки для сортировки по возрастанию, или же именем колонки с восклицательным знаком (!) перед ней для сортировки по убыванию.
Начиная с версии 0.3.3 значение может иметь вид разделённого запятыми списка колонок, подлежащих сортировке.
sort=!colname
view 0.2.2 Вводит произвольный SQL-запрос для получения списка записей для просмотра. Необходимо включить числовой первичный ключ таблицы в список возвращаемых колонок для того, чтобы была возможность выбора отдельной записи для просмотра. Использование данного ключа в некоторых версиях может вести к уязвимости, поэтому необходимо активировать эту опцию в настройках «Докувики»! view="SELECT id,col1 FROM table"
width Задаёт ширину таблицы при отображении её содержимого на странице. Значение может выражаться или целым числом, выражающим ширину в пикселях, или целым числом, предшествующим знаку процента (%), задающим ширину в процентах. Если значение данного ключа не задано, ширина таблицы настраивается таким образом, чтобы вместить все отображаемые данные. width=600 или width=70%
wikimarkup 0.1.14 Логический флаг, включающий поддержку разметки вики в текстовых значениях. Внимание! Использование этой опции значительно снижает скорость отрисовки страниц! wikimarkup=on
wikistyle 0.2.18 Запрос на использование встроенных стилей «Докувики». wikistyle

Определение колонок

Каждая колонка определяется в отдельной строке между открывающим и закрывающим тегами. Строка определения колонки может содержать до четырёх разделённых запятыми полей.

имя_столбца [, [ тип_столбца ] [, [ метка столбца ] [, [ опции столбца ] ] ] ]

В первых трёх полях пробелы в конце и начале строки игнорируются, если поле не заключено в двойные кавычки. Заключенное в кавычки поле может содержать собственно запятые в качестве знаков пунктуации, если другие правила не предписывают иное. Четвёртое поле обрабатывается иначе (см. далее).

Начинающиеся с символов решётки # или двух дробей (слэшей) // пустые строки и строки комментариев игнорируются.

Первое поле: имя колонки

Первое поле является обязательным и содержит имя колонки для внутреннего использования в коде. Имя может состоять только из набора символов ASCII. В случае использования символа не из набора, он автоматически заменяется нижним подчёркиванием. При использовании опции ввода псевдонимов (aliasing) имя колонки становится псевдонимом указанного SQL-запроса.

Второе поле: тип колонки

Во втором поле задаётся тип значений, сохраняемых в колонке. Если это поле отсутствует или его значение не задано, по умолчанию колонке присваивается текстовый тип (text).

Название типа Доступно
с версии
Альтернативный вариант Присваиваемый тип Описание Примеры
acl 0.3.0 Текстовый Набор правил авторизации в контексте текущей записи, блокирующий авторизацию действий на уровне таблицы mayedit=!@all;maydelete=userA,@groupB
check mark, bool, boolean Логический / Целое Флажок «вкл./выкл.»
date Дата / Целое Информация о дате (без времени) — этот тип хранится в БД как юниксовая отметка времени (unix timestamp) (если опция unixts включена) или в формате ГГГГ-ММ-ДД. Даты отображаются в зависимости от настроек вики. 2009/02/11
datetime Дата / Целое Комбинация даты и времени — этот тип хранится в БД как юниксовая отметка времени (unix timestamp) (если опция unixts включена) или в формате ГГГГ-ММ-ДДТЧЧ:ММ:СС. Даты отображаются в зависимости от настроек вики. 2009/02/11 13:53:00
decimal numeric, monetary Десятичная дробь Точное числовое значение. 3,5 или -23,76
enum Список Список с возможностью выбора только одного значения.
Значения указываются после имени типа, разделяются при этом дробью или запятой.
Мужчина / Женщина
file data, blob, binary Данные Один файл. В отличие от файла изображения image, файлы доступны для скачивания при просмотре записей, тогда как изображения отображаются внутри ячеек таблицы
float real, double Действительное число Число с плавающей точкой 3,5 или −23,76
image Данные Графический файл
integer int Целое Целое числовое значение -5 или 3004
mail email Текстовый Адрес электронной почты.
Значения хранятся как строки (текст), но при сохранении проверяются на соответствие формату.
soletan [at] nihilum [dot] de
phone fax Текстовый Телефонный номер
Значения хранятся как строки (текст), но при сохранении проверяются на соответствие формату.
+49 (30) 1234 567-8
related 0.2.11 related Список записей в пользовательском представлении.
Это более динамическая версия списка enum, позволяющая использовать специальный SELECT-запрос, возвращающий числовой идентификатор и название каждой доступной опции списка, отображаемого на странице пользователю. Также, выбранный числовой идентификатор записи сохраняется вместо названия опции.
Заключите определение данного типа в двойные кавычки, чтобы иметь возможность использовать запятую и укажите требуемый SELECT-запрос сразу после ключевого слова related, отделив его пробелом.
"related SELECT id,surname FROM people"
text [default] name, string, char Текстовый Необрабатываемый текст, например, имена и т. п.
Если для колонки выбирается максимальная длина значений меньше 255, в редакторе отображается обычное однострочное поле для ввода, при больших значениях отображается многострочная область ввода.
Вася Пупкин именем не является.
time Время Информация о времени (без даты) в формате ЧЧ:ММ:СС 23:00 или 12:34:56
url link, href Текстовый Абсолютный адрес ссылки на сайт или файл, расположенный на удалённом хосте.
Значения хранятся как строки (текст), но при сохранении проверяются на соответствие формату URL-адреса.
http://www.dokuwiki.org
Третье поле: метка колонки

Для представления в виде списка, а также однострочного детального представления одной записи, каждая колонка может иметь альтернативное название (метку), используемое в шапке списка или в качестве названия поля в однострочном представлении записи. Если значение поля не задано, в качестве названия используется имя, заданное в первом поле.

Четвёртое поле: опции колонки

В четвёртом поле содержатся опции колонки.

Это поле обрабатывается иначе, чем предыдущие. Поле может содержать произвольное число выражений типа «ключ—значение» в том же виде, в котором они используются в HTML-тегах. Вы можете опустить оператор присваивания и следующее за ним значение, таким образом по умолчанию присвоив параметру значение true (истина), что обеспечивает обратную совместимость с предыдущими версиями. Любая информация в четвёртом поле может содержать запятую без необходимости заключать строку в кавычки.

имя = "значение"

Необязательно заключать значение в двойные кавычки. Как и в языке С, закавыченные строки поддерживают escape-последовательности типа \n для перевода на новую строку и \x41 для вывода заглавной буквы A. Также поддерживаются дополнительные пробелы вокруг оператора присваивания, однако нужно помнить, что они влияют на читаемость кода.

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

Несколько параметров в строке разделяются пробелами.

Ключ Доступно
с версии
Тип присваиваемого значения Описание Пример
<integer> Это сокращённая запись (alias) length=<integer>. 32
@<integer> Это сокращённая запись (alias) tabindex=<integer>. @2
accept Шаблон стандарта PCRE Перечисляет принимаемые MIME-типы при загрузке файлов в колонку типа file. accept=§text/§i
aliasing 0.2.0 Выражение SQL Объявляет колонку псевдонимом произвольного выражения SQL, поддерживаемого используемой БД. Неявно маркирует колонку как колонку только для чтения, аналогично ключу readonly (см. выше). Для ввода такого псевдонима SQL-запроса рекомендуется заключать строку в кавычки. Использование данной опции в некоторых версиях может вести к уязвимости, поэтому необходимо активировать эту опцию в настройках «Докувики»! aliasing="upper(surname)"
alwaysshow 0.2.15 Объявляет колонку всегда видимой при просмотре записи. По умолчанию колонки со значением NULL не отображаются. При использовании данной опции колонка будет отображена в любом случае.
Внимание! Эта опция отличается от опции visible ниже!
alwaysshow
booltype xmark, yesno или int Выбирает метод хранения логических маркеров состояния в таблице и поэтому применим только к колонкам типа boolean. Настройка по умолчанию: yesno, при которой хранится y (для значений true/set) или n (для значений false/unset) в таблице, при этом xmark использует x для true и « » (одинарный пробел) для false-значений. int работает с целочисленной колонкой и позволяет выбрать «1» для true или «0» для false. booltype=xmark
default 0.2.2 Значение Объявляет значение колонки по умолчанию, используемое при добавлении новой записи в таблицу. Опция поддерживается всеми типа колонок, кроме типов file и image, если не установлена опция nodefault. См. раздел об установке значений по умолчанию ниже! default="some text"
filter 0.1.8 Явно добавляет колонку в список селектора колонок фильтра. Если этот параметр не применяется к какой-либо колонке, все видимые колонки включаются в список селектора.
Внимание! В список селектора попадают только колонки следующих типов: integer, real, decimal, text, date, enum, bool.
filter
headerlabel 0.3.5 Строка Задаёт иную метку колонки в шапке для использования при отображении. headerlabel="short name"
headerlink 0.4.1 Строка Задаёт абсолютный URL или идентификатор страницы, позволяющий сделать метку колонки в шапке кликабельной при отображении. headerlink="..:glossar#surname"
length Целое число Задаёт максимальную длину строки или файла. Влияет на генерацию SQL-запроса, для создания отсутствующей таблицы и при отображении редактора записи. length=32
mayedit Правило авторизации См. раздел об авторизациях ниже! mayedit=@admin
mayview Правило авторизации См. раздел об авторизациях ниже! mayview=@user,!userA
onclick 0.4.1 / 0.4.2 edit или inspect или ID/URL страницы Вводит зависящее от регистра имя действия для совершения с текущей строкой таблицы по клику на значение в таблице. В зависимости от настроек опции addonclick, данная опция или расширяет, или заменяет соответствующую команду в строке. Правила авторизации пользователя подчиняются настройкам опции.
Начиная с релиза 0.4.2 опция поддерживает идентификаторы страниц и абсолютные URL’ы со значением текущей ячейки посредством использования разметки %{value}.
onclick=edit
nodefault Отменяет заданное изначально значение по умолчанию для колонки, используемое при добавлении новых записей в таблицу. nodefault
noprint 0.2.17 Объявляет таблицу доступной только для просмотра на экране, без возможности печати. noprint
notnull 0.2.9 Не позволяет хранение значений NULL в данной колонке. Использование этой опции влияет на запись пустых/неустановленных значений с использованием 0000-00-00, 0 или пустой строки вместо NULL. notnull
primary Маркирует текущую колонку как первичный ключ (или его часть). Если колонка с такой опцией отсутствует, скрытый идентификатор колонки id автоматически ставится перед вашим набором определений колонки.
Обратите внимание, что все действия над строкой становятся недоступными, если вы определяете многоколоночный или нецелочисленный индекс первичного ключа.
primary
print 0.2.17 Объявляет колонку видимой в версии для печати. print
readonly 0.1.20 Помечает колонку как колонку только для чтения. Отличается от объявления колонки при авторизации для действий на уровне колонки тем, что колонка никогда не записывается в базу снова и тем, что даже администратор не должен редактировать значения колонки. readonly
required Отмечает текущую колонку как обязательную. Включает определение таблицы в SQL-запросе, а также требует от редактора запрашивать непустое значение этой колонки. required
tabindex Целое число Явно выбирает позицию колонки/поля в редакторе строки.
Внимание: все колонки без tabindex отображаются в конце списка колонок с tabindex.
tabindex=2
unique Помечает текущую колонку как уникальный индекс (или его часть). Этот ключ можно дополнить целочисленным суффиксом, тем самым будет определено вхождение в состав того или иного составного индекса. Все колонки с одинаковыми ключом и необязательным целочисленным суффиксом будут преобразованы в один уникальный индекс. unique5
unixts Применяется к колонкам типа date или datetime. Форсирует использование типа Unix timestamp для указанных ранее типов. При этом внутреннее представление даты есть целое число.
Внимание: при хранении в виде юниксовой отметки времени, данные типа «дата», которые не подразумевают хранения времени, содержат скрытое время, равное 12:00 по полудню.
unixts
visible Явно включает текущую колонку в список отображаемых. По умолчанию видны все колонки, однако если для одной из колонок выбрана данная опцию, все остальные колонки становятся невидимыми по умолчанию. visible
wikimarkup 0.2.18 Разрешает обработку вики-разметки в отдельных колонках. Доступно только для колонок типа text!
Внимание! Данная опция снижает скорость отрисовки страниц.
wikimarkup

Авторизация

Плагин предоставляет возможность авторизоваться для выполнения действий на уровне таблицы и на уровне колонки. В версии 0.3.0 была добавлена возможность авторизации на уровне строки таблицы.

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

Авторизация для действий на уровне таблицы

Авторизация для действий на уровне таблицы задаётся в виде параметра в открывающем теге. Базовый синтаксис для работы с такими авторизациями описан в разделах выше. В таблице ниже вы найдёте список всех авторизаций, поддерживаемых на уровне таблицы.

Авторизация Описание Права по умолчанию предоставлены…5)
view Просмотр таблицы в виде списка. всем пользователям
inspect Просмотр одной записи в детальном представлении. всем пользователям
insert Добавление новой записи в таблицу. никому
edit Редактирование существующей записи в таблице. никому
delete Удаление одной записи из таблицы. никому
drop Удаление всей таблицы со всеми записями. никому
download Скачивание файлов или просмотр связанных6) изображений. Зависит от прав view
с версии 0.1.8
filter Доступ к элементам управления фильтрацией вверху списка записей. никому
с версии 0.1.11
export Экспорт записей в доступный для скачивания CSV-файл. Внимание! Экспорт записей включает экспорт всех колонок7) и таким образом отменяет все правила авторизации для просмотра колонок. никому
с версии 0.1.12
print Просмотр специальной версии для печати в формате простого документа8), содержащего все отфильтрованные записи. никому
viewlog Экспорт истории изменений таблицы в доступный для скачивания CSV-файл. никому
с версии 0.3.0
admin Просмотр и редактирование наборов правил ACL на уровне строк. никому
Авторизация для действий на уровне колонки

Авторизация для действий на уровне колонки задаётся в виде опции в четвёртом поле в определении данной колонки. Базовый синтаксис для работы с такими авторизациями описан в разделах выше. В таблице ниже вы найдёте список всех авторизаций, поддерживаемых на уровне колонки.

Авторизация Описание Права по умолчанию предоставлены…9)
view Просмотр колонки в любой записи. всем пользователям
edit Редактирование колонки в любой записи. никому

Также поддерживается специальная комбинация авторизаций view и edit: если пользователь или группа пользователей может редактировать колонку, но не может её видеть, в этой колонке доступными для редактирования будут только новые записи.

В противоположном случае колонка будет доступна только для просмотра. Однако, в текущей реализации это относится только к представленному редактору одной записи. Значение колонки хранится с помощью внутренних механизмов и переписывается в базу снова, вне зависимости от того, были ли произведены изменения. Такая реализация может иметь некоторые побочные эффекты, проявляющиеся, например, в том, что сервер базы данных отказывается записать колонку и таким образом вся запись не сохраняется. Также такие колонки, выводимые только для чтения, всё равно доступны для редактирования администраторами, т. к. администратор обладает всеми доступными правами. Поскольку такое поведение приложения является необходимым в некоторых ситуациях, мы не отказываемся от данной реализации. См. опцию колонки readonly, чтобы полностью запретить запись колонки!

Авторизация для действий на уровне строки

В версии 0.3.0 был введён новый тип колонки acl и была добавлена авторизация для действий на уровне строки. Таблица может иметь только одну колонку типа acl. Подразумевается, что в этой колонке содержится набор правил авторизации, отменяющий все авторизации для действий на уровне таблицы в контексте одной строки. Отменяется только ограниченный набор авторизаций для действий на уровне таблицы: view, inspect, edit, delete, download. Более подробная расшифровка каждого из действий дана в списке авторизаций для действий на уровне таблицы.

Набором правил является разделённый точкой с запятой (;) список из одного и более правила авторизации. Перед каждым таким правилом ставится префикс may, название авторизуемого действия и оператор присваивания. Синтаксис каждого правила приведён в следующем разделе. Пустые правила, например:

mayedit=

игнорируются. Чтобы отменить любую авторизацию действий на уровне таблицы, необходимо ввести непустое правило. Таким образом, в текущей версии чтобы отменить авторизованные (в контексте таблицы или по умолчанию) действия всех пользователей, кроме администраторов, можно использовать правило !@all. Специальный компонент правила @none был введён в версии 0.3.0 и является псевдонимом (alias) для !@all.

Пример

Рассмотрим таблицу, в которой права на действия view и edit имеет пользователь userA, в то время как никто из группы groupA, а также пользователь userB, таких прав не имеют. Значит, чтобы запретить пользователю userA редактирование (edit), дать пользователям из группы groupA право просмотра (view) и дать пользователю userB право просмотра (view) и редактирования (edit), нам нужно использовать следующий набор правил авторизации действий на уровне строки:

mayview=userB,@groupA;mayedit=!userA,userB

Управление авторизацией действий на уровне строки

Любому пользователю может быть дана новая авторизация на действия на уровне таблицы под названием admin, необходимая для просмотра и редактирования колонок типа acl. Вывод этой колонки в таблицу на странице требует явного запроса с помощью опции колонки visible.

Синтаксис правил авторизации

Правило авторизации — это список имён пользователей и названий групп пользователей «Докувики», разделённых запятыми. Также, перед каждым именем может стоять восклицательный знак, исключающий пользователя или группу из списка авторизованных. Помимо этого, для выбора всех пользователей может использоваться специальное имя @ALL. С вводом в версии 0.3.0 набора правил ACL для строки, установка восклицательного знака перед @ALL стала необходимым условием для отзыва права доступа к действиям со строкой у всех обычных пользователей (не администраторов), имеющих этот доступ по умолчанию.

Правила авторизации читаются слева направо. В основном набор пользовательских правил отменяет авторизацию на действия со строкой. Как только доступ получен, обработка правила останавливается и следующие компоненты правила перестают обрабатываться.

Некоторые примеры правил

@editors

Авторизуются все пользователи из группы редакторов — editors.

@editors,!userA

Авторизуются все пользователи из группы редакторов — editors.

!userA,@editors

Авторизуются все пользователи из группы редакторов — editors, кроме пользователя userA.

@editors,userB

Авторизуются все пользователи из группы редакторов — editors и пользователь userB.

Пустые правила авторизации игнорируются.

«Зашитые» в код определения фильтров

Начиная с версии 0.1.8 стало возможно «зашивать» определения фильтров в исходный код страниц. Определение фильтра вводится в тег в виде параметра, становясь «опцией таблицы». В версиях до 0.2.1 в значениях опций таблицы не поддерживаются пробелы, поэтому определение фильтра предполагало быть закодированным с помощью механизма URL encoding. Версии с 0.2.2 и выше поддерживают закавыченные строки, что даёт возможность использовать пробелы и делает невозможным использование механизма кодирования URL encoding.

Определение состоит из одного или нескольких компонентов, разделённых одним (не кодируемым в URL!) амперсандом (&) или вертикальной чертой (|), выбор из которых диктуется необходимостью использовать логическое «И» или логическое «ИЛИ».10) Каждый компонент содержит имя колонки, имя оператора и значение этого оператора. Например:

запрос фамилий с окончанием на %ов

правильно кодируется как (в версии 0.2.1 и ниже)

фамилия+like+%25ов

и выводит все записи, в которых содержатся фамилии с окончанием на «-ов».

Некоторые поддерживаемые операторы не имеют параметров, а значит не требуют указания значения после оператора. Список применимых операторов:

  • like (содержание подстроки);
  • nlike (not like, проверяет, что совпадения по like нет);
  • eq (равно);
  • lt (меньше, чем…);
  • gt (больше, чем…);
  • ne (не равно);
  • le (меньше или равно);
  • ge (больше или равно).

Также, начиная с версии 0.3.0. поддерживаются следующие операторы, не принимающие параметров. Эти операторы применяются только к колонкам логического типа (boolean).

  • isset (проверяет, установлено ли значение логического типа (boolean))
  • isclear (проверяет, что значение логического типа (boolean) не установлено/пусто)

При использовании операторов like или nlike в значении может использоваться групповой символ «%», для подстановки последовательности произвольных символов. Если символ «%» отсутствует в значении, он автоматически подставляется в конце и в начале, обеспечивая простой поиск подстроки.

Любое недопустимое определение компонента игнорируется.

Разметка значений, передаваемых операторам

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

Значения по умолчанию

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

Колонки логического типа (boolean) могут принимать значения типа true (Истина), on (Вкл.), false (Ложь) или off (Выкл.). Селекторы (enum и related) принимают одно из доступных значений из списка опций. Колонки других типов принимают значения по умолчанию в том виде, в котором их указывает пользователь.

Разметка значений по умолчанию

Все версии, начиная c 0.3.2, поддерживают разметку, позволяющую встроить контекстно-зависимые данные из создаваемого вами кода. Такая разметка выглядит следующим образом:

%{ключевое_слово}

где «ключевое_слово» заменяется одним из значений, приводимых в таблице ниже. Каждый маркер заменяется соответствующим актуальным значением ключевого слова в текущем контексте. При замене ключевого слова, знак процента (%) и фигурные скобки ({}) сохраняются. Если маркер использует неизвестное ключевое слово, происходит замена пустой строкой. Все ключевые слова не зависят от регистра.

Ключевое слово Доступно
с версии
Описание соответствующего ключевого слова
date.<format> 0.3.3 текущие дата/время в формате, представленном в строке формата, заменяющей <format> в текущем ключевом слове; синтаксис строки формата такой же, как и для PHP-функции date(), т. е. Y-m-d, что даёт ключевое слово date.Y-m-d
wiki.user 0.3.2 логин авторизованного в настоящий момент пользователя вики
wiki.groups 0.3.2 все группы, членом которых является авторизованный в настоящий момент пользователь вики

В качестве примера рассмотрим выражение типа:

...default="добавил(а) '%{wiki.user}'"

в поле редактора, относящегося к данной колонке, при добавлении новой записи будет подставлено следующее значение:

добавил(а) 'testuser'

если авторизованным в настоящий момент пользователем является testuser.

Полноценный пример

<database addresses width=100% mayinsert=@user>
  # Основная информация
  surname, , Фамилия, 32 visible required @1
  first_name, , Имя, 32 visible required tabindex=2
  gender, enum Муж. / Жен., Пол
  birthday, date, Дата рождения, nodefault
  # Контактная информация
  address, string, Адрес, 64
  phone, phone, № телефона, 32
  email, email, Электропочта, 128 visible required @3 mayview=soletan
  website, url, Сайт
  # Дополнительная информация
  married, bool, Состоите в браке?
  children, integer, # Дети, required
  employed, bool, Наличие работы?, booltype=xmark
  salary, monetary, Зарплата
  daytime, time, Любимое время дня
  start, datetime, Дата начала подписки, nodefault
  time_100m, decimal, Пробегает 100 м за
  foto, image, Ваша фотография, visible
  vcard, file, Ваш vCard
  # Внутренняя информация
  comment, , Комментарий
  validated, bool, Всё правильно, booltype=int required
</database>

Установка базы данных

Локальные базы данных

Плагин управляет файлами локальной базы данных для текущей страницы с помощью SQLite. Предоставлять дополнительную информацию для доступа к файлу БД текущей страницы не нужно.

Разумеется, можно выбрать другой файл базы данных, используя опцию database, следуя инструкциям, приведённым выше.

Удалённые базы данных

ПредупреждениеПоскольку работа этой функции тестировалась только с MySQL, при попытке её применения к другим PDO-драйверам могут возникать ошибки.

Также плагин поддерживает возможность установки связи с удалённым сервером баз данных и позволяет работать с таблицами удалённой базы данных на страницах вашей вики.

ПредупреждениеРабота с таблицами удалённых баз данных может безвозвратно повлиять на их содержимое по причине полного доступа к этим данным.

Для доступа к серверу удалённых баз данных нужны:

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

DSN вводится в открывающем теге, используя параметр database. Чтобы отличать DSN от имени пути доступа к локальным файлам, перед DSN ставится знак «@».

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

  1. указать их в настройках вашей вики, выбрав произвольное «имя слота», например, mydbsrv. Ниже приводятся инструкции для каждой версии плагина database2.
  2. указать выбранное имя слота в параметре auth в открывающем теге, например:
    <database tablename auth=mydbsrv database=@mysql:host=localhost;dbname=mydb>

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

Версии до 0.2.0

Чтобы указать имя пользователя и пароль в версиях database2 до 0.2.0, нужно добавить несколько приведённых ниже строк кода в файл conf/local.protected.php11):

$conf['database2']['mydbsrv']['username'] = 'johndoe';
$conf['database2']['mydbsrv']['password'] = 'foobar';

(Замените johndoe на своё имя, foobar — на свой пароль.)

Версия 0.2.0 и выше

В этой версии способ указания имени пользователя и пароля изменился из-за пересмотра способа интеграции с менеджером настройки «Докувики». Теперь в настройках доступен компонент для многострочного ввода, в который можно ввести определения всех необходимых слотов для использования на страницах вашей вики. Синтаксис описывается следующим образом.

Каждое определение слота вводится отдельной строкой, начинающейся с имени слота. Используя оператор присваивания, пара имя пользователя—пароль, разделённые двоеточием, описывает слот в одной строке. Теперь определение слота из примера, описываемого выше, выглядит следующим образом:

mydbsrv=johndoe:foobar

Брать оператор присваивания в кавычки необязательно, однако, не используя кавычки, нужно помнить об escape-последовательностях. Имя пользователя не может содержать двоеточия, при этом пароль — может.

Опции запросов

Начиная с версии 0.4.3 возможно выбирать одно из поддерживаемых действий с таблицей, используя соответствующую переменную в запросе на странице. Также дополнительно была введена поддержка соответствующих опций запроса.

Данная функциональность пока недостаточно разработана и не слишком полезна. Для её использования необходимо знакомство с GET-запросами протокола HTTP.

Основной формат

Вы можете использовать неограниченное количество элементов в запросе. Обычно элемент запроса содержит имя, оператор присваивания и значение. Плагин database2 распознаёт имена, начинающиеся с префикса db2do и заканчивающиеся суффиксом [n], где n замещается порядковым номером тега <database2> на текущей странице: например, [1] обозначает самый верхний тег <database2>. Между префиксом и суффиксом содержится команда или название опции, иногда сопровождаемое идентификатором строки, к которой применяется команда.

Имя задаётся без пробелов и с учётом регистра.

Имя команды начинается с cmd, опция запроса начинается с opt. Обычно команды интерпретируют случайное значение как true (Истина).

Вывод подробного представления

...?db2docmdinspect97[2]=y

— эта команда открывает подробное представление записи с идентификатором 97 в таблице, интегрированной на выведенную страницу с помощью второго тега <database2>.

...?db2docmdinspect97[2]=y&db2dooptnoctl[2]=1

— эта команда дополнительно скрывает элементы управления, по умолчанию отображаемые внизу страницы подробного представления.

Устранение проблем

Вместо иконок в таблице отображаются текстовые элементы управления

Если используемый набор иконок недоступен, вместо иконок будет отображаться альтернативный текст, нарушающий структуру таблицы из-за большего размера относительно размера иконок.

Все иконки встроены в плагин и устанавливаются в подпапке

/lib/plugins/database2/icons, которая должна быть доступна для HTTP-запросов. Чтобы найти причину отсутствия доступа к иконкам, попробуйте сначала вызвать одну из них вручную, например, используя подобный URL:

http://www.mywikisite.tld/lib/plugins/database2/icons/add.gif

Если в результате запроса вы видите ошибку 404 (Not found), возможно, вы используете путь доступа не в том виде, в котором он должен быть указан.

Если в результате запроса вы видите ошибку 403 (Forbidden), это значит, что доступ к иконкам в папке плагина запрещён. Поскольку по умолчанию в «Докувики» данные папки не защищены, стоит поискать дополнительный файл .htaccess в одной из папок /lib/, /lib/plugins/ и так далее. Ни к одной из этих папок не должны применяться инструкции запрета/разрешения доступа для их защиты.

И наконец, проверьте права доступа в вашей вики. В «Докувики» для файлов могут использоваться права доступа 0660 и 0770 — для папок. Если учётная запись веб-сервера, с правами которой производится попытка доступа к файлу иконки, не является владельцем и не принадлежит к группе, имеющей права доступа к данным файлам, доступ к иконке будет запрещён, что приведёт к выдаче сообщения об ошибке 403.

database2 пытается создать дополнительные таблицы

В разных ситуациях плагин database2 использует до трёх указанных ниже таблиц в связанной базе данных. Эти таблицы создаются автоматически по запросу. Если настройки не позволяют создавать эти таблицы, некоторые действия с отображаемой на странице вики таблицей не могут быть совершены. Выводимые тексты ошибок сообщают о недостаточных правах для выполнения запросов CREATE и создания таблицы.

Чтобы обойти эту проблему, возможно, понадобится создать указанные таблицы вручную, используя аккаунт базы данных с достаточными полномочиями. Здесь понадобятся запросы CREATE, необходимые для создания наших скрытых таблиц.

Первая таблица используется для управления блокировками, устраняющими возникновение параллельных запросов на редактирование одной записи в таблице:

CREATE TABLE __locks (
	tablename CHAR(64) NOT NULL,
	record INTEGER NOT NULL,
	username CHAR(64) NOT NULL,
	obtained INTEGER NOT NULL,
	PRIMARY KEY ( tablename, record )
)

Следующая таблица необходима при добавлении записей в существующую базу данных:

CREATE TABLE __keys (
	tablename CHAR(64) NOT NULL PRIMARY KEY,
	recent INTEGER NOT NULL
)

И наконец, третья таблица используется для логгирования (журналирования) изменений, внесённых в записи и таблицы.

CREATE TABLE __log (
	tablename CHAR(64) NOT NULL,
	rowid INTEGER NULL,
	action CHAR(8) NOT NULL,
	username CHAR(64) NOT NULL,
	ctime INTEGER NOT NULL
)

Дублирование статьи при добавлении/копировании записи

Разумеется, плагин database2 может использоваться для взаимодействия с уже существующей базой данных. Если вы хотите управлять записями посредством database2, вам нужно вручную переписать содержимое таблицы __keys, т. к. именно она используется для выбора следующих доступных значений для числовых первичных ключей при добавлении и копировании записей.

Поддерживаемый MySQL параметр AUTO INCREMENT, поддерживается не всеми базами данных, с которыми работает PDO. Поэтому плагин database2 имеет иной подход к управлению пулом ключей с автоматически генерируемым по возрастанию значением. Этот пул находится в таблице __keys, каждая запись в которой содержит имя соответствующей таблицы и последнего значения ключа, использованного при предыдущем добавлении/копировании записи в эту таблицу.

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

Теги database2 игнорируются / Мои таблицы исчезли!

При обновлении с версий младше 0.4.0 или установке релиза 0.4.0+, необходимо включить поддержку тегов плагина database2 на всех или выбранных страницах вашей вики. Выполнение данного требования позволит предотвратить серьёзные уязвимости.

Откройте панель настроек вашей вики и найдите раздел настроек плагина database2. Включить поддержку database2 на всех страницах можно с помощью всего лишь одной опции, однако мы рекомендуем делать это, только в случае, если вы абсолютно уверены в том, что это действие вам необходимо. Мы рекомендуем использовать шаблоны во второй опции enablepages для включения поддержки тегов database2 только на выбранных страницах.

Пожалуйста, помните, что одновременное включение поддержки плагина database2 и плагинов типа discussion на одной странице открывает серьёзные уязвимости всего вашего сайта/хостинга! Более подробно об уязвимостях можно прочесть выше в разделах «Известные уязвимости» и «Включение database2»!

О переводе

Перевод осуществлён Анной Мартыновой и опубликован под лицензией CC-BY-SA.

1)
Существует плагин с названием database, поэтому цифра 2 была добавлена, чтобы указать на альтернативу.
2)
До недавнего времени базы хранились в namespace (пространстве имён) и являлись доступными для всех страниц из одного пространства имён. Однако такая привязка к пространствам имён представлялась противоречивой и была изменена на привязку к странице. Доступность базы для всех страниц можно обеспечить и в текущей версии, используя явный выбор базы данных в опции таблицы database
3)
доступны, если таблица имеет первичный ключ, состоящий из одной колонки, содержащей целочисленные значения
4) , 8)
документы в универсальной кодировке Plain Vanilla ASCII
5) , 9)
администраторам авторизация доступна всегда
6)
прикреплённых?
7)
колонки, содержащие бинарные данные, такие как файлы или изображения, в общем случае доступны для экспорта, однако не могут быть экспортированы в CSV-файл!
10)
Контроль порядка применения фильтров, например с помощью скобок или подобных знаков, не поддерживается. Порядок применения фильтров зависит от используемой базы данных.
11)
Данный файл используется для хранения пользовательских настроек, на которые не влияет встроенный в «Докувики» инструмент управления настройками Configuration Settings Tool. Если файл отсутствует, вы можете создать его самостоятельно. Не забудьте об открывающих и закрывающих PHP-тегах: <?php и ?>
ru/plugin/database2.txt · Последние изменения: 2016-02-18 07:59 — Aleksandr