MDL-73470 tool_componentlibrary: Documentation for toggle input

2022-01-25 18:04:58 +01:00
parent 795087462f
commit b43c28567a
2 changed files with 122 additions and 0 deletions
@@ -0,0 +1,81 @@
+---
+layout: docs
+title: "Toggle input"
+date: 2022-01-17T00:00:00+01:00
+draft: false
+weight: 60
+tags:
+- MDL-73470
+- 4.0
+---
+
+## How to use
+
+Toggle input is rendered using a template found in lib/templates/toggle.mustache. 
+
+The parameters for the template context are:
+* id: Unique id for the toggle input.
+* extraclasses: Any extra classes added to the toggle input outer container.
+* checked: If the initial status is checked.
+* disabled: If toggle input is disabled.
+* dataattributes: Array of name/value elements added as data-attributes.
+* label: Label text.
+* labelclasses: Any extra classes added to the label container.
+
+## Examples
+
+<div class="small">
+Checked toggle and with "sr-only" label.
+</div>
+{{< mustache template="core/toggle" >}}
+    {
+        "id": "example-toggle-1",
+        "checked": true,
+        "dataattributes": [{
+            "name": "action",
+            "value": "toggle-status"
+        }],
+        "label": "Enable/disable status",
+        "labelclasses": "sr-only"
+    }
+{{< /mustache >}}
+
+<div class="mt-3 small">
+Disabled toggle with extra classes.
+</div>
+{{< mustache template="core/toggle" >}}
+    {
+        "id": "example-toggle-2",
+        "disabled": true,
+        "extraclasses": "mt-2 ml-2",
+        "dataattributes": [{
+            "name": "action",
+            "value": "toggle-status"
+        }],
+        "label": "Enable/disable status"
+    }
+{{< /mustache >}}
+
+## Use toggle as a template block
+
+It is also possible to include *core/toggle* in any other template using [blocks](https://docs.moodle.org/dev/Templates#Blocks), instead of rendering it with a context.
+The parameters that you can define are:
+* id: Unique id for the toggle input.
+* extraclasses: Any extra classes added to the toggle input outer container.
+* attributes: Any attributes added to the toggle input.
+    * data-attributes
+    * checked
+    * disabled
+* labelmarkup: Label element code block.
+  * Should include *class="custom-control-label"*.
+* label: Label text.
+* labelclasses: Any extra classes added to the label container.
+
+<div class="small">
+Example of template using toggle as a block.
+</div>
+{{< mustache template="tool_componentlibrary/examples/toggle/example" >}}
+    {
+    }
+{{< /mustache >}}
+
@@ -0,0 +1,41 @@
+{{!
+    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/toggle/example
+
+    Template for toggle element used as a block example
+
+    Example context (json):
+    {
+    }
+}}
+<div id="toggle-example">
+    <h1>Toggle block</h1>
+    <span>This is a simple example using toggle template as a block.</span>
+    {{< core/toggle }}
+        {{$id}}example-toggle-3{{/id}}
+        {{$extraclasses}}mt-3{{/extraclasses}}
+        {{$attributes}}
+            data-action="toggle-status"
+            data-action-id="3"
+            checked
+            disabled
+        {{/attributes}}
+        {{$label}}Enable/disable status{{/label}}
+        {{$labelclasses}}sr-only{{/labelclasses}}
+    {{/ core/toggle }}
+</div>