mirror_php/moodle
1
0
Fork 0
mirror of https://github.com/moodle/moodle.git synced 2025-04-19 23:42:11 +02:00
Code Issues Projects Releases Wiki Activity

MDL-78279 output: user choice output class

Browse Source 
A class to represent a generic user choice. Other output compoments
can use this output to render user choices like selects, modals or
dropdowns.
This commit is contained in:
Ferran Recio 2023-06-14 13:59:25 +02:00
parent e3645f663b
commit 59bda4137d
2 changed files with 383 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

188
lib/classes/output/choicelist.php Normal file
View File

@ -0,0 +1,188 @@
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
namespace core\output;
use renderable;
use renderer_base;
/**
* A generic user choice output class.
*
* This class can be used as a generic user choice data structure for any dropdown, modal, or any
* other component that offers choices to the user.
*
* @package core
* @copyright 2023 Ferran Recio <ferran@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class choicelist implements renderable {
/** @var object[] The user choices. */
protected $options = [];
/** @var string the selected option. */
protected $selected = null;
/** @var string the choice description. */
protected $description = null;
/**
* Constructor.
*
* @param string $description the choice description.
*/
public function __construct(?string $description = null) {
$this->description = $description;
}
/**
* Add option to the user choice.
*
* The definition object could contain the following keys:
* - string description: the description of the option.
* - \moodle_url url: the URL to link to.
* - \pix_icon icon: the icon to display.
* - bool disabled: whether the option is disabled.
* - bool selected: whether the option is selected.
* - array extras: an array of HTML attributes to add to the option (attribute => value).
*
* @param string $value
* @param string $name
* @param array $definition an optional array of definition for the option.
*/
public function add_option(string $value, string $name, array $definition = []) {
$option = [
'value' => $value,
'name' => $name,
'description' => $definition['description'] ?? null,
'url' => $definition['url'] ?? null,
'icon' => $definition['icon'] ?? null,
'disabled' => (!empty($definition['disabled'])) ? true : false,
];
if (!empty($definition['selected'])) {
$this->selected = $value;
}
$this->options[$value] = $option;
if (isset($definition['extras'])) {
$this->set_option_extras($value, $definition['extras']);
}
}
/**
* Set the selected option.
*
* @param string $value The value of the selected option.
*/
public function set_selected_value(string $value) {
$this->selected = $value;
}
/**
* Get the selected option.
*
* @return string|null The value of the selected option.
*/
public function get_selected_value(): ?string {
return $this->selected;
}
/**
* Set the general choice description option.
*
* @param string $value the new description.
*/
public function set_description(string $value) {
$this->description = $value;
}
/**
* Get the choice description option.
*
* @return string|null the current description.
*/
public function get_description(): ?string {
return $this->description;
}
/**
* Set the option disabled.
*
* @param string $value The value of the option.
* @param bool $disabled Whether the option is disabled.
*/
public function set_option_disabled(string $value, bool $disabled) {
if (isset($this->options[$value])) {
$this->options[$value]['disabled'] = $disabled;
}
}
/**
* Set the option disabled.
*
* @param string $value The value of the option.
* @param array $extras an array to add HTML attributes to the option (attribute => value).
*/
public function set_option_extras(string $value, array $extras) {
if (!isset($this->options[$value])) {
return;
}
$extrasattributes = [];
foreach ($extras as $attribute => $attributevalue) {
$extrasattributes[] = [
'attribute' => $attribute,
'value' => $attributevalue,
];
}
$this->options[$value]['extras'] = $extrasattributes;
}
/**
* Export for template.
*
* @param renderer_base $output The renderer.
* @return array
*/
public function export_for_template(renderer_base $output): array {
$options = [];
foreach ($this->options as $option) {
if (!empty($option['icon'])) {
$option['icon'] = $option['icon']->export_for_template($output);
}
$option['hasicon'] = !empty($option['icon']);
if (!empty($option['url'])) {
$option['url'] = $option['url']->out(true);
}
$option['hasurl'] = !empty($option['url']);
if ($option['value'] == $this->selected) {
$option['selected'] = true;
}
$option['optionnumber'] = count($options) + 1;
$option['first'] = count($options) === 0;
$option['optionuniqid'] = \html_writer::random_id('choice_option_');
$options[] = $option;
}
return [
'description' => $this->description,
'options' => $options,
'hasoptions' => !empty($options),
];
}
}

195
lib/tests/output/choicelist_test.php Normal file
View File

