Разработка:XMLDB — различия между версиями

Материал из DOF
Перейти к: навигация, поиск
(→‎Использование визуального редактора для создания таблиц)
м (→‎Код для обновления таблицы)
 
(не показаны 22 промежуточные версии этого же участника)
Строка 1: Строка 1:
 
== Общие сведения ==
 
== Общие сведения ==
 
XML DataBases - это стандартный способ описания таблиц в базе данных Moodle. Он позволяет стандартизировать процесс установки и обновления таблиц. Вся структура таблиц содержится в специальных XML-файлах.  
 
XML DataBases - это стандартный способ описания таблиц в базе данных Moodle. Он позволяет стандартизировать процесс установки и обновления таблиц. Вся структура таблиц содержится в специальных XML-файлах.  
 +
 +
Установочный скрипт для таких таблиц выглядит следующим образом: внутри папки с плагином создается папка db, и в нее кладется файл install.xml, описывающий таблицу, или несколько таблиц в базе данных.
 +
 
== Использование визуального редактора для создания таблиц ==
 
== Использование визуального редактора для создания таблиц ==
−
XML-файлы не ребуется создавать вручную: для этого в Moodle есть специальный XMLDB-редактор. Для того чтобы использовать его вы должны обладать в системе Moodle правами администратора. В панели управления выберите Разное->XMLDB редактор.
+
XML-файлы не требуется создавать вручную: для этого в Moodle есть специальный XMLDB-редактор. Для того чтобы использовать его вы должны обладать в системе Moodle правами администратора.  
 +
 
 +
В панели управления выберите Разное->XMLDB редактор.
  
 
[[Изображение:xmldb_step1.jpeg]]
 
[[Изображение:xmldb_step1.jpeg]]
Строка 14: Строка 19:
 
[[Изображение:xmldb_step3.jpeg]]
 
[[Изображение:xmldb_step3.jpeg]]
  
−
К сожалению, XMLDB-редактор не видит всех таблиц freedeanceoffise, поэтому после создания кода таблицы нам придется скопировать xml-код вручную и вставить его в соответствующий файл.
+
Действия, которые возможно произвести на этой странице:
 +
* '''[View Original]''' - посмотреть оригинальный xml-код для установки базовых таблиц freedeanceoffice. Для создания новой таблицы не понадобится.
 +
* '''[View Edited]''' - посмотреть отредактированный xml-код таблиц. Понадобится для просмотра итогового результата.
 +
* '''[New Table]''' - создать новую таблицу.
 +
* '''[New Table From MySQL]''' - создать новую таблицу из уже существующей. Очень полезно, если вам нужно создать несколько однотипных таблиц в базе данных.
 +
* '''[New Statement]''' - создать новое выражение. Используется для конструирования SQL-выражений.
 +
* '''[Back To Main]''' - вернуться к списку всех таблиц.
 +
* '''[View SQL Code]''' - посмотреть SQL-код для создания всех таблиц.
 +
* '''[View PHP Code]''' - посмотреть PHP-код для создания всех таблиц.
 +
 
 +
=== Создание таблицы ===
 +
Выбирайте '''[New Table]'''. После этого вам отобразится диалог создания новой таблицы:
 +
 
 +
[[Изображение:xmldb_step4.jpeg]]
 +
 
 +
Задайте имя таблицы и комментарий к ней. Имена всех создаваемых вами таблиц должны начинаться с '''block_dof_s_'''. После того, как вы это сделали, можно будет приступать к созданию полей таблицы.
 +
Возможные действия над таблицей:
 +
* '''[View Edited]''' - получить xml-код всей вашей таблицы. Самый главный пункт меню, он пригодится нам, когда создание всех полей и индексов будет закончено.
 +
* '''[New Field]''' - новое поле.
 +
* '''[New Key]''' - новый ключ.
 +
* '''[New Index]''' - новый индекс.
 +
* '''[Back]''' - вернуться назад.
 +
* '''[View SQL Code]''' - посмотреть SQL-код для создания этой таблицы.
 +
* '''[View PHP Code]''' - посмотреть PHP-код для создания этой таблицы.
 +
Обратите внимание, что в таблице уже создано одно новое поля типа int, которое обладает свойствами ''unsigned'', ''not null'' и ''auto-numbered''. Оно также является и первичным ключом таблицы.
 +
 
 +
При создании таблицы в xmldb-редакторе она '''не создается''' в базе данных. Все изменения, которые вы сделаете хранятся исключительно во временном файле.
 +
=== Создание полей ===
 +
Нажимаем '''[New Field]''', появится диалоговое окно создания поля:
 +
 
 +
