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

Материал из DOF
Версия от 16:47, 8 декабря 2009; Ilya (обсуждение | вклад) (Примеры кода: Дополнено описание использования dof_modlib_widgets_form)
Перейти к: навигация, поиск
Плагин
Название 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 - начиная с какой записи начать выводить список.

  • 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, то таблица не будет распечатана, а будет возвращен только ее код

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

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_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_form

Подключение библиотеки форм
   $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);
   }