Блок «Внешние данные»
1. Назначение и использование
2. Работа с блоком
3. Настройки блока
4. Секция «Настройки типа контента»
4.1. Тип контента: «Записи из базы данных»
4.1.1. Секция настроек «Конфигурация»
4.1.2. Примеры
4.2. Тип контента: «Файлы по протоколу WebDAV»
4.2.1. Секция настроек «Конфигурация»
4.2.2. Примеры
4.3. Дополнительная информация о Mustache-шаблонах
1. Назначение и использование
Блок применяется для демонстрации пользователям информации из внешних источников. В качестве источника может выступать:
- внешняя база данных;
- сетевое файловое хранилище (например, Яндекс.Диск).
Блок может быть размещен на любой странице СЭО 3KL, например, в личном кабинете.
Отображение и передача файлов из внешнего источника осуществляется по протоколу WebDAV. Система формирует в блоке тексты и адреса ссылок на файлы согласно mustache-шаблона отображения, который настраивается администратором. Файлы могут быть скачаны пользователем.
Блок отправляет SQL запросы в БД, которые могут содержать макроподстановки (например, id, логин, Email текущего пользователя). При выводе шаблона отображения могут использоваться свойства первого элемента выборки, группировка и сортировка полученных данных. Переход к настройкам блока осуществляется по ссылке «Управление контентом» из самого блока (Рис. 2.18.1). В настройках блока прописываются пути до директории хранилища.
2. Работа с блоком
Технический администратор системы добавляет блок на страницы, где он будет отображаться пользователям (личный кабинет, страницы курса, главная страница сайта). Диспетчер-администратор настраивает тип контента «Записи из базы данных/Файлы по протоколу WebDAV»; указывает путь/запрос к внешнему источнику и Mustache шаблон для вывода данных.
Пользователь видит отображаемые данные в блоке, а при типе контента «Файлы по протоколу» может скачивать файлы по ссылкам из хранилища.
3.Настройки блока
Настройки блока в режиме редактирования стандартны. Можно ввести заголовок блока, определить страницы и регионы, где будет отображаться блок:
Переход к настройкам блока осуществляется после его добавления на страницу СЭО по ссылке «Управление контентом», расположенной в самом блоке:
4. Секция «Настройки типа контента»
Переход к данным настройкам осуществляется из самого блока через кнопку «Управление контентом».
Тип контента: Записи из базы данных/Файлы по протоколу WebDAV.
Данная настройка определяет тип источника контента, который будет передавать (транслировать) блок. После выбора типа контента и применения изменений открывается секция настроек «Конфигурация». В зависимости от типа контента рассматриваются два варианта дальнейших настроек блока и примеров его использования:
3.1. Тип контента: «Записи из базы данных»
3.2. Тип контента: «Файлы по протоколу WebDAV»
4.1. Тип контента: «Записи из базы данных»
Эта настройка предназначена для трансляции данных из внешней БД с помощью SQL запросов. Блок транслирует данные с помощью SQL запросов, поддерживающих макроподстановки. В целях безопасности плагин позволяет выполнять только SELECT запросы.
4.1.1. Секция настроек «Конфигурация»
В настройках указываются реквизиты подключения к внешней базе данных, SQL-запрос и mustache-шаблон для отображения:
Тип базы данных. Выбор типа БД из выпадающего списка
Хост. Имя хоста с БД
Логин
Пароль
Имя базы данных
Команда для настройки SQL. Например, здесь можно прописать: SET NAMES 'utf8'
SQL-запрос — запрос к БД, поддерживает макроподстановки. Возможны только SELECT запросы.
Для sql-запроса можно использовать макроподстановки, которые в коде заключаются в скобки: {user.id}:
- {user.id} — id текущего пользователя
- {user.username} — логин текущего пользователя
- {user.email} — Email текущего пользователя
- {user.idnumber} — внешний id текущего пользователя
- {course.id} — id курса, на странице которого размещен блок
- {course.shortname} — короткое имя курса, на странице которого размещен блок
- {course.idnumber} — внешний id курса, на странице которого размещен блок
- {course.category} — id категории курса, на странице которого размещен блок
- {profilepage.userid}— id пользователя, имеющего отношение к просматриваемому профилю
SELECT * FROM [table] WHERE email = {user.email} ORDER BY [field]
Данный запрос сделает выборку записей из внешней таблицы [table], у которых значение поля email совпадает с email пользователя Moodle, передающийся с помощью макроподстановки {user.email} и отсортирует эти записи по полю [field].
Mustache-шаблон — шаблон для отображения в блоке.
Объект, передаваемый в шаблон отображения обладает следующими свойствами:
- items. Массив записей, полученных по указанному SQL запросу с результатами выборки из внешнего хранилища. Каждый элемент этого массива содержит значения в соответствии с теми полями, которые запрашивались, и которые можно использовать в Mustache-шаблоне по своим именам. Для отображения внешних данных необходимо перебрать массив «items».
- has_items. Является ли массив «items» не пустым.
- count_items. Количество элементов в массиве «items».
Каждый элемент в массиве items — это строка выборки, которая будет иметь поля, указанные в sql-запросе. Кроме полей из запроса, в каждый элемент добавлены дополнительные свойства. Пример:
Первый элемент выборки first_item
В результатах выборки из внешнего источника первый элемент выборки содержит отметку. При формировании шаблона отображения это дополнительное свойство может быть использовано для вывода сведений о первом элементе выборки отдельно, например, в заголовке для сгруппированных/отсортированных элементов.
При формировании шаблона отображения необходимо проверить, является ли элемент выборки первым, это осуществляется использованием конструкции (пример):
{{#items}}
{{#first_item}}
Первый элемент!
{{/first_item}}
{{/items}}
Дополнительные свойства элементов массива: - first_item. Является ли первым в выборке.
- last_item. Является ли последним в выборке.
- even_item. Является ли четным элементом.
- odd_item. Является ли нечетным элементом.
- item_index_num. Порядковый номер элемента в выборке.
Для случаев, когда требуется отобразить выборку, имеющую повторяющиеся данные в одном поле, но при отображении не следует повторять эти данные в каждой строке, а нужно вывести отдельно, можно, предварительно отсортировав выборку по такому полю, использовать для оформления следующие свойства:
- group_by_[название поля]_first_in_group. Является ли элемент первым в группе повторяющихся значений для указанного поля
- group_by_[название поля]_last_in_group. Является ли элемент последним в группе повторяющихся значений для указанного поля
- group_by_[название поля]_index_num. Порядковый номер элемента в группе повторяющихся значений для указанного поля
4.1.2. Примеры
Каждый элемент массива items содержит значения в соответствии с теми полями, которые запрашивались, и которые можно использовать в Mustache-шаблоне по своим именам. Например, если запись содержит поля field1, field2, то в шаблоне в цикле по items так и нужно указывать подстановки field1 и field2 в тех местах, где нужно вывести значения этих полей. Данная запись выводит значения из полей firstname и lastname, которые ожидаются в массиве items в ходе выполнения запроса в базу:
{{#items}}
Имя: {{firstname}}; Фамилия: {{lastname}};
{{/items}}
Для этого подойдут такие SQL запросы:
или
Пример 1. Простой пример для случая, когда в запросе получили имя (firstname) и фамилию (lastname):
{{#has_items}} {{#items}}
{{/items}} {{/has_items}} {{^has_items}}
{{/has_items}}
Пример 2. Помимо имени (firstname) и фамилии (lastname) запрошено наименование программы (programmname), по которой обучается персона, используются дополнительные свойства элементов массива:
{{#has_items}} {{#items}} {{! Следующий блок будет выведен только для первого элемента выборки }} {{#first_item}}
{{/first_item}} {{! Следующий блок будет выведен только когда начинается новая группа повторяющихся значений в поле "Программа" (другими словами, когда начинается новая программа обучения в списке) }} {{#group_by_programmname_first_in_group}}
{{/group_by_programmname_first_in_group}} {{! Следующий блок будет выведен для всех элементов, но строки окрашиваются в разные цвета фона в зависимости от четности строки в выборке }}
{{! Следующий блок будет выведен только для последнего элемента в группе повторяющихся значений (последняя персона для программы обучения, по которым будет сгруппирован список) }} {{#group_by_programmname_last_in_group}}
{{/group_by_programmname_last_in_group}} {{! Следующий блок будет выведен только для самого последнего элемента выборки }} {{#last_item}}
{{/last_item}} {{/items}} {{/has_items}} {{^has_items}}
{{/has_items}}
Пример 3. Полная настройка блока с отображением данных из внешней БД согласно задаче:
Настройки блока:
SQL-запрос:
SELECT name, hours, grade FROM externaldata WHERE moodleid = {user.id} ORDER BY name
Это запрос данных (SELECT) сделает выборку записей из внешней таблицы (externaldata), у которых поле moodleid совпадает с id текущего пользователя Moodle ( {user.id} — id текущего пользователя). Запрашиваются названия дисциплин (name), часы(hours) и оценки за дисциплину (grade), также здесь включена сортировка данных по имени дисциплины (ORDER BY name).
name, hours, grade — это значения полей name (название), hours (часы), grade (оценка) из таблицы БД;
SELECT * FROM externaldata — выбрать все поля из таблицы externaldata.
WHERE moodleid = {user.id} — выборка записей из БД, у которых значение в поле moodleid совпадает с ID текущего пользователя Moodle — передается с помощью макроподстановки {user.id}.
Код Mustache-шаблона отображения для данного примера:
{{#items}}{{/items}}
Дисциплина | Кол-во часов | Оценка |
---|---|---|
{{name}} | {{hours}} | {{grade}} |
Данный шаблон формирует таблицу с тремя колонками, с заголовками колонок, с помощью цикла {{#items}} ... {{/items}} выводит значения в ячейки соответствующих колонок из полей name, hours и grade, которые ожидаются в массиве items в ходе выполнения запроса в базу.
Пример 4. Полная настройка блока с отображением данных из внешней БД согласно задаче:
SQL-запрос в Электронный деканат:
SELECT p.lastname, p.firstname, p.middlename, c.num as contractnum, prog.name as programmname FROM mdl_block_dof_s_persons as p LEFT JOIN mdl_block_dof_s_contracts as c on p.id=c.studentid LEFT JOIN mdl_block_dof_s_programmsbcs as pbcs ON pbcs.contractid=c.id LEFT JOIN mdl_block_dof_s_programms as prog ON prog.id=pbcs.programmid WHERE prog.id IS NOT NULL ORDER BY prog.id, p.id
получить поля p.lastname, p.firstname, p.middlename, c.num as contractnum, prog.name as programmname
из таблиц mdl_block_dof_s_persons, mdl_block_dof_s_contracts, mdl_block_dof_s_programmsbcs, mdl_block_dof_s_programms
при условии, что программа обучения указана
сортировать по идентификатору программы, потом по идентификатору персоны
Mustache-шаблон:
{{#has_items}} {{#items}} {{#first_item}}
{{/first_item}} {{#group_by_programmname_first_in_group}}
{{/group_by_programmname_first_in_group}}
{{#group_by_programmname_last_in_group}}
{{/group_by_programmname_last_in_group}} {{#last_item}}
{{/last_item}} {{/items}} {{/has_items}} {{^has_items}}
{{/has_items}}
Результат:
Пример 5. Настройка блока с отображением данных из внешней БД:
SQL-запрос в «Электронный деканат»:
SELECT p.lastname, p.firstname, p.middlename, c.num as contractnum, prog.name as programmname
FROM mdl_block_dof_s_persons as p
LEFT JOIN mdl_block_dof_s_contracts as c on p.id=c.studentid
LEFT JOIN mdl_block_dof_s_programmsbcs as pbcs ON pbcs.contractid=c.id
LEFT JOIN mdl_block_dof_s_programms as prog ON prog.id=pbcs.programmid
WHERE prog.id IS NOT NULL
ORDER BY prog.id, p.id
Mustache-шаблон:
{{#has_items}}
{{#items}}{{/items}}
lastname | firstname | middlename | contractnum | programmname | first_item | group_by_programmname_first_in_group | group_by_programmname_index_num | group_by_programmname_last_in_group | even_item | odd_item | last_item | count_items |
---|---|---|---|---|---|---|---|---|---|---|---|---|
{{lastname}} | {{firstname}} | {{middlename}} | {{contractnum}} | {{programmname}} | {{#first_item}}Да{{/first_item}}{{^first_item}}Нет{{/first_item}} | {{#group_by_programmname_first_in_group}}Да{{/group_by_programmname_first_in_group}}{{^group_by_programmname_first_in_group}}Нет{{/group_by_programmname_first_in_group}} | {{group_by_programmname_index_num}} | {{#group_by_programmname_last_in_group}}Да{{/group_by_programmname_last_in_group}}{{^group_by_programmname_last_in_group}}Нет{{/group_by_programmname_last_in_group}} | {{#even_item}}Да{{/even_item}}{{^even_item}}Нет{{/even_item}} | {{#odd_item}}Да{{/odd_item}}{{^odd_item}}Нет{{/odd_item}} | {{#last_item}}Да{{/last_item}}{{^last_item}}Нет{{/last_item}} | {{count_items}} |
{{/has_items}}
{{^has_items}}
{{/has_items}}
Результат:
4.2. Тип контента: Файлы по протоколу WebDAV
Настройка блока для данного типа контента предназначена для отображения и возможности передачи файлов из внешнего источника по протоколу WebDAV (сетевые хранилища файлов, например Яндекс.Диск). Система обращается к серверу WebDav и получает список адресов файлов согласно шаблону, формирует текст ссылки и адрес ссылки согласно шаблону отображения.
В базовом URL-адресе можно указать порт (при необходимости), а также возможно использование серверов без поддержки абсолютных путей. Таким образом, если организация использует нестандартные настройки WebDav сервера, администратор имеет возможность учесть их при настройке блока.
За счет хэширования путей к внешним файлам обеспечивается безопасность использования блока, таким образом пользователь сможет скачать только те файлы, которые были отображены ему в списке по условиям фильтрации.
4.2.1. Секция настроек «Конфигурация»
В настройках указываются реквизиты подключения к к серверу WebDav, путь к директории и шаблон отображения. В пути к директории сервера и в шаблоне можно использовать макроподстановки, заключаемые при написании в скобки: {user.id}.
- Базовый url сервера. Пример для Яндекс.Диска: https://webdav.yandex.ru . Вводится как в примере и схема (протокол), и хост. По схеме в дальнейшем автоматически определяется стандартный сокет подключения, порт. Здесь можно указать порт (при необходимости), а также возможно использование серверов без поддержки абсолютных путей.
- Имя пользователя для подключения (можно оставить пустым, если не требуется авторизация). Например, логин для сервисов Яндекса.
- Пароль для подключения. Например, пароль к сервисам Яндекса.
- Путь до директории, содержимое которой требуется отобразить. Если нужно отобразить файлы из корня WebDAV-сервера, в этом поле указывается слэш «/» (без кавычек). Некоторые WebDAV-серверы могут придерживаться строгих правил при указании пути. Необходимо проверить, чтобы на конце пути до директории стоял слэш «/», например: «/data/{user.id}/».
Для пути до директории можно использовать подстановки:- {user.id} — id текущего пользователя,
- {user.username} — логин текущего пользователя,
- {user.email} — Email текущего пользователя,
- {user.idnumber} — внешний id текущего пользователя,
- {course.id} — id курса, на странице которого размещен блок,
- {course.shortname} — короткое имя курса, на странице которого размещен блок,
- {course.idnumber} — внешний id курса, на странице которого размещен блок,
- {course.category} — id категории курса, на странице которого размещен блок,
- {profilepage.userid} — id пользователя, имеющего отношение к просматриваемому профилю.
-
Mustache-шаблон — шаблон для отображения в блоке. Для отображения внешних данных нужно перебрать массив «items», который будет содержать результат запроса во внешнее хранилище. Каждый элемент в массиве «items» - файл из директории, которая указана в настройках. Файл имеет следующие свойства:
- fileurl — ссылка на скачивание файла,
- basename — имя файла с расширением,
- filename — имя файла без расширения,
- extension — расширение файла.
4.2.2. Примеры
/SDO/{user.id}/ — переход в папку SDO и в подпапку, соответствующую {user.id} — id текущего пользователя СЭО, например /SDO/25/ для пользователя с ID=25 (система будет искать файлы в этой папке для данного пользователя).
Чаще применяется выборка по внешнему ID текущего пользователя {user.idnumber}. В этом случае путь может быть задан таким образом:
/SDO/{user.idnumber}/ — переход в папку SDO и в подпапку, соответствующую {user.idnumber} - внешний id текущего пользователя, например /SDO/41/ для пользователя с внешним ID=41 (система будет искать файлы в этой папке для данного пользователя).
Пример отображения файлов папки на Яндекс.Диске:
Пример mustache-шаблона:
{{#has_items}} {{#items}}
{{/items}} {{/has_items}} {{^has_items}}
{{/has_items}}
Данная запись выводит текст ссылки, состоящий из basename — имени файла с расширением, и адрес ссылки (URL) — fileurl — ссылки на скачивание файла для каждого файла в директории:
При клике на имя файла в блоке браузер предлагает открыть или скачать указанный файл.
Код
{{^has_items}}
{{/has_items}}
отображает надпись «В вашей директории файлов не найдено» при отсутствии файлов в указанной (целевой) папке.
4.3. Дополнительная информация о Mustache-шаблонах
Документация о том, как писать шаблоны (Templates) — сайт docs.moodle.org — ссылка.
Простые уроки, посвященные шаблонизатору Mustache — ссылка.