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

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

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

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

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

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

Блок отправляет SQL запросы в БД, которые могут содержать макроподстановки (например, id, логин, Email текущего пользователя). При выводе шаблона отображения могут использоваться свойства первого элемента выборки, группировка и сортировка полученных данных. Переход к настройкам блока осуществляется по ссылке «Управление контентом» из самого блока (Рис. 1.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 пользователя, имеющего отношение к просматриваемому профилю

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}}

{{/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).

Код Mustache-шаблона отображения для данного примера:

{{#items}}{{/items}}

Данный шаблон формирует таблицу с тремя колонками, с заголовками колонок, с помощью цикла {{#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

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}}

{{/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. Примеры

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

Пример 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 — ссылка.