@ -0,0 +1,195 @@
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* Unit tests for core\output\choice class.
*
* @package core
* @category test
* @copyright 2023 Ferran Recio <ferran@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
namespace core\output;
use advanced_testcase;
/**
* Unit tests for the `icon_system` class.
*
* @coversDefaultClass \core\output\choicelist
*/
class choicelist_test extends advanced_testcase {
/**
* Test for a choice without options.
*
* @covers ::_construct
* @covers ::add_option
* @covers ::export_for_template
*/
public function test_empty_export(): void {
$page = new \moodle_page();
$page->set_url('/user/profile.php');
$page->set_context(\context_system::instance());
$renderer = $page->get_renderer('core');
$choice = new choicelist('Choose an option');
$export = $choice->export_for_template($renderer);
$this->assertEquals('Choose an option', $export['description']);
$this->assertEquals(false, $export['hasoptions']);
$this->assertEquals([], $export['options']);
}
/**
* Test for a choice with basic options.
*
* @covers ::_construct
* @covers ::add_option
* @covers ::export_for_template
*/
public function test_basic_export(): void {
$page = new \moodle_page();
$page->set_url('/user/profile.php');
$page->set_context(\context_system::instance());
$renderer = $page->get_renderer('core');
$choice = new choicelist('Choose an option');
$choice->add_option('option1', 'Option 1');
$choice->add_option('option2', 'Option 2');
$export = $choice->export_for_template($renderer);
$this->assertEquals('Choose an option', $export['description']);
$this->assertEquals(true, $export['hasoptions']);
$this->assertCount(2, $export['options']);
$this->validate_option($export['options'][0], 'option1', 'Option 1', []);
$this->validate_option($export['options'][1], 'option2', 'Option 2', []);
}
/**
* Test for a choice with extras options definition.
*
* @covers ::_construct
* @covers ::add_option
* @covers ::set_option_extras
* @covers ::export_for_template
*/
public function test_option_defintion_export(): void {
$page = new \moodle_page();
$page->set_url('/user/profile.php');
$page->set_context(\context_system::instance());
$renderer = $page->get_renderer('core');
$choice = new choicelist('Choose an option');
$definition1 = [
'disabled' => true,
'description' => 'Description',
'url' => new \moodle_url('/user/profile.php'),
'icon' => new \pix_icon('i/grade', 'Grade'),
'extras' => [
'data-attribute' => 'value',
],
];
$choice->add_option('option1', 'Option 1', $definition1);
$definition2 = [
'disabled' => false,
'description' => null,
'url' => null,
'icon' => null,
'extras' => null,
];
$choice->add_option('option2', 'Option 2', $definition2);
$export = $choice->export_for_template($renderer);
$this->assertEquals('Choose an option', $export['description']);
$this->assertEquals(true, $export['hasoptions']);
$this->assertCount(2, $export['options']);
$definition1['iconexport'] = $definition1['icon']->export_for_template($renderer);
$this->validate_option($export['options'][0], 'option1', 'Option 1', $definition1);
$this->validate_option($export['options'][1], 'option2', 'Option 2', $definition2);
}
/**
* Test for a choice with option selected.
*
* @covers ::_construct
* @covers ::add_option
* @covers ::set_selected_value
* @covers ::get_selected_value
* @covers ::export_for_template
*/
public function test_option_selected_export(): void {
$page = new \moodle_page();
$page->set_url('/user/profile.php');
$page->set_context(\context_system::instance());
$renderer = $page->get_renderer('core');
$choice = new choicelist('Choose an option');
$choice->add_option('option1', 'Option 1');
$choice->add_option('option2', 'Option 2');
$choice->set_selected_value('option1');
$export = $choice->export_for_template($renderer);
$this->assertEquals('Choose an option', $export['description']);
$this->assertEquals(true, $export['hasoptions']);
$this->assertCount(2, $export['options']);
$this->assertEquals('option1', $choice->get_selected_value());
$this->validate_option($export['options'][0], 'option1', 'Option 1', [], true);
$this->validate_option($export['options'][1], 'option2', 'Option 2', []);
}
/**
* Validate a choice option export.
* @param array $option the option export
* @param string $value the option value
* @param string $name the option name
* @param array|null $definition the option definition
* @param bool $selected if the option is selected
*/
private function validate_option(
array $option,
string $value,
string $name,
?array $definition,
bool $selected = false
): void {
$this->assertEquals($value, $option['value']);
$this->assertEquals($name, $option['name']);
$this->assertEquals($definition['disabled'] ?? false, $option['disabled']);
$this->assertEquals($definition['description'] ?? null, $option['description']);
if (isset($definition['url'])) {
$this->assertEquals($definition['url']->out(true), $option['url']);
$this->assertTrue($option['hasurl']);
}
if (isset($definition['icon'])) {
$this->assertEquals($definition['iconexport'], $option['icon']);
$this->assertTrue($option['hasicon']);
}
if ($selected) {
$this->assertTrue($option['selected']);
}
if (isset($definition['extras'])) {
foreach ($option['extras'] as $extra) {
$attribute = $extra['attribute'];
$this->assertEquals($definition['extras'][$attribute], $extra['value']);
}
} else {
$this->assertFalse(isset($option['extras']));
}
}
}