mirror of
https://github.com/moodle/moodle.git
synced 2025-08-07 18:06:51 +02:00
MDL-83869 tool_componentlibrary: collapsable section page
This commit is contained in:
ferran
parent
46318e53d0
commit
53886acba6
2 changed files with 193 additions and 0 deletions
|
|
@ -0,0 +1,158 @@
|
|||
---
|
||||
layout: docs
|
||||
title: "Collapsable sections"
|
||||
description: "A reusable collapsable section component"
|
||||
date: 2024-12-20T10:10:00+08:00
|
||||
draft: false
|
||||
tags:
|
||||
- MDL-83869
|
||||
- "5.0"
|
||||
---
|
||||
|
||||
## How it works
|
||||
|
||||
The collapsable section component in Moodle allows you to create sections of content that can be expanded or collapsed by the user. This is useful for organizing content in a way that doesn't overwhelm the user with too much information at once. The component is built using a combination of PHP, Mustache templates, and JavaScript.
|
||||
|
||||
## Source files
|
||||
|
||||
- `lib/templates/local/collapsable_section.mustache`: The Mustache template for rendering the collapsable section.
|
||||
- `lib/classes/output/local/collapsable_section.php`: The output class for the collapsable section component.
|
||||
- `lib/amd/src/local/collapsable_section/events.js`: JavaScript module for handling events related to the collapsable section.
|
||||
- `lib/amd/src/local/collapsable_section/controls.js`: JavaScript module for controlling the collapsable section.
|
||||
|
||||
## Usage
|
||||
|
||||
To use the collapsable section component, you need to create an instance of the `collapsable_section` class and render it using Moodle's output renderer. You can customize the title content, section content, CSS classes, and additional HTML attributes.
|
||||
|
||||
Example:
|
||||
|
||||
{{< php >}}
|
||||
use core\output\local\collapsable_section;
|
||||
|
||||
// Create an instance of the collapsable section.
|
||||
$section = new collapsable_section(
|
||||
titlecontent: 'Section Title',
|
||||
sectioncontent: 'This is the content of the section.',
|
||||
);
|
||||
|
||||
echo $OUTPUT->render($section);
|
||||
{{< / php >}}
|
||||
|
||||
{{< mustache template="core/local/collapsable_section" >}}
|
||||
{
|
||||
"titlecontent": "Section Title",
|
||||
"sectioncontent": "This is the content of the section."
|
||||
}
|
||||
{{< /mustache >}}
|
||||
|
||||
You can also add CSS classes, extra HTML attributes, and customize the expand and collapse labels of the collapsable section:
|
||||
|
||||
{{< php >}}
|
||||
$section = new collapsable_section(
|
||||
titlecontent: 'Section Title',
|
||||
sectioncontent: 'This is the content of the section.',
|
||||
open: true, // Optional parameter to set the section as open by default.
|
||||
classes: 'p-3 rounded bg-dark text-white', // Optional parameter to add custom CSS classes.
|
||||
extras: ['id' => 'MyCollapsableSection', 'data-foo' => 'bar'], // Optional HTML attributes.
|
||||
expandlabel: 'Show more', // Optional label for the expand button.
|
||||
collapselabel: 'Show less', // Optional label for the collapse button.
|
||||
);
|
||||
|
||||
echo $OUTPUT->render($section);
|
||||
{{< / php >}}
|
||||
|
||||
{{< mustache template="core/local/collapsable_section" >}}
|
||||
{
|
||||
"titlecontent": "Section Title",
|
||||
"sectioncontent": "This is the content of the section.",
|
||||
"open": true,
|
||||
"classes": "p-3 rounded bg-dark text-white",
|
||||
"elementid": "someuniqueid",
|
||||
"extras": [
|
||||
{
|
||||
"attribute": "id",
|
||||
"value": "MyCollapsableSection"
|
||||
},
|
||||
{
|
||||
"attribute": "data-foo",
|
||||
"value": "bar"
|
||||
}
|
||||
],
|
||||
"expandlabel": "Show more",
|
||||
"collapselabel": "Show less"
|
||||
}
|
||||
{{< /mustache >}}
|
||||
|
||||
## Include a collapsable section from a mustache template
|
||||
|
||||
Collapsable sections can also be included from a Mustache template using the `core/local/collapsable_section` template. This template allows you to define the title content and section content within the template.
|
||||
|
||||
{{< mustache template="tool_componentlibrary/examples/collapsablesections/includesection" >}}
|
||||
{
|
||||
}
|
||||
{{< /mustache >}}
|
||||
|
||||
## JavaScript
|
||||
|
||||
### Control a section
|
||||
|
||||
The collapsable sections component includes a JavaScript module for controlling the sections. This module provides methods to hide, show, and toggle the visibility of the sections.
|
||||
|
||||
To use the JavaScript controls, you need to import the `CollapsableSection` module and create an instance from a selector:
|
||||
|
||||
```javascript
|
||||
import CollapsableSection from 'core/local/collapsable_section/controls';
|
||||
|
||||
const section = CollapsableSection.instanceFromSelector('#MyCollapsableSection');
|
||||
|
||||
// Use hide, show, and toggle methods to control the section.
|
||||
section.hide();
|
||||
section.show();
|
||||
section.toggle();
|
||||
```
|
||||
|
||||
### Get the state of a section
|
||||
|
||||
You can also check the state of a section using the `isHidden` method:
|
||||
|
||||
```javascript
|
||||
import CollapsableSection from 'core/local/collapsable_section/controls';
|
||||
|
||||
const section = CollapsableSection.instanceFromSelector('#MyCollapsableSection');
|
||||
|
||||
if (section.isVisible()) {
|
||||
console.log('The section is hidden.');
|
||||
} else {
|
||||
console.log('The section is visible.');
|
||||
}
|
||||
```
|
||||
|
||||
### Events
|
||||
|
||||
The collapsable sections component also includes a JavaScript module for handling events. This module wraps the standard Bootstrap collapsable events and provides custom event types for collapsable sections.
|
||||
|
||||
The component triggers two main events:
|
||||
|
||||
- `core_collapsable_section_shown`: when the collapsed content is shown.
|
||||
- `core_collapsable_section_hidden`: when the collapsed content is hidden.
|
||||
|
||||
For convenience, the `core/local/collapsable_section/events` also list the original Bootstrap events. They should not be needed in most cases, but they are available if you need them:
|
||||
|
||||
- `show.bs.collapse`: when the collapse is starting to show.
|
||||
- `shown.bs.collapse`: when the collapse has been shown.
|
||||
- `hide.bs.collapse`: when the collapse is starting to hide.
|
||||
- `hidden.bs.collapse`: when the collapse has been hidden.
|
||||
|
||||
To listen for events related to the collapsable sections, you need to import the `eventTypes` from the `events` module and add event listeners:
|
||||
|
||||
```javascript
|
||||
import {eventTypes as collapsableSectionEventTypes} from 'core/local/collapsable_section/events';
|
||||
|
||||
document.addEventListener(collapsableSectionEventTypes.shown, event => {
|
||||
console.log(event.target); // The HTMLElement relating to the section that was shown.
|
||||
});
|
||||
|
||||
document.addEventListener(collapsableSectionEventTypes.hidden, event => {
|
||||
console.log(event.target); // The HTMLElement relating to the section that was hidden.
|
||||
});
|
||||
```
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
{{!
|
||||
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/>.
|
||||
}}
|
||||
{{!
|
||||
@template tool_componentlibrary/examples/collapsablesections/includesection
|
||||
|
||||
TODO describe template includesection
|
||||
|
||||
Example context (json):
|
||||
{
|
||||
}
|
||||
}}
|
||||
{{<core/local/collapsable_section}}
|
||||
{{$titlecontent}} Section title {{/titlecontent}}
|
||||
{{! Optional id for the section. }}
|
||||
{{$elementid}}optionaId{{/elementid}}
|
||||
{{! Optional classes for the section. }}
|
||||
{{$extraclasses}}border border-1 rounded-3 p-3{{/extraclasses}}
|
||||
{{$sectioncontent}}
|
||||
This is the section content.
|
||||
{{/sectioncontent}}
|
||||
{{/core/local/collapsable_section}}
|
||||
Loading…
Add table
Add a link
Reference in a new issue