diff --git a/admin/tool/componentlibrary/classes/exampleform.php b/admin/tool/componentlibrary/classes/local/examples/formelements/example.php similarity index 99% rename from admin/tool/componentlibrary/classes/exampleform.php rename to admin/tool/componentlibrary/classes/local/examples/formelements/example.php index d16b1f9df76..a7616222156 100644 --- a/admin/tool/componentlibrary/classes/exampleform.php +++ b/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 * @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. */ diff --git a/admin/tool/componentlibrary/content/library/example-files.md b/admin/tool/componentlibrary/content/library/example-files.md new file mode 100644 index 00000000000..9b62ca16797 --- /dev/null +++ b/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`: + +``` + +``` + +## 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 +``` diff --git a/admin/tool/componentlibrary/content/moodle/components/dynamictabs.md b/admin/tool/componentlibrary/content/moodle/components/dynamictabs.md index 10fddd4f4e6..5c334bc5177 100644 --- a/admin/tool/componentlibrary/content/moodle/components/dynamictabs.md +++ b/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 - + diff --git a/admin/tool/componentlibrary/content/moodle/components/form-elements.md b/admin/tool/componentlibrary/content/moodle/components/form-elements.md index 6886bbf2894..fd87e851c13 100644 --- a/admin/tool/componentlibrary/content/moodle/components/form-elements.md +++ b/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. - \ No newline at end of file + diff --git a/admin/tool/componentlibrary/dynamictabs.php b/admin/tool/componentlibrary/examples/dynamictabs.php similarity index 87% rename from admin/tool/componentlibrary/dynamictabs.php rename to admin/tool/componentlibrary/examples/dynamictabs.php index 7f4a37fc562..c7890489e73 100644 --- a/admin/tool/componentlibrary/dynamictabs.php +++ b/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(); diff --git a/admin/tool/componentlibrary/formfields.php b/admin/tool/componentlibrary/examples/formfields.php similarity index 74% rename from admin/tool/componentlibrary/formfields.php rename to admin/tool/componentlibrary/examples/formfields.php index 7470ba73cb7..426380a8118 100644 --- a/admin/tool/componentlibrary/formfields.php +++ b/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(); diff --git a/admin/tool/componentlibrary/templates/moodleformtoggles.mustache b/admin/tool/componentlibrary/templates/examples/formelements/toggles.mustache similarity index 95% rename from admin/tool/componentlibrary/templates/moodleformtoggles.mustache rename to admin/tool/componentlibrary/templates/examples/formelements/toggles.mustache index a3c8e2ec207..ffa0b9bf118 100644 --- a/admin/tool/componentlibrary/templates/moodleformtoggles.mustache +++ b/admin/tool/componentlibrary/templates/examples/formelements/toggles.mustache @@ -15,7 +15,7 @@ along with Moodle. If not, see . }} {{! - @template tool_componentlibrary/clipboardbutton + @template tool_componentlibrary/examples/formelements/toggles Example context (json): {