Merge branch 'MDL-73635-master' of https://github.com/junpataleta/moodle

admin/tool/componentlibrary/classes/local/examples/formelements/example.php

@@ -22,7 +22,7 @@
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
-namespace tool_componentlibrary;
+namespace tool_componentlibrary\local\examples\formelements;
 
 /**
  * Example form to showcase the rendering of form fields.
@@ -30,7 +30,7 @@ namespace tool_componentlibrary;
  * @copyright  2021 Bas Brands <bas@moodle.com>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
-class exampleform extends \moodleform {
+class example extends \moodleform {
     /**
      * Elements of the test form.
      */

admin/tool/componentlibrary/content/library/example-files.md

@@ -0,0 +1,75 @@
+---
+layout: docs
+title: "Example files"
+date: 2020-01-21T13:00:00+08:00
+draft: false
+---
+
+There may be times that we need to provide example implementations of the component being documented in order to further demonstrate how to use a component.
+
+We need to put these files in `examples` folders. It helps organise things and makes the maintenance of the component library code easier by allowing us to distinguish examples from the actual component library code. 
+
+
+## Example pages
+
+Example pages can be placed under the `componentlibrary/examples` folder. 
+
+See the `formfields.php` example page as an example:
+
+```
+componentlibrary
+└── examples
+     └── formfields.php
+```
+
+This can be embedded in the component's documentation page via iframe. For example in `componentlibrary/content/moodle/form-elements.md`:
+
+```
+<iframe src="../../../../examples/formfields.php" style="overflow:hidden;height:4000px;width:100%;border:0" title="Moodle form fields"></iframe>
+```
+
+## Example classes
+
+Example classes can be placed under the `componentlibrary/classes/local/examples/[componentname]` folder. 
+
+In our form fields example, we have the `\tool_componentlibrary\local\examples\formelements\example` class under `componentlibrary/classes/local/examples/formelements`.
+
+## Example templates
+
+Example templates can be placed under the `componentlibrary/templates/examples/[componentname]` folder.
+
+In our form fields example, we have the `tool_componentlibrary/examples/formelements/toggles` template under `componentlibrary/templates/examples/formelements`.
+
+## Summary
+
+Please put example files in their designated `examples` folders.
+```
+componentlibrary
+└── classes
+    └── local
+        └── examples
+            └── [component folder]
+                └── [example classes]
+└── examples
+    └── [example page]
+└── templates
+    └── examples
+        └── [component folder]
+            └── [example templates]
+```
+
+For the form elements documentation, its example files are in the following `examples` folders.
+```
+componentlibrary
+└── classes
+    └── local
+        └── examples
+            └── formelements
+                └── example.php
+└── examples
+    └── formfields.php
+└── templates
+    └── examples
+        └── formelements
+            └── toggles.mustache
+```

admin/tool/componentlibrary/content/moodle/components/dynamictabs.md

@@ -97,4 +97,4 @@ using `get_data` method (for example to check permissions in `is_available`).
 
 ## Example
 
-<iframe src="../../../../dynamictabs.php" style="overflow:hidden;height:400px;width:100%;border:0" title="Moodle dynamictabs"></iframe>
+<iframe src="../../../../examples/dynamictabs.php" style="overflow:hidden;height:400px;width:100%;border:0" title="Moodle dynamic tabs"></iframe>

admin/tool/componentlibrary/content/moodle/components/form-elements.md