[[Изображение:xmldb_step5.jpeg]]
 +
 
 +
Параметры:
 +
* ''Name:'' Имя нового поля.
 +
* ''Comment:'' Комментарий к полю. ''Примечание: в версии moodle-1.9.2 и ранее, есть баг, который не добавляет описание к полям таблицы в базе данных. Будем наедятся, что в будущих версиях это будет исправлено.''
 +
* ''Type:'' Тип значения.
 +
* ''Length:'' Длина
 +
* ''Decimals:'' количество знаков после запятой (для типа number)
 +
* ''Unsigned:'' знаковое\беззнаковое значение
 +
* ''Not Null:'' Ненулевое значение
 +
* ''Sequence:'' для поля типа int: производить ли авто-нумерацию (AUTO_INCREMENT)
 +
* ''Enum:'' Для поля типа enum: список значений через запятую. Чтобы это поле стало активным выберите в поле Type значение char.
 +
* ''Default:'' Значение по умолчанию.
 +
 
 +
Действия:
 +
* '''[View Original]''' - Посмотреть оригинальный xml-код для этого поля. Не работает для только что созданных полей.
 +
* '''[View Edited]''' - Посмотреть измененный xml-код этого поля (если вы его редактировали)
 +
* '''[Back]''' - вернуться к редактированию таблицы.
 +
 
 +
Замечания:
 +
* Для хранения всех внешних ключей используется поле типа int длины 11.
 +
* Для хранения времени используйте формат unixtime, и тип int длины 11.
 +
 
 +
=== Создание индексов ===
 +
После создания всех полей таблицы обязательно создайте для них индексы - это значительно ускорит работу с вашей таблицей.
 +
 
 +
Для того чтобы создать индекс, в меню редактирования таблицы нажимаем '''[New Index]''', и переходим на страницу создания индекса:
 +
 
 +
[[Изображение:xmldb_step6.jpeg]]
 +
 
 +
Параметры:
 +
* ''Name:'' имя индекса.
 +
* ''Comment:'' коментарий для индекса.
 +
* ''Type:'' тип индекса: уникальный или нет
 +
* ''Fields:'' индексируемые поля через запятую.
 +
 
 +
Действия:
 +
* '''[View Original]''' - Посмотреть оригинальный xml-код для этого индекса. Не работает для только что созданных индексов.
 +
* '''[View Edited]''' - Посмотреть измененный xml-код этого индекса (если вы его редактировали)
 +
* '''[Back]''' - вернуться к редактированию таблицы.
 +
 
 +
=== Создание ключей ===
 +
После создания индексов можно будет создать ключи для вашей таблицы при помощи команды '''[New Key]''', если это необходимо.
 +
 
 +
[[Изображение:xmldb_step7.jpeg]]
 +
 
 +
Параметры:
 +
* ''Name:'' имя ключа
 +
* ''Comment:'' комментарий к ключу
 +
* ''Type:'' тип ключа
 +
** primary - первичный
 +
** unique - уникальный
 +
** foreign - внешний
 +
** foreign-unique - внешний-уникальный
 +
* ''Fields:'' поля для ключа
 +
* ''Reftable:'' для внешних ключей - имя внешней таблица для ключа
 +
* ''Reffields:'' для внешних ключей - имя поля во внешней таблице
 +
 
 +
Действия:
 +
* '''[View Original]''' - Посмотреть оригинальный xml-код для этого индекса. Не работает для только что созданных ключей.
 +
* '''[View Edited]''' - Посмотреть измененный xml-код этого ключа (если вы его редактировали)
 +
* '''[Back]''' - вернуться к редактированию таблицы.
 +
 
 +
=== Получение xml-кода и создание файла установки ===
 +
К сожалению, XMLDB-редактор не видит всех таблиц freedeanceoffiсe, поэтому после создания таблицы нам придется скопировать ее xml-код вручную и вставить его в соответствующий файл (install.xml).
 +
После того, как вы описали все поля, ключи и индексы в меню редактирования таблицы нажимаете '''[View Edited]'''. Вы автоматически перейдете на страницу с xml-кодом таблицы. Если ваш браузер попытается прочесть ее как обычную web-страницу, то настройте его таким образом, чтобы все xml-файлы он открывал при помощи текстового редактора.
 +
 
 +
Сохраните весь xml-код <nowiki>(от <TABLE> до </TABLE>)</nowiki> в install.xml.
 +
 
 +
Теперь нужно вставить дополнительные xml-теги, для того чтобы инсталлятор понял ваш файл
 +
 
 +
Перед тегом <nowiki><TABLE></nowiki> нужно вставить код:
 +
