Разработка:modlibs/widgets

Плагин
Название	widgets
Тип	modlibs

Описание

В этом плагине располагаются все виджеты - дополнительные средства визуального оформления интерфейса.

Структура папок

Для каждого виджета в папке widgets создается отдельная папка с его названием. Внутри этой папки должен лежать файл lib.php, в котором содержится класс виджета. Все дополнительные файлы, относящиеся к этому виджету (если они требуются) - должны лежать в этой же папке.

Стандарт именования классов

Все классы виджетов должны называться по схеме dof_modlib_widgets_<название_виджета>.

API

webform()

Инициализировать библиотеку форм. Этот метод отвечает за подключение библиотеки moodleQuickForm. Если вы хотите использовать moodleQuickForm, то она подключается только при помощи этого метода. Подключение класса moodleQuickForm (или moodleform) напрямую не допускается.

form_classname()

Аналог метода webform. В настоящее время не используется. Он оставлен только для совместимости, не используйте его в новых функциях.

progressbar($name, $percent, $width, $process, $auto_create)

Эта функция пригодится, если вам понадобится вывести прогрессбар - полоску, которая в реальном времени отображает ход выполнения какого-либо долгого процесса.

Возвращает экземпляр класса dof_modlib_widgets_progress_bar. Параметры:

$name - имя html-элемента. Если прогрессбаров несколько на странице, то имена не должны повторяться.

$percent - начальное процентное значение.

$width - длина в пикселях.

$process - название процесса, который выполняется в текущий момент (загрузка... сохранение... и т. п.)

$auto_create - для этого формата возможны два значения:

true - сразу же отправить html-код прогрессбара в выходной поток. false - только создать объект, не выводя progressbar. По умолчанию true.

=== pages_navigation() === - подключает класс pages_navigation. Служит для отображения ссылок на страницы при постраничном выводе списка данных.

$code - код плагина, для которого будут созданы ссылки на страницы.

$recordscount - общее количество записей на всех страницах

$limitnum - по сколько записей нужно выводить на одной странице. По умолчанию NULL (вывести все на одной странице)

$limitfrom - начиная с какой записи начать выводить список.

notice_yesno($message, $linkyes, $linkno, $optionsyes=NULL, $optionsno=NULL, $methodyes='post', $methodno='post')

Выводит сообщение подтверждение да/нет для дальнейшей работы с пользователем

$message - код плагина, для которого будут созданы ссылки на страницы.

$linkyes - общее количество записей на всех страницах

$linkno - по сколько записей нужно выводить на одной странице. По умолчанию NULL (вывести все на одной странице)

$optionsyes - начиная с какой записи начать выводить список.

$optionsno - общее количество записей на всех страницах

$methodyes - по сколько записей нужно выводить на одной странице. По умолчанию NULL (вывести все на одной странице)

$methodno - начиная с какой записи начать выводить список.

print_table($table, $return=false)

Распечатывает хорошо отформатированную таблицу, использующую текущую тему оформления moodle

Параметры:

$table - стандартный объект со следующими свойствами

• $table->head - Массив заголовков таблицы. (если не задан - выведутся только данные)
• $table->align - Массив, который хранит параметры горизонтального выравнивания текста в колонках
• $table->size - Массив размеров колонок
• $table->wrap - Массив, отвечающий за возможность переноса текста внутри колонки. Возможные значения:
  • wrap (переносить)
  • nowrap (не переносить)
• $table->data[] - Массив, каждый элемент которого является массивом значений строки таблицы
• $table->width - ширина таблицы в пикселях или процентах
• $table->tablealign - Расположение всей таблицы
• $table->cellpadding - html-параметр cellpadding
• $table->cellspacing - html-параметр cellspacing
• $table->class - html-параметр "class", отвечающий за то, какой
  • стиль должен быть сопоставлен этой таблице
• $table->id - html-параметр "id" для использования getElementById()
• $table->rowclass[] - массив названий css-классов для добавления их к специальным рядам
• $table->summary - общее описание содержимого таблицы.

$return - если true, то таблица не будет распечатана, а будет возвращен только ее код

print_box_start($classes='generalbox', $ids=' ', $return=false)

Распечатывает начало блока (запуск окна с помощью дива)

Параметры:

$classes - имена классов через пробел(по умолчанию generalbox)

$ids - имена id через пробел

$return - возвращает как строку или просто распечатывает его

Возвращает смешанную строку или ничего