@@ -23,7 +23,7 @@ Form elements are styled using the .form-control class, see the [Bootstrap](/boo
 
 ## Example form elements
 
-The example form below is showing an ifram with an actual Moodle form. Use the toggle options to display the different states for the form.
+The example form below is showing an iframe with an actual Moodle form. Use the toggle options to display the different states for the form.
 
 
-<iframe src="../../../../formfields.php" style="overflow:hidden;height:4000px;width:100%;border:0" title="Moodle formfields"></iframe>
+<iframe src="../../../../examples/formfields.php" style="overflow:hidden;height:4000px;width:100%;border:0" title="Moodle form fields"></iframe>

admin/tool/componentlibrary/examples/dynamictabs.php

@@ -26,7 +26,7 @@
 
 declare(strict_types=1);
 
-require_once('../../../config.php');
+require_once(__DIR__ . '/../../../../config.php');
 
 use core\output\dynamic_tabs;
 
@@ -34,12 +34,12 @@ require_login();
 require_capability('moodle/site:configview', context_system::instance());
 
 global $PAGE, $OUTPUT;
-$PAGE->set_url(new moodle_url('/local/componentlibrary/dynamictabs/dynamictabs.php'));
+$PAGE->set_url(new moodle_url('/admin/tool/componentlibrary/examples/dynamictabs.php'));
 $PAGE->set_context(context_system::instance());
 $PAGE->set_pagelayout('embedded');
 
-$PAGE->set_heading('Moodle dynamic fields');
-$PAGE->set_title('Moodle dynamic fields');
+$PAGE->set_heading('Moodle dynamic tabs');
+$PAGE->set_title('Moodle dynamic tabs');
 
 echo $OUTPUT->header();
 

admin/tool/componentlibrary/examples/formfields.php

@@ -24,7 +24,7 @@
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
-require_once('../../../config.php');
+require_once(__DIR__ . '/../../../../config.php');
 require_once($CFG->dirroot.'/lib/formslib.php');
 
 require_login();
@@ -34,14 +34,15 @@ $repeatcount = optional_param('test_repeat', 1, PARAM_INT);
 
 $PAGE->set_pagelayout('embedded');
 
-$url = new moodle_url('/admin/tool/componentlibrary/formfields.php');
+$url = new moodle_url('/admin/tool/componentlibrary/examples/formfields.php');
 
 $toggles  = (object)[];
 $toggles->defaulturl = $url;
-$toggles->helpurl = new moodle_url('/admin/tool/componentlibrary/formfields.php', ['help' => 1]);
-$toggles->requiredurl = new moodle_url('/admin/tool/componentlibrary/formfields.php', ['required' => 1]);
-$toggles->bothurl = new moodle_url('/admin/tool/componentlibrary/formfields.php', ['help' => 1, 'required' => 1]);
-$toggles->mixedurl = new moodle_url('/admin/tool/componentlibrary/formfields.php', ['help' => 1, 'required' => 1, 'mixed' => 1]);
+$toggles->helpurl = new moodle_url('/admin/tool/componentlibrary/examples/formfields.php', ['help' => 1]);
+$toggles->requiredurl = new moodle_url('/admin/tool/componentlibrary/examples/formfields.php', ['required' => 1]);
+$toggles->bothurl = new moodle_url('/admin/tool/componentlibrary/examples/formfields.php', ['help' => 1, 'required' => 1]);
+$toggles->mixedurl = new moodle_url('/admin/tool/componentlibrary/examples/formfields.php',
+    ['help' => 1, 'required' => 1, 'mixed' => 1]);
 
 $PAGE->set_url($url);
 $PAGE->set_context(context_system::instance());
@@ -49,10 +50,10 @@ $PAGE->set_context(context_system::instance());
 $PAGE->set_heading('Moodle form fields');
 $PAGE->set_title('Moodle form fields');
 
-$form = new \tool_componentlibrary\exampleform($url, ['repeatcount' => $repeatcount]);
+$form = new \tool_componentlibrary\local\examples\formelements\example($url, ['repeatcount' => $repeatcount]);
 
 echo $OUTPUT->header();
 
-echo $OUTPUT->render_from_template('tool_componentlibrary/moodleformtoggles', $toggles);
+echo $OUTPUT->render_from_template('tool_componentlibrary/examples/formelements/toggles', $toggles);
 $form->display();
 echo $OUTPUT->footer();

admin/tool/componentlibrary/templates/examples/formelements/toggles.mustache

@@ -15,7 +15,7 @@
     along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 }}
 {{!
-    @template tool_componentlibrary/clipboardbutton
+    @template tool_componentlibrary/examples/formelements/toggles
 
     Example context (json):
     {