<pre>
 +
  <?xml version="1.0" encoding="UTF-8" ?>
 +
  <XMLDB PATH="blocks/deansoffice/db" VERSION="20090515" COMMENT="XMLDB file for Moodle blocks/deansoffice"
 +
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 +
      xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd">
 +
    <TABLES>
 +
</pre>
 +
''Здесь идет вся ваша таблица, и после нее в конце надо вставить закрывающие теги:''
 +
    </TABLES>
 +
  </XMLDB>
 +
Перед установкой таблицы не забудьте убрать свойство "previous" из тега <nowiki><TABLE></nowiki>, иначе при запуске установочного скрипта возникнет ошибка.
 +
    <TABLE NAME="block_dof_s_testtable" COMMENT="Комментарий к таблице" <span style="color:#FF0000"><strike>'''PREVIOUS="block_dof_events"'''</strike></span>>
 +
После этого ваша таблица готова к установке.
 +
 
 +
== Создание установочных скриптов ==
 +
В этом разделе будет рассмотрено, как создавать скрипты установки для создания и обновления базы данных. Важно помнить о том, что скрипты для установки понадобятся вам '''только''' в том случае, когда вы будете обновлять плагин storage. Если вы создаете новый плагин, то достаточно будет создать install.xml установки.
 +
=== Код для обновления таблицы ===
 +
Весь код для обновления таблицы должен содержаться в методе upgrage($oldversion) плагина storage. Этот код можно получить, нажав '''[View PHP Code]''' на странице редактирования таблицы.
 +
 
 +
Выведется диалоговое окно для автоматического создания кода:
 +
 
 +
[[Изображение:xmldb_step8.jpeg]]
 +
 
 +
В данном примере, для простоты я взял таблицу с названием ''block_dof_s_testtable'' только с тремя полями. Поскольку мы имеем дело с модификацией структуры таблицы, нам нужно будет составить код отдельно для каждого поля.
 +
 
 +
Для этого у XMLDB-редактора уже есть готовый список действий, рассмотрим их:
 +
 
 +
'''Select Action''' - действие, которое надо произвести.
 +
* Добавить поле (индекс или ключ)
 +
* Переименовать поле (индекс или ключ)
 +
* Удалить поле (индекс или ключ)
 +
 
 +
'''Select Field/Key/Index''' - к какому полю/ключу/индексу нужно применить это действие.
 +
Выбираете нужное значение из списка.
 +
 
 +
После этого нажимаете '''view''', и получаете PHP-код действия, которое вы выбрали.
 +
 
 +
Все действия, которые вы хотите произвести нужно помещать внутрь контейнера вида:
 +
    if ($oldversion < XXXXXXXXXX)
 +
    {
 +
''Тут идет код всех ваших изменений''
 +
    }
 +
 
 +
Здесь ''XXXXXXXXXX'' - самая новая версия плагина storage (например 2009062300). Синтаксис обращения к методам XMLDBTable и XMLDBField описан ниже.
 +
 
 +
Если вы несколько раз модифицируете плагин, то самые старые контейнеры изменений должны находится вверху, самые новые - внизу функции upgrade().
 +
 
 +
Логика работы обновлений такая: сначала устанавливается таблица из XML-файла, а затем на нее одно за другим накладываются все обновления: от более старого к более новому. При обновлении таблицы также следует поправить xml-файл, добавив в него xml-код новых полей, а также '''изменив версию''' (в самом начале файла).
 +
 
 +
Все скрипты обновления должны помещаться в папке "'''storage/<название_плагина>/init.php'''", внутри функции upgrade(). Пример можно посмотреть в хранилище examplest. Для того чтобы обновление таблицы сработало необходимо обновить версию плагина в файле init.php
 +
 
 +
=== Основные методы класса XMLDBTable ===
 +
=== Основные методы класса XMLDBField ===
 +
 
 +
== Удаление временных данных ==
 +
После того, как вы получили xml-файл со своей таблицей желательно удалить ее из xmldb-редактора. Для этого в меню редактирования всех таблиц freedeansoffice напротив созданной вами таблицы нажмите '''[Delete]'''.
  
−
== Создание скриптов установки ==
+
== Запись изначальных данных в таблицу ==
 +
== Ссылки ==
 +