print_box_end($return=false)

Распечатывает конец блока

Параметры:

$return - возвращает как строку или просто распечатывает его

Возвращает смешанную строку или ничего

js_init()

Подключить js-библиотеку (вместе со стилями) или набор скриптов, по переданному коду. Все виждеты, которые используют javascript должны использовать эту функцию для подключения своих скриптов.

Параметры:

- $code - код библиотеки которую следует подключить

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

ifield()

Получить объект интерактивно редактируемого поля. То есть текст, на который кликаешь, а он становится полем редактирования и через ajax отправляет сохраненные данные.

Параметры:

• $plugintype - тип плагина, который будет предоставлять и сохранять данные
• $plugincode - код плагина, который будет предоставлять и сохранять данные
• $queryname - тип запроса (тип запроса - как правило имя поля)
• $objectid - id объекта, который редактируется
• $type - тип элемента. Это параметра type для тега input. Допустимые значения: text, textarea, select
• $text - текст, который отображается на элементе до редактирования
• $options - массив или строка дополнительных html-параметров для div-элемента, содержащего поле редактирования. По умолчанию null.

При обращении к этому методу также автоматически подключаются все js-библиотеки, которые нужны для отображения и работы этого элемента, поэтому его следует вызывать до вывода заголовка (print_header)

save_ifield()

Сохранить данные при inline-редактировании. Сохраняет одно поле. Ищет в переданном плагине функцию widgets_save_field, и передает в нее тип запроса ($querytype), id объекта ($objectid) и новое значение поля ($data). Если такой функции нет - возвращает ошибку.

Функция widgets_save_field должна вернуть либо новое, измененное значение поля, либо html-код ошибки.

• $plugintype - тип плагина, который отвечает за сохранение поля
• $plugincode - код плагина, который отвечает за редактирование поля
• $querytype - уникальный код запроса внутри плагина. Как правило - имя сохраняемого поля
• $objectid - id объекта, поля которого редактируются
• $data - данные в формате json (или просто строка), пришедшие из формы редактирования объекта.

Возвращает новое, обновленное значение параметра из базы, или html-код ошибки.

load_ifield()

Загрузить данные для inline-редактирования поля. Этот метод вызывается непосредственно перед редактированием поля, загружая значения из базы, для того чтобы пользователю, который редактирует данные, предоставлялась максимально актуальная информация. Ищет в плагине функцию widgets_load_field , и передает в нее название поля ($querytype), id объекта ($objectid) и новое значение поля ($data). Если такой функции нет - возвращает ошибку.

Функция widgets_load_field должна вернуть либо значение поля, либо html-код ошибки.

• $plugintype - тип плагина, который отвечает за редактироване поля
• $plugincode - код плагина, который отвечает за редактироване поля
• $fieldname - поле объекта, которое нужно запросить
• $objectid - id объекта, который редактируется
• $data - дополнительные данные для загрузки объекта

Возвращает значение поля, которое будет отображаться в редактируемом элементе.

Дополнительные классы

dof_modlib_widgets_progress_bar

• __construct($name, $percent, $width, $process, $auto_create)

Параметры:

$name - имя html-элемента. Если прогрессбаров несколько на странице, то имена не должны повторяться.

$percent - начальное процентное значение.

$width - длина в пикселях.

$process - название процесса, который выполняется в текущий момент (загрузка... сохранение... и т. п.)

$auto_create - для этого формата возможны два значения:

true - сразу же отправить html-код прогрессбара в выходной поток. false - только создать объект, не выводя progressbar. По умолчанию true.

• create() - вывести html-код прогрессбара в браузер. Эту функцию не нужно использовать, в случае если в конструкторе $auto_create стоит true.
• set_name($name) - установить имя html-элемента, которым является прогрессбар. Внутренний метод, вызывается из конструктора.
• set_percent($percent) - установить начальное процентное значение для полоски прогрессбара.

$percent - количество начальных процентов, от 0 до 100.

• set_percent_adv($cur_amount,$max_amount) - увеличить полоску прогрессбара. Полоска увеличивается в зависимости от того, сколько задач уже выполнено, а сколько еще осталось.

$cur_amount - количество уже выполненных задач

$max_amount - общее количество задач, которое надо выполнить.

• set_width($width) - установить длину прогрессбара в пикселях. Внутренний метод, используется из конструктора.

dof_modlib_widgets_form

