From b0ed857b084121493fe85271273a20cc58ca4889 Mon Sep 17 00:00:00 2001
From: Andrew Nicols <andrew@nicols.co.uk>
Date: Fri, 28 Jan 2022 11:41:37 +0800
Subject: [PATCH 1/1] MDL-73679 examples: Examples of format_topics extending
 templates

The following templates are considered top-level:
* course/format/topics/templates/local/content.mustache
* course/format/topics/templates/local/content/cm/title.mustache
* course/format/topics/templates/local/content/section.mustache
* course/format/topics/templates/local/content/section/cmitem.mustache

When overriding these templates, they must also be specified in their
respective class definitions:
* course/format/topics/classes/output/courseformat/content.php
* course/format/topics/classes/output/courseformat/content/cm/title.php
* course/format/topics/classes/output/courseformat/content/section.php
* course/format/topics/classes/output/courseformat/content/section/cmitem.php
---
 .../classes/output/courseformat/content.php   |   3 +
 .../output/courseformat/content/cm/title.php  |  10 ++
 .../output/courseformat/content/section.php   |   4 +
 .../courseformat/content/section/cmitem.php   |  10 ++
 .../topics/templates/local/content.mustache   |  95 ++++++++++++
 .../templates/local/content/cm/title.mustache |  27 ++++
 .../templates/local/content/section.mustache  | 140 ++++++++++++++++++
 .../local/content/section/cmitem.mustache     |  84 +++++++++++
 .../local/content/section/summary.mustache    |  26 ++++
 9 files changed, 399 insertions(+)
 create mode 100644 course/format/topics/classes/output/courseformat/content/cm/title.php
 create mode 100644 course/format/topics/classes/output/courseformat/content/section/cmitem.php
 create mode 100644 course/format/topics/templates/local/content.mustache
 create mode 100644 course/format/topics/templates/local/content/cm/title.mustache
 create mode 100644 course/format/topics/templates/local/content/section.mustache
 create mode 100644 course/format/topics/templates/local/content/section/cmitem.mustache
 create mode 100644 course/format/topics/templates/local/content/section/summary.mustache

diff --git a/course/format/topics/classes/output/courseformat/content.php b/course/format/topics/classes/output/courseformat/content.php
index 8d3e630810..fdff607639 100644
--- a/course/format/topics/classes/output/courseformat/content.php
+++ b/course/format/topics/classes/output/courseformat/content.php
@@ -42,4 +42,7 @@ class content extends content_base {
      */
     protected $hasaddsection = false;
 
+    public function get_template_name(\renderer_base $renderer): string {
+        return 'format_topics/local/content';
+    }
 }
diff --git a/course/format/topics/classes/output/courseformat/content/cm/title.php b/course/format/topics/classes/output/courseformat/content/cm/title.php
new file mode 100644
index 0000000000..04d512054f
--- /dev/null
+++ b/course/format/topics/classes/output/courseformat/content/cm/title.php
@@ -0,0 +1,10 @@
+<?php
+
+namespace format_topics\output\courseformat\content\cm;
+
+class title extends \core_courseformat\output\local\content\cm\title {
+
+    public function get_template_name(\renderer_base $renderer): string {
+        return 'format_topics/local/content/cm/title';
+    }
+}
diff --git a/course/format/topics/classes/output/courseformat/content/section.php b/course/format/topics/classes/output/courseformat/content/section.php
index c4a8ac1a23..f6edec85d0 100644
--- a/course/format/topics/classes/output/courseformat/content/section.php
+++ b/course/format/topics/classes/output/courseformat/content/section.php
@@ -37,6 +37,10 @@ use stdClass;
  */
 class section extends section_base {
 
+    public function get_template_name(\renderer_base $renderer): string {
+        return 'format_topics/local/content/section';
+    }
+
     /** @var course_format the course format */
     protected $format;
 
diff --git a/course/format/topics/classes/output/courseformat/content/section/cmitem.php b/course/format/topics/classes/output/courseformat/content/section/cmitem.php
new file mode 100644
index 0000000000..961f792c76
--- /dev/null
+++ b/course/format/topics/classes/output/courseformat/content/section/cmitem.php
@@ -0,0 +1,10 @@
+<?php
+
+namespace format_topics\output\courseformat\content\section;
+
+class cmitem extends \core_courseformat\output\local\content\section\cmitem {
+
+    public function get_template_name(\renderer_base $renderer): string {
+        return 'format_topics/local/content/section/cmitem';
+    }
+}
diff --git a/course/format/topics/templates/local/content.mustache b/course/format/topics/templates/local/content.mustache
new file mode 100644
index 0000000000..e735a92780
--- /dev/null
+++ b/course/format/topics/templates/local/content.mustache
@@ -0,0 +1,95 @@
+{{!
+
+This is an example template to override individual child templates in the content of a course.
+
+All overridable templates are listed in this file.
+
+If you are overriding this template, or any of the children listed here, then you must also create and configure the
+format_[yourplugin]\output\local\content class.
+
+To override the formatting of a section, you will need to:
+* override the section template, following the documentation in local/content/section.mustache;
+* provide a format_[yourplugin]\output\local\content\section class with detail of the overridden section template;
+* override this template to include the section; and
+* provide a format_[yourplugin]\output\local\content class with detail of the overridden content template.
+
+To override the formatting of a course module (activity), you will need to:
+* override the cmitem template, following the documentation in local/content/section/cmitem.mustache;
+* provide a format_[yourplugin]\output\local\content\section\cmitem class with detail of the overridden cmitem template;
+* override the section template, following the documentation in local/content/section.mustache;
+* provide a format_[yourplugin]\output\local\content\section class with detail of the overridden section template;
+* override this template to include the section; and
+* provide a format_[yourplugin]\output\local\content class with detail of the overridden content template.
+
+}}
+
+{{!
+  Include the core content template.
+  This is the top template for a course.
+}}
+{{< core_courseformat/local/content }}
+
+    {{!
+        The representation of a single section.
+        Source: core_courseformat/local/content/section
+
+        Note: To override the section template you must also override the section class.
+        See notes in the content/section example.
+    }}
+    {{!$ core_courseformat/local/content/section }}
+        {{! In this example, we override it with a template in the format_topics component }}
+        {{!> format_topics/local/content/section }}
+    {{!/ core_courseformat/local/content/section }}
+
+
+    {{!
+        The representation of the section navigation.
+        Source: core_courseformat/local/content/sectionnavigation
+    }}
+    {{!$ core_courseformat/local/content/sectionnavigation }}
+        {{!> core_courseformat/local/content/sectionnavigation }}
+    {{!/ core_courseformat/local/content/sectionnavigation }}
+
+
+    {{!
+        The representation of the section selector.
+        Source: core_courseformat/local/content/sectionselector
+    }}
+    {{!$ core_courseformat/local/content/sectionselector }}
+        {{!> core_courseformat/local/content/sectionselector }}
+    {{!/ core_courseformat/local/content/sectionselector }}
+
+
+    {{!
+        The representation of the "Add section" button.
+        Source: core_courseformat/local/content/addsection
+
+        Note: This template is also used in the content/section template and must be specified there too.
+    }}
+    {{!$ core_courseformat/local/content/addsection }}
+        {{!> core_courseformat/local/content/addsection }}
+    {{!/ core_courseformat/local/content/addsection }}
+
+{{!
+
+EXAMPLE: The following is an example of overriding part of a cmitem.
+
+Because the cmitem may be rendered individually, as part of a single section, or a part of an entire course, the
+following three templates _must_ be overridden:
+* core_courseformat\local\content
+* core_courseformat\local\content\section
+* core_courseformat\local\content\section\cmitem
+
+
+The following classes must also be provided and specify the respective template names:
+* format_topics\output\local\content
+* format_topics\output\local\content\section
+* format_topics\output\local\content\section\cmitem
+
+}}
+
+    {{$ core_courseformat/local/content/section }}
+        {{> format_topics/local/content/section }}
+    {{/ core_courseformat/local/content/section }}
+
+{{/ core_courseformat/local/content }}
diff --git a/course/format/topics/templates/local/content/cm/title.mustache b/course/format/topics/templates/local/content/cm/title.mustache
new file mode 100644
index 0000000000..0909ef1b0f
--- /dev/null
+++ b/course/format/topics/templates/local/content/cm/title.mustache
@@ -0,0 +1,27 @@
+{{!
+
+This is an example template to override individual child templates in the content of a course.
+
+All overridable templates are listed in this file.
+
+If you are overriding this template, or any of the children listed here, then you must also create and configure the
+format_[yourplugin]\output\local\content\cm\title class.
+
+}}
+
+{{!
+    Note: This template does not include any blocks as standard.
+    You should not use the block inclusion tags.
+}}
+{{!> core_courseformat/local/content/cm/title }}
+
+
+{{!
+
+EXAMPLE: Wrapping the entire content in a new div and adding additional siblings.
+
+}}
+<div class="my_first_example">
+    {{> core_courseformat/local/content/cm/title }}
+    <div class="d-flex flex-column my_second_example">Example sibling</div>
+</div>
diff --git a/course/format/topics/templates/local/content/section.mustache b/course/format/topics/templates/local/content/section.mustache
new file mode 100644
index 0000000000..efd101695c
--- /dev/null
+++ b/course/format/topics/templates/local/content/section.mustache
@@ -0,0 +1,140 @@
+{{!
+
+This is an example template to override child templates of an individual section or its children.
+
+All overridable templates are listed in this file.
+
+If you are overriding this template, or any of the children listed here, then you must also:
+* create and configure the format_[yourplugin]\output\local\content\section class;
+* override the content template; and
+* create and configure the format_[yourplugin]\output\local\content class.
+
+To override the formatting of a course module (activity), you will need to:
+* override the cmitem template, following the documentation in local/content/section/cmitem.mustache;
+* provide a format_[yourplugin]\output\local\content\section\cmitem class with detail of the overridden cmitem template;
+* override the section template, following the documentation in local/content/section.mustache;
+* provide a format_[yourplugin]\output\local\content\section class with detail of the overridden section template;
+* override this template to include the section; and
+* provide a format_[yourplugin]\output\local\content class with detail of the overridden content template.
+
+}}
+
+{{!
+  Include the core content/section template.
+  This is the template used to render a single section.
+}}
+{{< core_courseformat/local/content/section }}
+
+
+    {{!
+        The representation of a section header.
+        Source: core_courseformat/local/content/section/header
+
+        In this example the standard template is used, but is wrapped in an additional div.
+    }}
+    {{!$ core_courseformat/local/content/section/header }}
+        {{!> core_courseformat/local/content/section/header }}
+    {{!/ core_courseformat/local/content/section/header }}
+
+
+    {{!
+        The representation of section badges.
+        Source: core_courseformat/local/content/section/badges
+    }}
+    {{!$ core_courseformat/local/content/section/badges }}
+        {{!> core_courseformat/local/content/section/badges }}
+    {{!/ core_courseformat/local/content/section/badges }}
+
+
+    {{!
+        The representation of the section controls.
+        Source: core_courseformat/local/content/section/controlmenu
+    }}
+    {{!$ core_courseformat/local/content/section/controlmenu }}
+        {{!> core_courseformat/local/content/section/controlmenu }}
+    {{!/ core_courseformat/local/content/section/controlmenu }}
+
+
+    {{!
+        The representation of the section summary.
+        Source: core_courseformat/local/content/section/summary
+    }}
+    {{!$ core_courseformat/local/content/section/summary }}
+        {{!> core_courseformat/local/content/section/summary }}
+    {{!/ core_courseformat/local/content/section/summary }}
+
+
+    {{!
+        The representation of the section availability information.
+        Source: core_courseformat/local/content/section/availability
+    }}
+    {{!$ core_courseformat/local/content/section/availability }}
+        {{!> core_courseformat/local/content/section/availability }}
+    {{!/ core_courseformat/local/content/section/availability }}
+
+
+    {{!
+        The representation of the section cmsummary.
+        Source: core_courseformat/local/content/section/cmsummary
+    }}
+    {{!$ core_courseformat/local/content/section/cmsummary }}
+        {{!> core_courseformat/local/content/section/cmsummary }}
+    {{!/ core_courseformat/local/content/section/cmsummary }}
+
+
+    {{!
+        The representation of the course module list in a section.
+        Source: core_courseformat/local/content/section/cmlist
+    }}
+    {{!$ core_courseformat/local/content/section/cmlist }}
+        {{!> core_courseformat/local/content/section/cmlist }}
+    {{!/ core_courseformat/local/content/section/cmlist }}
+
+
+        {{!
+            The representation of a single course module (activity).
+            Source: core_courseformat/local/content/section/cmitem
+
+            Note: This is a child template of the CM List.
+            Note: See notes at the top of this file for instructions on how to override the cmitem template.
+        }}
+        {{!$ core_courseformat/local/content/section/cmitem }}
+            {{!> core_courseformat/local/content/section/cmitem }}
+        {{!/ core_courseformat/local/content/section/cmitem }}
+
+
+    {{!
+      The representation of the "Add section" button.
+      Source: core_courseformat/local/content/addsection
+
+      Note: This template is also used in the content template and must be specified there too.
+    }}
+    {{!$ core_courseformat/local/content/addsection }}
+        {{!> core_courseformat/local/content/addsection }}
+    {{!/ core_courseformat/local/content/addsection }}
+
+
+{{!
+
+EXAMPLE: The following is an example of overriding part of a cmitem.
+The section summary is also updated with a custom template.
+
+We must also override the format_topics\output\local\content\section class to specify the template name of this
+template.
+
+}}
+
+    {{$ core_courseformat/local/content/section/cmitem }}
+        {{> format_topics/local/content/section/cmitem }}
+    {{/ core_courseformat/local/content/section/cmitem }}
+
+    {{!
+        The representation of the section summary.
+        Source: core_courseformat/local/content/section/summary
+    }}
+    {{$ core_courseformat/local/content/section/summary }}
+        {{> format_topics/local/content/section/summary }}
+    {{/ core_courseformat/local/content/section/summary }}
+
+
+{{/ core_courseformat/local/content/section }}
diff --git a/course/format/topics/templates/local/content/section/cmitem.mustache b/course/format/topics/templates/local/content/section/cmitem.mustache
new file mode 100644
index 0000000000..177eaf3146
--- /dev/null
+++ b/course/format/topics/templates/local/content/section/cmitem.mustache
@@ -0,0 +1,84 @@
+{{!
+
+This is an example template to override individual child templates in a course module (activity).
+
+All overridable templates are listed in this file.
+
+If you are overriding this template, or any of the children listed here, then you must also:
+* create and configure the format_[yourplugin]\output\local\content\section\cmitem class;
+* override the content/section template; and
+* create and configure the format_[yourplugin]\output\local\content\section class;
+* override the content template; and
+* create and configure the format_[yourplugin]\output\local\content class.
+
+}}
+
+{{!
+  Include the core content/section/cmitem template.
+  This is the template used to render a single activity.
+}}
+{{< core_courseformat/local/content/section/cmitem }}
+
+
+    {{!
+        The representation of the course module.
+        Source: core_courseformat/local/content/cm/badges
+
+        Note: This template has lots of children.
+        If you wish to override this template, or any of it's children, then they must be specified in this file.
+    }}
+    {{!$ core_courseformat/local/content/cm}}
+        {{!> core_courseformat/local/content/cm }}
+    {{!/ core_courseformat/local/content/cm}}
+
+    {{!
+        The representation of the course module 'badges'.
+        Source: core_courseformat/local/content/cm/badges
+    }}
+    {{!$ core_courseformat/local/content/cm/badges }}
+        {{!> core_courseformat/local/content/cm/badges }}
+    {{!/ core_courseformat/local/content/cm/badges }}
+
+
+    {{!
+        The representation of the course module information.
+        Source: core_courseformat/local/content/cm/activity_info
+    }}
+    {{!$ core_courseformat/local/content/cm/activity_info }}
+        {{!> core_courseformat/local/content/cm/activity_info }}
+    {{!/ core_courseformat/local/content/cm/activity_info }}
+
+
+    {{!
+        The representation of the course module control menu.
+        Source: core_courseformat/local/content/cm/controlmenu
+    }}
+    {{!$ core_courseformat/local/content/cm/controlmenu }}
+        {{!> core_courseformat/local/content/cm/controlmenu }}
+    {{!/ core_courseformat/local/content/cm/controlmenu }}
+
+
+    {{!
+        The representation of the course module availability information.
+        Source: core_courseformat/local/content/cm/availability
+    }}
+    {{!$ core_courseformat/local/content/cm/availability }}
+        {{!> core_courseformat/local/content/cm/availability }}
+    {{!/ core_courseformat/local/content/cm/availability }}
+
+{{!
+
+EXAMPLE: The following is an example of wrapping one of the standard templates in a new div.
+
+We also override the format_topics\output\local\content\section\cmitem class to specify the template name of this
+template.
+
+}}
+
+    {{$ core_courseformat/local/content/cm}}
+        <div class="text-monospace">
+            {{> core_courseformat/local/content/cm }}
+        </div>
+    {{/ core_courseformat/local/content/cm}}
+
+{{/ core_courseformat/local/content/section/cmitem }}
diff --git a/course/format/topics/templates/local/content/section/summary.mustache b/course/format/topics/templates/local/content/section/summary.mustache
new file mode 100644
index 0000000000..ba029e8885
--- /dev/null
+++ b/course/format/topics/templates/local/content/section/summary.mustache
@@ -0,0 +1,26 @@
+{{!
+
+EXAMPLE
+
+This is an example of how the standard section summary template can be overridden.
+
+Care should be taken when overriding entire templates in this manner and it is recommended that you carefully check git
+logs for any template that is overridden between versions.
+
+Note: there is no need to override the \core_courseformat\output\local\content\section\summary class for this change as
+the section summary is only ever rendered as part of the whole section.
+
+}}
+{{#summarytext}}
+    {{!
+        This example adds some extra classes to the standard summary div.
+    }}
+    <div class="course-description-item summarytext mycustomtemplate example">
+        {{!
+            And also to the inner description.
+        }}
+        <div class="description-inner text-monospace">
+            {{{summarytext}}}
+        </div>
+    </div>
+{{/summarytext}}
-- 
2.34.1