Блок «Внешние данные»

Алексей Городков
09.18.24
По умолчанию блок может быть добавлен на страницы СЭО только техническим администратором системы. Настройки блока может проводить Диспетчер-администратор.

1. Назначение и использование

Блок применяется для демонстрации пользователям информации из внешних источников. В качестве источника может выступать:

  • внешняя база данных;
  • сетевое файловое хранилище (например, Яндекс.Диск).

Рис. 2.18.1. Блок «Внешние данные».

Блок может быть размещен на любой странице СЭО 3KL, например, в личном кабинете.

Отображение и передача файлов из внешнего источника осуществляется по протоколу WebDAV.  Система формирует в блоке тексты и адреса ссылок на файлы согласно mustache-шаблона отображения, который настраивается администратором. Файлы могут быть скачаны пользователем.

Рис. 1.2. Тексты и адреса ссылок на файлы согласно шаблону отображения.

Блок отправляет SQL запросы в БД, которые могут содержать макроподстановки (например, id, логин, Email текущего пользователя). При выводе шаблона отображения могут использоваться свойства первого элемента выборки, группировка и сортировка полученных данных. Переход к настройкам блока осуществляется по ссылке «Управление контентом» из самого блока (Рис. 2.18.1). В настройках блока прописываются пути до директории хранилища.

Рис. 1.1. Блок «Внешние данные».

2. Работа с блоком

Технический администратор системы добавляет блок на страницы, где он будет отображаться пользователям (личный кабинет, страницы курса, главная страница сайта). Диспетчер-администратор настраивает тип контента «Записи из базы данных/Файлы по протоколу WebDAV»; указывает путь/запрос к внешнему источнику и Mustache шаблон для вывода данных.

Пользователь видит отображаемые данные в блоке, а при типе контента «Файлы по протоколу» может скачивать файлы по ссылкам из хранилища.

3.Настройки блока

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

Рис. 3.1. Настройки блока в режиме редактирования.

Переход к настройкам блока осуществляется после его добавления на страницу СЭО по ссылке «Управление контентом», расположенной в самом блоке:

Рис. 3.2. Кнопка «Управление контентом» в блоке «Внешние данные».

4. Секция «Настройки типа контента»

Переход к данным настройкам осуществляется из самого блока через кнопку «Управление контентом».

Рис. 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 пользователя, имеющего отношение к просматриваемому профилю
Пример SQL запроса:
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 запросы:

SELECT firstname, lastname FROM [table] WHERE email = {user.email}

или

SELECT * FROM [table] WHERE email = {user.email}
Пример 1. Простой пример для случая, когда в запросе получили имя (firstname) и фамилию (lastname):
{{#has_items}}
{{#items}}
Имя: {{firstname}}; Фамилия: {{lastname}};
{{/items}}
{{/has_items}}
{{^has_items}}
Данных не найдено
{{/has_items}}

 

Пример 2. Помимо имени (firstname) и фамилии (lastname) запрошено наименование программы (programmname), по которой обучается персона, используются дополнительные свойства элементов массива:
{{#has_items}}
{{#items}}
 
{{! Следующий блок будет выведен только для первого элемента выборки }}
{{#first_item}}
Списки персон, изучающих программы
{{/first_item}}
 
{{! Следующий блок будет выведен только когда начинается новая группа повторяющихся значений в поле "Программа" (другими словами, когда начинается новая программа обучения в списке) }}
{{#group_by_programmname_first_in_group}}
{{programmname}}
{{/group_by_programmname_first_in_group}}
 
{{! Следующий блок будет выведен для всех элементов, но строки окрашиваются в разные цвета фона в зависимости от четности строки в выборке }}
{{group_by_programmname_index_num}}. {{lastname}} {{firstname}}
 
{{! Следующий блок будет выведен только для последнего элемента в группе повторяющихся значений (последняя персона для программы обучения, по которым будет сгруппирован список) }}
{{#group_by_programmname_last_in_group}}
Итого подписок на программу "{{programmname}}": {{group_by_programmname_index_num}}
{{/group_by_programmname_last_in_group}}
 
{{! Следующий блок будет выведен только для самого последнего элемента выборки }}
{{#last_item}}
Итого подписок на все программы: {{count_items}}
{{/last_item}}
 
{{/items}}
{{/has_items}}
 
{{^has_items}}
Данных не найдено
{{/has_items}}
Пример 3. Полная настройка блока с отображением данных из внешней БД согласно задаче:
Задача: Требуется отобразить слушателю его успеваемость по очным дисциплинам, которая учитывается в другой системе.  Администратор размещает блок «Внешние данные» в личном кабинете пользователя, создает SQL-запрос к внешней базе данных, где хранится успеваемость по очным занятиям, и настраивает шаблон отображения. Слушатель видит названия дисциплин и оценки в личном кабинете.

Рис. 4.1.2.а. Пример № 3.

Настройки блока:

Рис. 4.1.2.б. Пример № 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 запрос названий программ и слушателей, подписанных на эти программы. По первому запросу (название программы) в mustage-шаблоне выполняется группировка результатов и вывод заголовка выборки. См.скриншот.

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}}
{{programmname}}
{{/group_by_programmname_first_in_group}}
{{group_by_programmname_index_num}}. {{lastname}} {{firstname}} {{middlename}}
{{#group_by_programmname_last_in_group}}
Итого подписок на программу "{{programmname}}": {{group_by_programmname_index_num}}
{{/group_by_programmname_last_in_group}}

{{#last_item}}
Итого подписок на все программы: {{count_items}}
{{/last_item}}

{{/items}}
{{/has_items}}

{{^has_items}}
Данных не найдено
{{/has_items}}

Результат:

Рис. 4.1.2.в. Список персон, изучающих программы.
Пример 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.1.2.г. Пример № 5. Настройка блока с отображением данных из внешней БД.

4.2. Тип контента: Файлы по протоколу WebDAV

Настройка блока для данного типа контента предназначена для отображения и возможности передачи файлов из внешнего источника по протоколу WebDAV (сетевые хранилища файлов, например Яндекс.Диск). Система обращается к серверу WebDav и получает список адресов файлов согласно шаблону, формирует текст ссылки и адрес ссылки согласно шаблону отображения.

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

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

4.2.1. Секция настроек «Конфигурация»

Рис. 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 (система будет искать файлы в этой папке для данного пользователя). 

Пример отображения файлов папки на Яндекс.Диске:

 Рис. 4.2.2.а. Пример отображения файлов папки на Яндекс.Диске.

Пример mustache-шаблона:

{{#has_items}}
{{#items}}
{{/items}}
{{/has_items}}
{{^has_items}}
В вашей директории файлов не найдено
{{/has_items}}

Данная запись выводит текст ссылки, состоящий из basename — имени файла с расширением, и адрес ссылки (URL) — fileurl — ссылки на скачивание файла для каждого файла в директории:

Рис. 4.2.2.б. Ссылки на скачивание файла для каждого файла в директории.

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

Код
{{^has_items}}

В вашей директории файлов не найдено


{{/has_items}}
отображает надпись «В вашей директории файлов не найдено» при отсутствии файлов в указанной (целевой) папке.

4.3. Дополнительная информация о Mustache-шаблонах

Документация о том, как писать шаблоны (Templates) — сайт docs.moodle.org  — ссылка.
Простые уроки, посвященные шаблонизатору Mustache — ссылка.

Теги: блок
Рейтинг ответа: 0 (0 оценок)

Комментарии запрещены