Класс, наследующий moodleform. Имеет собственные методы, предназначенные для работы с нашими модулями Подробнее об использовании moodleQuickForm можно прочитать в разделе Работа с moodleQuickForm.

dof_get_select_values()

Получить массив, пригодный для составления элементов select и hierselect.

Параметры

• $records - массив записей из storage. Ожидаемый формат данных - массив объектов. По умолчанию false.
• $firstelm - (по умолчанию - true) задать первый элемент списка. Возможные значения:
  • true - нужен стандартый первый элемент array(0 => '--- Выбрать ---')
  • false - первый элемент не нужен
  • массив в формате "ключ"=>"значение" из одного, или нескольких элементов, которые нужно добавить в начало списка
• $key - какое поле БД использовать в качестве ключа (это значение отправится формой). По умолчанию 'id'
• $namefields - одно или несколько полей, которые будут видны пользователю в списке. Каждое последующее поле после первого будет заключено в квадратные скобки. По умолчанию 'name'. Формат:
  • строка: если отобразить нужно только одно поле
  • массив, с названиями полей - если полей нужно несколько. Поля выведутся именно в том порядке, в котором вы их указали

Возвращаемые значения:

• array - массив для составления select-элемента
• bool - false в случае ошибки. Возможные ошибки:
  • В переданном списке у объектов нет нужных полей
  • Для ключа массива есть неуникальные значения

dof_modlib_widgets_pages_navigation

• __construct($dof, $code, $count, $limitnum=NULL, $limitfrom) - конструктор класса. Осуществляет все проверки данных.
  • $dof - объект класса dof_control
  • $code - код плагина, для которого будут созданы ссылки на страницы.
  • $count - общее количество записей на всех страницах
  • $limitnum - по сколько записей нужно выводить на одной странице. По умолчанию NULL (вывести все на одной странице).
  • $limitfrom - начиная с какой записи начать выводить список.
• get_navpages_list($adds, $vars) - Возвращает html-строку навигации, разбивая ленту таблицы или списка на страницы. Нумерация страница всегда начинается с единицы
  • $adds - дополнительный путь внутри плагина, и список дополнительных параметров для ссылки в виде строки
  • $vars - список дополнительных параметров для ссылки в виде массива в формате "ключ" => "значение"
• get_page_link($pagenum, $limitfrom, $adds, $vars) - Возвращает ссылку на страницу или страницу без ссылки, если она является текущей.
  • $pagenum - номер страницы
  • $limitfrom - номер записи, с которой начинается просмотр
  • $adds - дополнительный путь внутри плагина, и список дополнительных параметров для ссылки в виде строки
  • $vars - список дополнительных параметров для ссылки в виде массива в формате "ключ" => "значение"
• get_current_page() - Получить номер страницы по номеру текущей записи, и количеству записей на странице
• get_total_pages() - Возвращает общее количество страниц для отображения
• get_current_limitfrom() - Возвращает исходный параметр номера записи, с которого начинается просмотр
• get_current_limitnum() - Возвращает исходный параметр минимального количества записей на странице

dof_modlib_widgets_addremove

Класс для составления стандартного элемента "добавить\удалить". Элемент представляет собой двусторонний список с двумя html-элементами Select. Используется для автоматизации процесса добавления и удаления элементов из какой-либо категории или группы. Позволяет одновременно передавать несколько элементов.

• __construct($DOF, $action=, $formid='dof_modlib_widgets_addremove') - конструктор класса.
  • $DOF объект класса dof_control
  • $action - ссылка на страницу-обработчик формы. По умолчанию - эта же страница.
  • $formid - id html-элемента на странице. Используется для скрипта, который делает кнопки "добавить" или "удалить" неактивными, в зависимости от того, какое из полей select выбрано.
• set_default_strings($values)
• set_add_list($options, $extradata=null)
• set_remove_list($options, $extradata=null)
• set_complex_add_list($options)
• set_complex_remove_list($options)
• check_add_remove_array($data) - проверить пришедший из формы массив элементов для добавления или удаления.
  • $data - массив элементов, пришедший из $_POST
  • Возвращаемое значение: (array) - массив числовых значений идентификаторов.
• print_html() - распечатать html-код элемента.
• get_html() - получить html-код элемента для последующей распечатки.
• assemble_templater_data() - Внутренний метод.
• get_complex_options_template_data($groups, $type) - Внутренний метод.
• get_simple_options_template_data($options, $extradata=null) - Внутренний метод.
• get_search_default_strings() - Внутренний метод.
• get_form_default_strings() - Внутренний метод.

