L-electron-Rare/moodle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MDL-86488 componentlibrary: Improved documentation for the action menu

Browse Source
This commit is contained in:
Jun Pataleta
2025-09-18 19:28:07 +08:00
parent 320eb96304
commit 2fdaddbab7
2 changed files with 98 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
public/admin/tool/componentlibrary/content/moodle/components/actionmenu.md
+49 -17
View File
@@ -39,7 +39,7 @@ The component output classes can render an action menu entirely in PHP. The step
The following code is a basic example of an action menu:
{{< php >}}
```php
/** @var core_renderer $output*/
$output = $PAGE->get_renderer('core');
@@ -54,11 +54,11 @@ $menu->add(new action_menu_link(
));
echo $output->render($menu);
{{< / php >}}
```
And this is the same example but passing the items in the creation:
{{< php >}}
```php
/** @var core_renderer $output*/
$output = $PAGE->get_renderer('core');
@@ -72,32 +72,64 @@ $menu = new action_menu([
]);
echo $output->render($menu);
{{< / php >}}
```
### Setup the menu trigger
By default, the action menu trigger is a cog icon. However, the class has methods to convert it to a kebab menu or even display any arbitrary content.
By default, the action menu trigger is a button that uses the `t/edit_menu` icon and is displayed with a caret. However, the class has methods to convert it to a kebab menu or even display any arbitrary content.
Example of a kebab menu:
#### Example of a kebab menu
{{< php >}}
```php
/** @var core_renderer $output*/
$output = $PAGE->get_renderer('core');
$menu = new action_menu();
$menu->set_kebab_trigger(get_string('edit'), $output);
$menu->set_additional_classes('fields-actions');
{{< / php >}}
```
Example of a custom trigger:
#### Customising the menu trigger
{{< php >}}
/** @var core_renderer $output*/
$output = $PAGE->get_renderer('core');
##### Trigger with a text label
```php
// This example displays an "Edit" label for the trigger.
$menu = new action_menu();
$menu->set_menu_trigger(get_string('edit'));
{{< / php >}}
```
##### Trigger with an icon
This example displays an icon for the trigger. When rendering the menu trigger button as an icon button, ensure that the icon is rendered as a decorative image. If you are using a `pix_icon`, pass an empty `$alt` parameter to make the icon decorative.
The accessible name of the icon button should be set within the button element itself. You can set an accessible name for the icon trigger button either by:
* Using the `::set_action_label()` method.
```php
$menu = new action_menu();
// Make sure the pix icon is rendered as a decorative image by passing an empty alt parameter.
$icon = $output->pix_icon('t/edit', '');
$menu->set_menu_trigger($icon);
$menu->set_action_label(get_string('edit'));
```
* Or alternatively, by adding a visually hidden text alongside the icon.
```php
$menu = new action_menu();
// Make sure the pix icon is rendered as a decorative image by passing an empty alt parameter.
$icon = $output->pix_icon('t/edit', '');
// Add a visually hidden text label for the trigger button.
$icon .= html_writer::span(get_string('edit'), 'visually-hidden');
$menu->set_menu_trigger($icon);
```
##### Removing the caret symbol
You may also remove the caret symbol by adding a `no-caret` class to the `triggerextraclasses` property.
```php
$menu->triggerextraclasses = 'no-caret';
```
### Add items
@@ -108,7 +140,7 @@ Secondary items: are displayed inside the action menu dropdown.
The item location must be configured before adding the element. The following example shows different ways to add primary and secondary menu items.
{{< php >}}
```php
// Primary items examples.
$menu->add(new action_menu_link(
new moodle_url($PAGE->url),
@@ -134,7 +166,7 @@ $menu->add(new action_menu_link_secondary(
new pix_icon('t/user', ''),
'Action link example',
));
{{< / php >}}
```
## Types of items
@@ -178,7 +210,7 @@ Construct params:
The following example creates a subpanel using a renderable choicelist instance:
{{< php >}}
```php
/** @var core_renderer $output*/
$output = $PAGE->get_renderer('core');
@@ -205,7 +237,7 @@ $menu->add(new core\output\local\action_menu\subpanel(
));
echo $output->render($menu);
{{< / php >}}
```
### HTML string
public/admin/tool/componentlibrary/examples/actionmenu.php
+49 -7
View File
@@ -77,7 +77,7 @@ echo '<p><strong>Important note:</strong> actions menus are not prepared
to be displayed inside iframes. You may need to scroll to see the
action menu options.</p>';
echo $output->heading("Action menu default example", 4);
echo $output->heading("Action menu default example", 3);
$menu = new action_menu();
@@ -87,11 +87,11 @@ $menu->add($subpanel);
$menu->add($basicactionlink);
echo '<div class="border m-3 p-3 d-flex flex-row">';
echo '<div class="flex-fill">Example of default an action menu</div><div>';
echo '<div class="flex-fill">An action menu rendered without customisation</div><div>';
echo $OUTPUT->render($menu);
echo '</div></div>';
echo $output->heading("Kebab menu example", 4);
echo $output->heading("Kebab menu example", 3);
$menu = new action_menu();
$menu->set_kebab_trigger(get_string('edit'), $output);
@@ -106,11 +106,11 @@ $menu->add(new core\output\local\action_menu\subpanel(
$menu->add($basicactionlink);
echo '<div class="border m-3 p-3 d-flex flex-row">';
echo '<div class="flex-fill">Example of kebab menu</div><div>';
echo '<div class="flex-fill">An action menu with a kebab menu trigger button</div><div>';
echo $OUTPUT->render($menu);
echo '</div></div>';
echo $output->heading("Custom trigger menu example", 4);
echo $output->heading("Custom trigger menu examples", 3);
$menu = new action_menu();
$menu->set_menu_trigger(get_string('edit'));
@@ -124,11 +124,53 @@ $menu->add(new core\output\local\action_menu\subpanel(
$menu->add($basicactionlink);
echo '<div class="border m-3 p-3 d-flex flex-row">';
echo '<div class="flex-fill">Example of kebab menu</div><div>';
echo '<div class="flex-fill">An action menu with a menu trigger button with a custom text label</div><div>';
echo $OUTPUT->render($menu);
echo '</div></div>';
echo $output->heading("Primary actions menu example", 4);
$links = [
$basicactionlink,
$basicactionlink,
];
$moreicon = $OUTPUT->pix_icon('i/moremenu', '');
$editicon = $OUTPUT->pix_icon('t/edit', '');
$menu = new action_menu($links);
$menu->set_menu_trigger($moreicon);
$menu->set_action_label(get_string('moremenu'));
$menu->triggerattributes = [
'title' => get_string('moremenu'),
];
echo '<div class="border m-3 p-3 d-flex flex-row">';
echo '<div class="flex-fill">An action menu with only an icon for its custom menu trigger button</div>';
echo html_writer::div($OUTPUT->render($menu));
echo '</div>';
echo '<div class="border m-3 p-3 d-flex flex-row">';
echo '<div class="flex-fill">An action menu with only an icon for its custom menu trigger button with the caret removed</div>';
$menu->triggerextraclasses = 'no-caret';
echo html_writer::div($OUTPUT->render($menu));
echo '</div>';
$menu = new action_menu($links);
$menu->set_menu_trigger($editicon . ' ' . get_string('edit'));
echo '<div class="border m-3 p-3 d-flex flex-row">';
echo '<div class="flex-fill">An action menu with an icon and visible text for its custom menu trigger button</div>';
echo html_writer::div($OUTPUT->render($menu));
echo '</div>';
$menu = new action_menu($links);
$menu->set_menu_trigger($editicon . ' ' . html_writer::span(get_string('edit'), 'visually-hidden'));
echo '<div class="border m-3 p-3 d-flex flex-row">';
echo '<div class="flex-fill">An action menu with an icon and visually hidden text for its custom menu trigger button</div>';
echo html_writer::div($OUTPUT->render($menu));
echo '</div>';
echo $output->heading("Primary actions menu example", 3);
$menu = new action_menu();
$menu->set_menu_trigger(get_string('edit'));