* [http://docs.moodle.org/en/Development:XMLDB_Documentation Справка по XMLDB на английском]

Текущая версия на 15:04, 4 ноября 2010

Общие сведения

XML DataBases - это стандартный способ описания таблиц в базе данных Moodle. Он позволяет стандартизировать процесс установки и обновления таблиц. Вся структура таблиц содержится в специальных XML-файлах.

Установочный скрипт для таких таблиц выглядит следующим образом: внутри папки с плагином создается папка db, и в нее кладется файл install.xml, описывающий таблицу, или несколько таблиц в базе данных.

Использование визуального редактора для создания таблиц

XML-файлы не требуется создавать вручную: для этого в Moodle есть специальный XMLDB-редактор. Для того чтобы использовать его вы должны обладать в системе Moodle правами администратора.

В панели управления выберите Разное->XMLDB редактор.

Xmldb step1.jpeg

Вам отобразится весь список таблиц, которые есть в Moodle. Мы будем работать только с таблицами freedeanceoffice, которые обозначены как blocks/dof/db.

Xmldb step2.jpeg

Выбирайте функцию [load] для того чтобы начать работать с таблицами. После этого строчка таблицы станет зеленой, и ссылка [edit] станет активной. Нажмите на нее. Появится диалоговое окно работы с таблицами freedeansoffise:

Xmldb step3.jpeg

Действия, которые возможно произвести на этой странице:

  • [View Original] - посмотреть оригинальный xml-код для установки базовых таблиц freedeanceoffice. Для создания новой таблицы не понадобится.
  • [View Edited] - посмотреть отредактированный xml-код таблиц. Понадобится для просмотра итогового результата.
  • [New Table] - создать новую таблицу.
  • [New Table From MySQL] - создать новую таблицу из уже существующей. Очень полезно, если вам нужно создать несколько однотипных таблиц в базе данных.
  • [New Statement] - создать новое выражение. Используется для конструирования SQL-выражений.
  • [Back To Main] - вернуться к списку всех таблиц.
  • [View SQL Code] - посмотреть SQL-код для создания всех таблиц.
  • [View PHP Code] - посмотреть PHP-код для создания всех таблиц.

Создание таблицы

Выбирайте [New Table]. После этого вам отобразится диалог создания новой таблицы:

Xmldb step4.jpeg

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

  • [View Edited] - получить xml-код всей вашей таблицы. Самый главный пункт меню, он пригодится нам, когда создание всех полей и индексов будет закончено.
  • [New Field] - новое поле.
  • [New Key] - новый ключ.
  • [New Index] - новый индекс.
  • [Back] - вернуться назад.
  • [View SQL Code] - посмотреть SQL-код для создания этой таблицы.
  • [View PHP Code] - посмотреть PHP-код для создания этой таблицы.

Обратите внимание, что в таблице уже создано одно новое поля типа int, которое обладает свойствами unsigned, not null и auto-numbered. Оно также является и первичным ключом таблицы.

При создании таблицы в xmldb-редакторе она не создается в базе данных. Все изменения, которые вы сделаете хранятся исключительно во временном файле.

Создание полей

Нажимаем [New Field], появится диалоговое окно создания поля:

Xmldb step5.jpeg

Параметры:

  • Name: Имя нового поля.
  • Comment: Комментарий к полю. Примечание: в версии moodle-1.9.2 и ранее, есть баг, который не добавляет описание к полям таблицы в базе данных. Будем наедятся, что в будущих версиях это будет исправлено.
  • Type: Тип значения.
  • Length: Длина
  • Decimals: количество знаков после запятой (для типа number)
  • Unsigned: знаковое\беззнаковое значение
  • Not Null: Ненулевое значение
  • Sequence: для поля типа int: производить ли авто-нумерацию (AUTO_INCREMENT)
  • Enum: Для поля типа enum: список значений через запятую. Чтобы это поле стало активным выберите в поле Type значение char.
  • Default: Значение по умолчанию.

Действия:

  • [View Original] - Посмотреть оригинальный xml-код для этого поля. Не работает для только что созданных полей.
  • [View Edited] - Посмотреть измененный xml-код этого поля (если вы его редактировали)
  • [Back] - вернуться к редактированию таблицы.

Замечания:

  • Для хранения всех внешних ключей используется поле типа int длины 11.
  • Для хранения времени используйте формат unixtime, и тип int длины 11.

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

После создания всех полей таблицы обязательно создайте для них индексы - это значительно ускорит работу с вашей таблицей.

Для того чтобы создать индекс, в меню редактирования таблицы нажимаем [New Index], и переходим на страницу создания индекса:

Xmldb step6.jpeg

Параметры:

  • Name: имя индекса.
  • Comment: коментарий для индекса.
  • Type: тип индекса: уникальный или нет
  • Fields: индексируемые поля через запятую.

Действия:

  • [View Original] - Посмотреть оригинальный xml-код для этого индекса. Не работает для только что созданных индексов.
  • [View Edited] - Посмотреть измененный xml-код этого индекса (если вы его редактировали)
  • [Back] - вернуться к редактированию таблицы.

Создание ключей

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

Xmldb step7.jpeg

Параметры:

  • Name: имя ключа
  • Comment: комментарий к ключу
  • Type: тип ключа
    • primary - первичный
    • unique - уникальный
    • foreign - внешний
    • foreign-unique - внешний-уникальный
  • Fields: поля для ключа
  • Reftable: для внешних ключей - имя внешней таблица для ключа
  • Reffields: для внешних ключей - имя поля во внешней таблице

Действия:

  • [View Original] - Посмотреть оригинальный xml-код для этого индекса. Не работает для только что созданных ключей.
  • [View Edited] - Посмотреть измененный xml-код этого ключа (если вы его редактировали)
  • [Back] - вернуться к редактированию таблицы.

Получение xml-кода и создание файла установки

К сожалению, XMLDB-редактор не видит всех таблиц freedeanceoffiсe, поэтому после создания таблицы нам придется скопировать ее xml-код вручную и вставить его в соответствующий файл (install.xml). После того, как вы описали все поля, ключи и индексы в меню редактирования таблицы нажимаете [View Edited]. Вы автоматически перейдете на страницу с xml-кодом таблицы. Если ваш браузер попытается прочесть ее как обычную web-страницу, то настройте его таким образом, чтобы все xml-файлы он открывал при помощи текстового редактора.

Сохраните весь xml-код (от <TABLE> до </TABLE>) в install.xml.

Теперь нужно вставить дополнительные xml-теги, для того чтобы инсталлятор понял ваш файл

Перед тегом <TABLE> нужно вставить код: 

  <?xml version="1.0" encoding="UTF-8" ?>
  <XMLDB PATH="blocks/deansoffice/db" VERSION="20090515" COMMENT="XMLDB file for Moodle blocks/deansoffice"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd">
    <TABLES>

Здесь идет вся ваша таблица, и после нее в конце надо вставить закрывающие теги: 

   </TABLES>
 </XMLDB>

Перед установкой таблицы не забудьте убрать свойство "previous" из тега <TABLE>, иначе при запуске установочного скрипта возникнет ошибка. 

   <TABLE NAME="block_dof_s_testtable" COMMENT="Комментарий к таблице" PREVIOUS="block_dof_events">

После этого ваша таблица готова к установке.

Создание установочных скриптов

В этом разделе будет рассмотрено, как создавать скрипты установки для создания и обновления базы данных. Важно помнить о том, что скрипты для установки понадобятся вам только в том случае, когда вы будете обновлять плагин storage. Если вы создаете новый плагин, то достаточно будет создать install.xml установки.

Код для обновления таблицы

Весь код для обновления таблицы должен содержаться в методе upgrage($oldversion) плагина storage. Этот код можно получить, нажав [View PHP Code] на странице редактирования таблицы.

Выведется диалоговое окно для автоматического создания кода:

Xmldb step8.jpeg

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

Для этого у XMLDB-редактора уже есть готовый список действий, рассмотрим их:

Select Action - действие, которое надо произвести.

  • Добавить поле (индекс или ключ)
  • Переименовать поле (индекс или ключ)
  • Удалить поле (индекс или ключ)

Select Field/Key/Index - к какому полю/ключу/индексу нужно применить это действие. Выбираете нужное значение из списка.

После этого нажимаете view, и получаете PHP-код действия, которое вы выбрали.

Все действия, которые вы хотите произвести нужно помещать внутрь контейнера вида: 

    if ($oldversion < XXXXXXXXXX)
    {

Тут идет код всех ваших изменений 

    }

Здесь XXXXXXXXXX - самая новая версия плагина storage (например 2009062300). Синтаксис обращения к методам XMLDBTable и XMLDBField описан ниже.

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

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

Все скрипты обновления должны помещаться в папке "storage/<название_плагина>/init.php", внутри функции upgrade(). Пример можно посмотреть в хранилище examplest. Для того чтобы обновление таблицы сработало необходимо обновить версию плагина в файле init.php

Основные методы класса XMLDBTable

Основные методы класса XMLDBField

Удаление временных данных

После того, как вы получили xml-файл со своей таблицей желательно удалить ее из xmldb-редактора. Для этого в меню редактирования всех таблиц freedeansoffice напротив созданной вами таблицы нажмите [Delete].

Запись изначальных данных в таблицу

Ссылки

Источник — «http://docs.deansoffice.ru/wiki/index.php?title=Разработка:XMLDB&oldid=1886»