dof_modlib_widgets_ifield

Класс, отвечающий за элемент inline-редактирования. Создает элемент, который при помощи AJAX-запросов

__construct()

Параметры

• $dof - объект класса dof_control
• $plugintype - тип плагина, который будет предоставлять и сохранять данные
• $plugincode - код плагина, который будет предоставлять и сохранять данные
• $queryname - тип запроса (тип запроса - как правило имя поля)
• $objectid - id объекта, который редактируется
• $type - тип элемента. Это параметра type для тега input. Допустимые значения: text, textarea, select
• $text - текст, который отображается на элементе до редактирования
• $options - массив или строка дополнительных html-параметров для div-элемента, содержащего поле редактирования. По умолчанию null.

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

get_html()

Получить html-код элемента. После создания объекта этот метод можно вызывать несколько раз, каждый раз указывая новый id. Все нужные параметры (текст скрипта, и т. п.) будут пересчитаны автоматически.

Параметры

• $objectid - id редактируемого объекта
• $text - текст, который отображается вместо элемента, пока не нажата кнопка "редактировать". Разрешено html-форматирование
• $options - Массив или строка дополнительных html-параметров для div-элемента, содержащего поле редактирования.

display()

Вывести элемент. После создания объекта этот метод можно вызывать несколько раз, каждый раз указывая новый id. Все нужные параметры (текст скрипта, и т. п.) будут пересчитаны автоматически.

Параметры

• $objectid - id редактируемого объекта
• $text - текст, который отображается вместо элемента, пока не нажата кнопка "редактировать". Разрешено html-форматирование
• $options - Массив или строка дополнительных html-параметров для div-элемента, содержащего поле редактирования.

set_options()

Метод для установки параметров класса вручную. Используется в том случае, когда всех приведенных выше методов недостаточно.

Параметры:

• $options - массив свойств класса в формате ключ-значение.

Примеры кода

Стандартные формы

Здесь будут приведены примеры работы с классов dof_modlib_widgets_form. Этот класс наследует находящийся в moodle класс moodleform. Подробнее о нем можно посмотреть в разделе: Разработка:moodleQuickForm

Подключение библиотеки форм

   $DOF->modlib('widgets')->webform();

Получение массива нужного формата для составления select-элементов

   // получаем список всех учебных периодов из нашей таблицы "ages"
   // Отсортированных по названию
   $ages = $this->dof->storage('ages')->get_list(null, null, "name ASC")
   // задаем массив из нескольких собственных первых элементов для списка:
   // они добавятся в начало
   $firstelms = array(54 => 'Элемент 1', 'abc' => 'Элемент 2');
   // указываем, какое поле из массива объектов нужно брать в качестве ключа 
   // (значения должны быть уникальными!)
   $idfield = 'id';
   // указываем, какие поля БД нужно выводить пользователю
   $showfields = array('name', 'eduweeks');
   // получаем массив нужной структуры для составления select-элемента.
   $selectdata = $this->dof_get_select_values($ages, $firstelms, $idfield, $showfields);

Использование прогрессбара

1. Устанавливаем параметры

   $name        = 'pbar'; // имя html-элемента, только латинские буквы
   $percent     = 1;      // начинаем с отметки 1%
   $width       = 200;    // длинна полоски 200 пикселей
   $process     = 'Идет сохранение...'; // какой процесс происходит
   $auto_create = true;   // вывести прогрессбар сразу же после создания объекта

2. Создаем нужный объект

   $progressbar = $DOF->modlib('widgets')->progressbar($name, $percent, $width, $process, $auto_create)

3. Вставляем прогрессбар внутрь цикла с выполняемым процессом

   for ($i=1; $i<=333; $i++)
   {
       // номер текущей выполняемой задачи
       $cur_task  = $i;
       // общее количество задач, которое надо выполнить их количество можно менять в ходе выполнения процесса
       (например, если сразу неясно сколько точно шагов будет у цикла)
       $num_tasks = 333; 
       // внутри цикла производим все трудоемкие операции...
       
       ...
       
       sleep(0.1);// для теста: чтобы было видно как ползет полоска
       // после того как проведены все операции увеличиваем длину полоски на чуть-чуть
       $progressbar->set_percent_adv($cur_task,$num_tasks);
   }