DOC Document changes to template layer #591

GuySartorelli · 2024-09-26T04:27:33Z

Issue

Abstract template layer into its own dedicated module silverstripe-framework#11322

GuySartorelli · 2024-10-23T02:38:04Z

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

-$Foo(param)
+$Foo("param")


mostly-unrelated update to promote best practice

GuySartorelli · 2024-10-23T02:39:14Z

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

 $Foo.Bar
 ```

 These variables will call a method / field on the object and insert the returned value as a string into the template.

+Arguments don't have to be literals - you can pass template variables as arguments as well.


This is new and was mostly just a natural consequence of how we're wrapping data now. Very useful though, I'm already gonna use it in the CMSMain refactor.

GuySartorelli · 2024-10-23T02:40:24Z

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

-> 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 cannot be literal arrays (e.g `$myMethod(["val1", "val2"])`). The behaviour for this is currently undefined.


This was mostly saying "you can't pass template variables as arguments" which as noted above is no longer the case. It's just array literals you can't do now.

GuySartorelli · 2024-10-23T02:41:22Z

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

-> Arguments passed into methods can be any non-array literal type (not just strings), e.g:
+> Arguments passed into methods can be almost any type (not just strings), e.g:


At first glance you might think to leave as-is cause we still can't do arrays - but it doesn't have to be a literal anymore which the old text said it does.

GuySartorelli · 2024-10-23T02:44:12Z

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

-
-    public function UsersIpAddress()
+    public function usersIpAddress()


Unrelated change to promote best practice. Also updated casing on the below.

GuySartorelli · 2024-10-23T02:50:09Z

en/02_Developer_Guides/01_Templates/09_Casting.md

-All objects that are being rendered in a template should be a [ModelData](api:SilverStripe\Model\ModelData) instance such as `DataObject`,
-`DBField` or `Controller`. From these objects, the template can include any method from the object in [scope](syntax#scope).
+Classes that subclass [`ModelData`](api:SilverStripe\Model\ModelData) (such as `DataObject`,
+`DBField` or `Controller`) can define how their values should be cast or escaped when used in a template.


You can pass basically anything into templates, doesn't have to be ModelData - but the ability to define casting like this is unique to ModelData and its subclasses.

GuySartorelli · 2024-10-23T02:51:59Z

en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_Preview.md

-The `forTemplate` method will probably look something like this:
-
-```php
-namespace App\Model;
-
-use SilverStripe\ORM\CMSPreviewable;
-use SilverStripe\ORM\DataObject;
-
-class Product extends DataObject implements CMSPreviewable
-{
-    // ...
-
-    public function forTemplate(): string
-    {
-        // If the template for this DataObject is not an "Include" template, use the appropriate type here
-        // e.g. "Layout".
-        return $this->renderWith(['type' => 'Includes', self::class]);
-    }
-}
-```


Remove unnecessary example now that the default implementation in ModelData does this for you.

GuySartorelli · 2024-10-23T02:52:22Z

en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_Preview.md

->         $preview = SSViewer::create('PreviewBase')->process(ArrayData::create(['Preview' => $preview]));
+>         $preview = SSViewer::create('PreviewBase')->process(['Preview' => $preview]);


No need to wrap them anymore. I'd argue it's even best practice to not wrap them.

GuySartorelli · 2024-10-23T02:53:05Z

en/08_Changelogs/6.0.0.md

@@ -526,12 +582,12 @@ You can change the level of entropy required by passing one of the valid [minSco

 ### Other new features

- Native indexed PHP arrays can now be passed into templates and iterated over with `<% loop $MyArray %>`. Under the hood they are wrapped in [`ArrayList`](api:SilverStripe\Model\List\ArrayList), so you can get the count using `$Count` and use `<% if $ArrayList %>` as a shortcut for `<% if $ArrayList.Count %>`. Other functionality from `ArrayList` such as filtering and sorting cannot be used on arrays since they don't have keys to filter or sort against.


Moved this into the template changes section

GuySartorelli · 2024-10-23T02:53:21Z

en/08_Changelogs/6.0.0.md

 - Modules no longer need to have a root level `_config.php` or `_config` directory to be recognised as a Silverstripe CMS module. They will now be recognised as a module if they have a `composer.json` file with a `type` of `silverstripe-vendormodule` or `silverstripe-theme`.
 - A new [`DataObject::getCMSEditLink()`](api:SilverStripe\ORM\DataObject::getCMSEditLink()) method has been added, which returns `null` by default. This provides more consistency for that method which has previously been inconsistently applied to various subclasses of `DataObject`. See [managing records](/developer_guides/model/managing_records/#getting-an-edit-link) for more details about providing sane values for this method in your own subclasses.
 - The `CMSEditLink()` method on many `DataObject` subclasses has been renamed to `getCMSEditLink()`.
 - The [`UrlField`](api:SilverStripe\Forms\UrlField) class has some new API for setting which protocols are allowed for valid URLs.
 - The [`EmailField`](api:SilverStripe\Forms\EmailField) class now uses `symfony/validator` to handle its validation logic, where previously this was validated with a custom regex.
+- [`ArrayData`](api:SilverStripe\Model\ArrayData) can now be serialised using [`json_encode()`](https://www.php.net/manual/en/function.json-encode.php).


This isn't directly related to templates so adding here instead.

emteknetnz · 2024-10-15T02:14:32Z

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

+
+Just like in PHP, method names are case insensitive, but property names are case sensitive.
+
+Using `$MyValue` in a template will successfully call a `myValue()` method, or a `getMyvalue()` method even though the case doesn't match what you used in the template. But it *will not* match a `myValue` property or database field because the case doesn't match.


Suggested change

Using `$MyValue` in a template will successfully call a `myValue()` method, or a `getMyvalue()` method even though the case doesn't match what you used in the template. But it *will not* match a `myValue` property or database field because the case doesn't match.

Using `$MyValue` in a template will successfully call a `myValue()` method, or a `getMyValue()` method even though the case doesn't match what you used in the template. But it *will not* match a `myValue` property or database field because the case doesn't match.

emteknetnz · 2024-10-15T02:27:52Z

en/08_Changelogs/6.0.0.md

@@ -459,6 +459,62 @@ Note that the `SilverStripe\View\ViewableData` class has been renamed to [`Silve

 See [many renamed classes](#renamed-classes) for more information about this change.

+#### Improved separation between the view and model layers {#view-layer-separation}
+
+Historically the `ModelData` class did double-duty as being the base class for most models as well as being the presumed class wrapping data for the template layer. Part of this included methods like `XML_val()` being called on any object in the template layer, despite being methods very specifically implemented on `ModelData`.


Historically it's been called ViewableData ? Maybe mention that ModelData used to be called ViewableData

emteknetnz · 2024-10-25T01:39:30Z

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.


Suggested change

> 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.

> The template syntax, file extensions, and specifics about which templates 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.

emteknetnz · 2024-10-25T01:41:36Z

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

@@ -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:


Suggested change

Or wrap the data in a `ModelData` subclass:

Or wrap the data in a `ModelData` subclass such as `ArrayList`:

emteknetnz · 2024-10-25T01:45:11Z

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

+
+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.


Suggested change

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.

That PHP code is cached 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.

Just ties it together a little better

GuySartorelli marked this pull request as draft September 26, 2024 04:27

GuySartorelli mentioned this pull request Sep 26, 2024

Abstract template layer into its own dedicated module silverstripe/silverstripe-framework#11322

Open

23 tasks

GuySartorelli force-pushed the pulls/6/refactor-template-layer branch 3 times, most recently from 94d90fe to 827cb70 Compare October 4, 2024 00:21

GuySartorelli force-pushed the pulls/6/refactor-template-layer branch 8 times, most recently from a6f45e5 to fd791b5 Compare October 14, 2024 02:57

DOC Document changes to template layer

a23cf76

GuySartorelli force-pushed the pulls/6/refactor-template-layer branch from fd791b5 to a23cf76 Compare October 22, 2024 00:11

GuySartorelli marked this pull request as ready for review October 23, 2024 02:37

GuySartorelli commented Oct 23, 2024

View reviewed changes

emteknetnz requested changes Oct 25, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC Document changes to template layer #591

DOC Document changes to template layer #591

GuySartorelli commented Sep 26, 2024

GuySartorelli Oct 23, 2024

GuySartorelli Oct 23, 2024

GuySartorelli Oct 23, 2024

GuySartorelli Oct 23, 2024

GuySartorelli Oct 23, 2024

GuySartorelli Oct 23, 2024

GuySartorelli Oct 23, 2024

GuySartorelli Oct 23, 2024

GuySartorelli Oct 23, 2024

GuySartorelli Oct 23, 2024

emteknetnz Oct 15, 2024

emteknetnz Oct 15, 2024

emteknetnz Oct 25, 2024

emteknetnz Oct 25, 2024

emteknetnz Oct 25, 2024

emteknetnz Oct 25, 2024

		> Arguments passed into methods can be any non-array literal type (not just strings), e.g:
		> Arguments passed into methods can be almost any type (not just strings), e.g:


		public function UsersIpAddress()
		public function usersIpAddress()

		> $preview = SSViewer::create('PreviewBase')->process(ArrayData::create(['Preview' => $preview]));
		> $preview = SSViewer::create('PreviewBase')->process(['Preview' => $preview]);

		@@ -526,12 +582,12 @@ You can change the level of entropy required by passing one of the valid [minSco

		### Other new features

		- Native indexed PHP arrays can now be passed into templates and iterated over with `<% loop $MyArray %>`. Under the hood they are wrapped in [`ArrayList`](api:SilverStripe\Model\List\ArrayList), so you can get the count using `$Count` and use `<% if $ArrayList %>` as a shortcut for `<% if $ArrayList.Count %>`. Other functionality from `ArrayList` such as filtering and sorting cannot be used on arrays since they don't have keys to filter or sort against.


		Just like in PHP, method names are case insensitive, but property names are case sensitive.

		Using `$MyValue` in a template will successfully call a `myValue()` method, or a `getMyvalue()` method even though the case doesn't match what you used in the template. But it will not match a `myValue` property or database field because the case doesn't match.

	> 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.
	> The template syntax, file extensions, and specifics about which templates 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.

	Or wrap the data in a `ModelData` subclass:
	Or wrap the data in a `ModelData` subclass such as `ArrayList`:


		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.

	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.
	That PHP code is cached 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.

		$Foo(param)
		$Foo("param")

DOC Document changes to template layer #591

Are you sure you want to change the base?

DOC Document changes to template layer #591

Conversation

GuySartorelli commented Sep 26, 2024

Issue

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment