DOC Document changes to template layer

en/00_Getting_Started/04_Directory_Structure.md

@@ -32,7 +32,7 @@ We use `app/` as the default folder.
 | `app/_config`    | YAML configuration specific to your application                    |
 | `app/src`        | PHP code specific to your application (subdirectories are optional)     |
 | `app/tests`      | PHP unit/functional/end-to-end tests                                                      |
-| `app/templates`  | HTML [templates](/developer_guides/templates) with `*.ss-extension` for the `$default` theme   |
+| `app/templates`  | [templates](/developer_guides/templates) for the `$default` theme   |
 | `app/client/src` | Conventional directory for source resources (images/CSS/JavaScript) for your CMS customisations |
 | `app/client/dist` | Conventional directory for transpiled resources (images/CSS/JavaScript) for your CMS customisations |
 | `app/client/lang` | Conventional directory for [JavaScript translation tables](/developer_guides/i18n/#translation-tables-in-javascript) |

en/02_Developer_Guides/01_Templates/01_Syntax.md

@@ -6,8 +6,7 @@ icon: code
 
 # Template syntax
 
-A template can contain any markup language (e.g HTML, CSV, JSON, etc) and before being rendered to the user, they're
-processed through [SSViewer](api:SilverStripe\View\SSViewer). This process replaces placeholders such as `$Var` with real content from your
+A template can contain any markup language (e.g HTML, CSV, JSON, etc). The rendering process replaces placeholders such as `$Var` with real content from your
 model (see [Model and Databases](../model)) and allows you to use logic like `<% if $Var %>` in your templates.
 
 An example of a Silverstripe CMS template is below:
@@ -76,9 +75,7 @@ $Foo.Bar
 These variables will call a method / field on the object and insert the returned value as a string into the template.
 
 > [!WARNING]
-> If you wish to pass arguments to getter functions, you must use the full method name. e.g. `$Thing` will try to access `Thing` as a property, which will ultimately result in `getThing()` being called with no arguments To pass arguments you must use `$getThing('param')`.
->
-> Also, arguments must be literals, and cannot be other template variables (`$getThing($variable)` will pass the literal string `'$variable'` to the `getThing()` method).
+> Arguments must be literals, and cannot be other template variables (`$Thing($variable)` will pass the literal string `'$variable'` to the `getThing()` method).
 
 - `$Foo("param")` will call `$obj->Foo("param")`
 - `$Foo.Bar` will call `$obj->Foo()->Bar`
@@ -90,11 +87,11 @@ These variables will call a method / field on the object and insert the returned
 > - `$Foo(0.5)` will pass `0.5` as a float
 > - `$Foo(true)` will pass `true` as a boolean
 > - `$Foo(null)` will pass `null` as a null primitive
-> - `$Foo("param")`, `$Foo('param')`, and `$Foo(param)` will all pass `'param'` as a string. It is recommended that you always use quotes when passing a string for clarity
+> - `$Foo("param")`, `$Foo('param')`, and `$Foo(param)` will all pass `'param'` as a string. It is recommended that you always use quotes when passing a string for clarity and for future-proofing.
 
 If a variable returns a string, that string will be inserted into the template. If the variable returns an object, then
 the system will attempt to render the object through its `forTemplate()` method. If the `forTemplate()` method has not
-been defined, the system will return an error.
+been defined, the system will attempt to cast the object to a string.
 
 > [!NOTE]
 > For more details around how variables are inserted and formatted into a template see
@@ -125,10 +122,11 @@ class MyObject extends DataObject
 ```
 
 > [!NOTE]
-> Method names that begin with `get` will automatically be resolved when their prefix is excluded. For example, the above method call `$UsersIpAddress` would also invoke a method named `getUsersIpAddress()`.
+> Method names that begin with `get` will automatically be resolved when their prefix is excluded. For example, if the method `UsersIpAddress()` didn't exist, the above reference to `$UsersIpAddress` would invoke a method named `getUsersIpAddress()`.
+> Note that a method with the exact name you're referencing will always be used if it exists.
 
 The variables that can be used in a template vary based on the object currently in scope (see [scope](#scope) below). Scope defines what
-object the methods get called on. For the standard `Page.ss` template the scope is the current [`ContentController`](api:SilverStripe\CMS\Controllers\ContentController)
+object the methods get called on. For the standard `Page.ss` template the scope is usually the current [`ContentController`](api:SilverStripe\CMS\Controllers\ContentController)
 object. This object provides access to all the public methods on that controller, as well as the public methods, relations, and database fields for its corresponding [`SiteTree`](api:SilverStripe\CMS\Model\SiteTree) record.
 
 ```ss
@@ -206,7 +204,7 @@ For more nuanced conditions you can use the `!=` operator.
 
 ### Boolean logic
 
-Multiple checks can be done using `||`/`or`, or `&&`/ `and`.
+Multiple checks can be done using `||`/`or`, or `&&`/`and`.
 
 > [!NOTE]
 > `or` is functionally equivalent to `||` in template conditions, and `and` is functionally equivalent to `&&`.
@@ -564,39 +562,24 @@ refer directly to properties and methods of the [`Member`](api:SilverStripe\Secu
 
 ### `fortemplate()` and `$Me` {#fortemplate}
 
-If you reference some `ModelData` object directly in a template, the `forTemplate()` method on that object will be called.
-This can be used to provide a default template for an object.
-
-```php
-// app/src/PageType/HomePage.php
-namespace App\PageType;
-
-use Page;
-
-class HomePage extends Page
-{
-    public function forTemplate(): string
-    {
-        // We can also render a template here using $this->renderWith()
-        return 'Page: ' . $this->Title;
-    }
-}
-```
+If you reference some object directly in a template, the `forTemplate()` method on that object will be called. This can be used to provide a default template for an object.
+If the `forTemplate()` method isn't implemented, the system will attempt to cast your object to a string.
+The default implementation of this method on `ModelData` renders the model using templates named after the class or its superclasses.
 
 ```ss
-<%-- calls forTemplate() on the first page in the list and prints Page: Home --%>
+<%-- calls forTemplate() on the first page in the list --%>
 $Pages->First
 ```
 
 You can also use the `$Me` variable, which outputs the current object in scope by calling `forTemplate()` on the object.
 This is especially helpful when you want to directly render items in a list you're looping over.
 
 > [!WARNING]
-> If the object does not have a `forTemplate()` method implemented, this will throw an error.
+> If a `ModelData` object does not have an appropriate template or override the `forTemplate()` method, this will throw an error.
 
 ```ss
 <% loop $Pages %>
-    <%-- calls forTemplate() on the current object in scope and prints Page: Home --%>
+    <%-- calls forTemplate() on the current object in scope --%>
     $Me
 <% end_loop %>
 ```

en/02_Developer_Guides/01_Templates/02_Common_Variables.md

@@ -36,11 +36,11 @@ have a read of the [Formatting, Modifying and Casting Variables](casting) docume
 </head>
 ```
 
-The `<% base_tag %>` placeholder is replaced with the HTML base element. Relative links within a document (such as
+The `<% base_tag %>` placeholder is replaced with the HTML `<base>` element. Relative links within a document (such as
 `<img src="someimage.jpg" alt="">`) will become relative to the URI specified in the base tag. This ensures the
 browser knows where to locate your site’s images and CSS files.
 
-It renders in the template as `<base href="https://www.example.com" /><!--[if lte IE 6]></base><![endif]-->`
+It renders in the template as `<base href="https://www.example.com/">`
 
 > [!CAUTION]
 > A `<% base_tag %>` is nearly always required or assumed by Silverstripe CMS to exist.
@@ -117,20 +117,20 @@ on a per-page basis.
 
 By default `$MetaTags` renders (assuming 5.1.0 is the current version of `silverstripe/framework`):
 
-```ss
+```html
 <title>Title of the Page</title>
 <meta name="generator" content="Silverstripe CMS 5.1">
 <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
 ```
 
 `$MetaTags(false)` will render
 
-```ss
+```html
 <meta name="generator" content="Silverstripe CMS 5.1">
 <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
 ```
 
-If using `$MetaTags(false)` we can provide a more custom `title`.
+If using `$MetaTags(false)` we can provide a custom `<title> tag`.
 
 ```ss
 $MetaTags(false)

en/02_Developer_Guides/01_Templates/03_Requirements.md

@@ -94,7 +94,7 @@ Also see [Direct resource urls](#direct-resource-urls) below if you need to incl
 ## PHP requirements API
 
 It is common practice to include most Requirements either in the `init()` method of your [controller](../controllers/), or
-as close to rendering as possible (e.g. in [FormField](api:SilverStripe\Forms\FormField)).
+as close to rendering as possible (e.g. in [`FormField::Field()`](api:SilverStripe\Forms\FormField::Field())).
 
 ```php
 namespace App\Control;
@@ -451,7 +451,7 @@ If you want to get a resource for a *specific* theme or from somewhere that is n
 ```
 
 > [!TIP]
-> Notice the `vendor/module:some/path/to/file.jpg` syntax (used to get a resource from a specific module) is only valid for the `$resourceURL()` helper method. It won't work for `themedResourceURL()`.
+> Notice the `vendor/module:some/path/to/file.jpg` syntax (used to get a resource from a specific module) is only valid for the `$resourceURL()` helper method. It won't work for `$themedResourceURL()`.
 
 ### Resource URLs or filepaths from a PHP context
 

en/02_Developer_Guides/01_Templates/04_Rendering_Templates.md

@@ -6,6 +6,9 @@ icon: code
 
 # Rendering data to a template
 
+> [!NOTE]
+> The template syntax, file extensions, and specifics about which tempaltes are chosen from a set as described on this page are specific to the default [`SSTemplateEngine`](api:SilverStripe\View\SSTemplateEngine) - but many of the concepts here (especially the PHP code) should work with any template engine you choose to use.
+
 Templates do nothing on their own. Rather, they are used to generate markup - most typically they are used to generate HTML markup, using variables from some `ModelData` object.
 All of the `<% if %>`, `<% loop %>` and other variables are methods or parameters that are called on the current object in
 scope (see [scope](syntax#scope) in the syntax section).
@@ -19,6 +22,9 @@ The following will render the given data into a template. Given the template:
 
 Our application code can render into that view using the [`renderWith()`](api:SilverStripe\Model\ModelData) method provided by `ModelData`. Call this method on any instance of `ModelData` or its subclasses, passing in a template name or an array of templates to render.
 
+> [!IMPORTANT]
+> Don't include the `.ss` file extension when referencing templates.
+
 ```php
 namespace App\Model;
 
@@ -44,6 +50,11 @@ class MyModel extends DataObject
 
 If you want to render an arbitrary template into the `$Layout` section of a page, you need to render your layout template and pass that as the `Layout` parameter to the Page template.
 
+These examples assume you have moved the `templates/Coach_Message.ss` template file to `templates/Layout/Coach_Message.ss`
+
+> [!WARNING]
+> While a lot of the concepts on this page apply for any template engine, the `$Layout` functionality is specific to the default [`SSTemplateEngine`](api:SilverStripe\View\SSTemplateEngine).
+
 ```php
 namespace App\Model;
 
@@ -71,7 +82,6 @@ class MyModel extends DataObject
 In this case it may be better to use an *implicit* `Layout` type template, and rely on template inheritance to figure out which templates to use.
 
 ```php
-// This assumes you have moved the Coach_Message template to `templates/Layout/Coach_Message.ss`
 $this->customise($data)->renderWith(['Coach_Message', 'Page']);
 ```
 
@@ -157,16 +167,15 @@ class MyPageController extends PageController
 
 ## Rendering arbitrary data in templates
 
-Any data you want to render into the template that does not extend `ModelData` should be wrapped in an object that
-does, such as `ArrayData` or `ArrayList`.
+While `ModelData` has some methods on it you may find useful for reprensenting complex data, you should be able to use just about anything as a model in a template.
+
+To actually render the data, you can use the `customise()` method to add your arbitrary data on top of an existing model:
 
 ```php
 namespace App\PageType;
 
 use PageController;
 use SilverStripe\Control\Director;
-use SilverStripe\Model\ArrayData;
-use SilverStripe\Model\List\ArrayList;
 
 class MyPageController extends PageController
 {
@@ -178,14 +187,14 @@ class MyPageController extends PageController
             return $this->customise([
                 'Name' => 'John',
                 'Role' => 'Head Coach',
-                'Experience' => ArrayList::create([
-                    ArrayData::create([
+                'Experience' => [
+                    [
                         'Title' => 'First Job',
-                    ])
-                    ArrayData::create([
+                    ],
+                    [
                         'Title' => 'Second Job',
-                    ]),
-                ]),
+                    ],
+                ],
             ])->renderWith('AjaxTemplate');
         } else {
             return $this->httpError(400);
@@ -194,5 +203,62 @@ class MyPageController extends PageController
 }
 ```
 
-> [!WARNING]
-> A common mistake is trying to loop over an array directly in a template - this won't work. You'll need to wrap the array in some `ModelData` instance as mentioned above.
+Or wrap the data in a `ModelData` subclass:
+
+```php
+namespace App\PageType;
+
+use PageController;
+use SilverStripe\Model\ArrayData;
+
+class MyPageController extends PageController
+{
+    // ...
+
+    public function getMyRenderedData()
+    {
+        return ArrayData::create([
+            'Name' => 'John',
+            'Role' => 'Head Coach',
+            'Experience' => [
+                [
+                    'Title' => 'First Job',
+                ],
+                [
+                    'Title' => 'Second Job',
+                ],
+            ],
+        ])->renderWith('MyTemplate');
+    }
+}
+```
+
+Or you can hand the data to `SSViewer` directly:
+
+```php
+namespace App\PageType;
+
+use PageController;
+use SilverStripe\View\SSViewer;
+
+class MyPageController extends PageController
+{
+    // ...
+
+    public function getMyRenderedData()
+    {
+        return SSViewer::create('MyTemplate')->process([
+            'Name' => 'John',
+            'Role' => 'Head Coach',
+            'Experience' => [
+                [
+                    'Title' => 'First Job',
+                ],
+                [
+                    'Title' => 'Second Job',
+                ],
+            ],
+        ]);
+    }
+}
+```

en/02_Developer_Guides/01_Templates/05_Template_Inheritance.md

@@ -103,21 +103,6 @@ to determine resolution priority. This search is based on the following three co
    the module author, and does not normally need to be customised. This includes the `$project` and
    `$other_modules` placeholder values.
 
-### ThemeResourceLoader
-
-The resolution of themes is performed by a [ThemeResourceLoader](api:SilverStripe\View\ThemeResourceLoader)
-instance, which resolves a template (or list of templates) and a set of themes to a system template path.
-
-For each path the loader will search in this order:
-
-- Loop through each theme which is configured.
-- If a theme is a set (declared with the `$` prefix, e.g. `$default`) it will perform a nested search within
-   that set.
-- When searching the `$default` set, all modules will be searched in the order declared via the `module_priority`
-   config, interpolating keys `$project` and `$other_modules` as necessary. By default, your project's templates should
-   be checked before any vendor modules.
-- When the first template is found, it will be immediately returned, and will not continue to search.
-
 ### Declaring themes
 
 All themes can be enabled and sorted via the `SilverStripe\View\SSViewer.themes` config value. For reference

en/02_Developer_Guides/01_Templates/07_Caching.md

@@ -8,8 +8,8 @@ icon: rocket
 
 ## Object caching
 
-All functions that provide data to templates must have no side effects, as the value is cached after first access. For
-example, this controller method will not behave as you might imagine.
+Any values accessed from a template on a `ModelData` object are cached after first access. Because of this, methods that provide data to templates should ideally have no side effects. For
+example, this `getCounter()` method will not behave as you might imagine when invoked from a template.
 
 ```php
 namespace App\Model;
@@ -33,8 +33,7 @@ class MyObject extends DataObject
 
 ```ss
 $Counter, $Counter, $Counter
-
-// returns 1, 1, 1
+// renders as 1, 1, 1
 ```
 
 When we render `$Counter` to the template we would expect the value to increase and output `1, 2, 3`. However, as
@@ -51,3 +50,9 @@ Example:
     $CacheableContent
 <% end_cached %>
 ```
+
+## Template caching
+
+Every time a raw template file is processed, some PHP code is generated from it which is then executed to produce the final rendered result.
+
+That PHP code is stored in the filesystem so that the raw template file doesn't need to be processed again until either the cache is flushed or the raw template file is updated.