From c093ebcdae6daf5817262c4af331afce7720ae36 Mon Sep 17 00:00:00 2001 From: Guy Sartorelli Date: Mon, 4 Nov 2024 16:33:55 +1300 Subject: [PATCH] DOC Document moving template engine into its own module --- .../01_Templates/01_Syntax.md | 2 +- .../01_Templates/04_Rendering_Templates.md | 4 ++-- .../11_Partial_Template_Caching.md | 8 ++++---- .../08_Performance/01_Caching.md | 2 +- en/08_Changelogs/6.0.0.md | 18 +++++++++++++++--- .../07_Supported_Modules.md | 1 + 6 files changed, 24 insertions(+), 11 deletions(-) diff --git a/en/02_Developer_Guides/01_Templates/01_Syntax.md b/en/02_Developer_Guides/01_Templates/01_Syntax.md index 2d8a30c63..d43cdf817 100644 --- a/en/02_Developer_Guides/01_Templates/01_Syntax.md +++ b/en/02_Developer_Guides/01_Templates/01_Syntax.md @@ -369,7 +369,7 @@ Methods can also be chained. ### Position indicators Inside the loop scope, there are many variables at your disposal to determine the current position in the list and -iteration. These are provided by [`SSViewer_BasicIteratorSupport::get_template_iterator_variables()`](api:SilverStripe\View\SSViewer_BasicIteratorSupport::get_template_iterator_variables()). +iteration. These are provided by [`BasicIteratorSupport::get_template_iterator_variables()`](api:SilverStripe\TemplateEngine\BasicIteratorSupport::get_template_iterator_variables()). - `$Even`, `$Odd`: Returns boolean based on the current position in the list (see `$Pos` below). Handy for zebra striping. - `$EvenOdd`: Returns a string based on the current position in the list, either 'even' or 'odd'. Useful for CSS classes. diff --git a/en/02_Developer_Guides/01_Templates/04_Rendering_Templates.md b/en/02_Developer_Guides/01_Templates/04_Rendering_Templates.md index e0cc29aba..ab3c21932 100644 --- a/en/02_Developer_Guides/01_Templates/04_Rendering_Templates.md +++ b/en/02_Developer_Guides/01_Templates/04_Rendering_Templates.md @@ -7,7 +7,7 @@ icon: code # Rendering data to a template > [!NOTE] -> 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. +> 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\TemplateEngine\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 @@ -53,7 +53,7 @@ If you want to render an arbitrary template into the `$Layout` section of a page 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). +> 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\TemplateEngine\SSTemplateEngine). ```php namespace App\Model; diff --git a/en/02_Developer_Guides/01_Templates/11_Partial_Template_Caching.md b/en/02_Developer_Guides/01_Templates/11_Partial_Template_Caching.md index 8eab59ea6..28bd3f2be 100644 --- a/en/02_Developer_Guides/01_Templates/11_Partial_Template_Caching.md +++ b/en/02_Developer_Guides/01_Templates/11_Partial_Template_Caching.md @@ -49,7 +49,7 @@ different templates. Here is how it works in detail: -1. `SilverStripe\View\SSTemplateEngine.global_key` hash +1. `SilverStripe\TemplateEngine\SSTemplateEngine.global_key` hash With the current template context, value of the `$global_key` configuration property is rendered into a string and hashed. @@ -64,7 +64,7 @@ Here is how it works in detail: ```yml # app/_config/view.yml - SilverStripe\View\SSTemplateEngine: + SilverStripe\TemplateEngine\SSTemplateEngine: global_key: '$CurrentReadingMode, $CurrentUser.ID, $CurrentLocale' ``` @@ -86,7 +86,7 @@ Here is how it works in detail: A string produced by concatenation of all the values mentioned above is used as the final value. - Even if `$CacheKey` is omitted, `SilverStripe\View\SSTemplateEngine.global_key` and `Block hash` values are still + Even if `$CacheKey` is omitted, `SilverStripe\TemplateEngine\SSTemplateEngine.global_key` and `Block hash` values are still getting used to generate cache key for the caching backend storage. #### Cache key calculated in controller @@ -340,7 +340,7 @@ The two following forms produce the same result <%-- Hash of this content block is also included into the final Cache Key value along with - SilverStripe\View\SSTemplateEngine::$global_key + SilverStripe\TemplateEngine\SSTemplateEngine::$global_key --%> <% uncached %> This text is always dynamic (never cached) diff --git a/en/02_Developer_Guides/08_Performance/01_Caching.md b/en/02_Developer_Guides/08_Performance/01_Caching.md index df51bc7df..e4e4feb80 100644 --- a/en/02_Developer_Guides/08_Performance/01_Caching.md +++ b/en/02_Developer_Guides/08_Performance/01_Caching.md @@ -293,7 +293,7 @@ SilverStripe\Core\Injector\Injector: Unfortunately not all caches are configurable via cache adapters. -- [`SSTemplateEngine`](api:SilverStripe\View\SSTemplateEngine) writes compiled templates as PHP files to the filesystem +- [`SSTemplateEngine`](api:SilverStripe\TemplateEngine\SSTemplateEngine) writes compiled templates as PHP files to the filesystem (in order to achieve opcode caching on `include()` calls) - [i18n](api:SilverStripe\i18n\i18n) uses `Symfony\Component\Config\ConfigCacheFactoryInterface` (filesystem-based) diff --git a/en/08_Changelogs/6.0.0.md b/en/08_Changelogs/6.0.0.md index 10ade37e1..f0cc28043 100644 --- a/en/08_Changelogs/6.0.0.md +++ b/en/08_Changelogs/6.0.0.md @@ -505,17 +505,29 @@ This made that class difficult to maintain. More importantly, it made it difficu The template rendering functionality has now been abstracted. `SSViewer` still acts as the barrier between the model and template layers, but it now delegates rendering templates to an injectable [`TemplateEngine`](api:SilverStripe\View\TemplateEngine). -`TemplateEngine` is an interface with all of the methods required for `SSViewer` and the rest of Silverstripe CMS to interact reliably with your template rendering solution of choice. For now, all of the templates provided in core and supported modules will use the familiar ss template syntax and the default template engine will be [`SSTemplateEngine`](api:SilverStripe\View\SSTemplateEngine) - but the door is now open for you to experiment with alternative template rendering solutions if you want to. +`TemplateEngine` is an interface with all of the methods required for `SSViewer` and the rest of Silverstripe CMS to interact reliably with your template rendering solution of choice. For now, all of the templates provided in core and supported modules will use the familiar ss template syntax and the default template engine will be [`SSTemplateEngine`](api:SilverStripe\TemplateEngine\SSTemplateEngine). This template engine lives in the new [`silverstripe/template-engine` module](https://github.com/silverstripe/silverstripe-template-engine/). -There are various ways to declare which rendering engine to use, which are explained in detail in the [swap template engines](/developer_guides/templates/swap_template_engines/) documentation. +Along with making the default template engine easier to maintain, these changes also open the door for you to experiment with alternative template rendering solutions if you want to. There are various ways to declare which rendering engine to use, which are explained in detail in the [swap template engines](/developer_guides/templates/swap_template_engines/) documentation. Some API which used to be on `SSViewer` is now on `SSTemplateEngine`, and some has been outright removed. The common ones are listed here, but see [full list of removed and changed API](#api-removed-and-changed) below for the full list. -- The `SSViewer.global_key` configuration property is now [`SSTemplateEngine.global_key`](api:SilverStripe\View\SSTemplateEngine->global_key). +- The `SSViewer.global_key` configuration property is now [`SSTemplateEngine.global_key`](api:SilverStripe\TemplateEngine\SSTemplateEngine->global_key). - `SSViewer::chooseTemplate()` has been removed without a replacement. - `SSViewer::hasTemplate()` is now [`TemplateEngine::hasTemplate()`](api:SilverStripe\View\TemplateEngine::hasTemplate()). - `SSViewer::fromString()` and the `SSViewer_FromString` class have been replaced with [`TemplateEngine::renderString()`](api:SilverStripe\View\TemplateEngine::renderString()). +Along with those API changes, the following classes and interfaces were moved into the new module: + +|old class|new class| +|---|---| +|`SilverStripe\View\SSViewer_BasicIteratorSupport`|[`SilverStripe\TemplateEngine\BasicIteratorSupport`](api:SilverStripe\TemplateEngine\BasicIteratorSupport)| +|`SilverStripe\View\SSTemplateParseException`|[`SilverStripe\TemplateEngine\Exception\SSTemplateParseException`](api:SilverStripe\TemplateEngine\Exception\SSTemplateParseException)| +|`SilverStripe\View\SSTemplateParser`|[`SilverStripe\TemplateEngine\SSTemplateParser`](api:SilverStripe\TemplateEngine\SSTemplateParser)| +|`SilverStripe\View\SSViewer_Scope`|[`SilverStripe\TemplateEngine\ScopeManager`](api:SilverStripe\TemplateEngine\ScopeManager)| +|`SilverStripe\View\SSViewer_DataPresenter`|[`SilverStripe\TemplateEngine\ScopeManager`](api:SilverStripe\TemplateEngine\ScopeManager)| +|`SilverStripe\View\TemplateIteratorProvider`|[`SilverStripe\TemplateEngine\TemplateIteratorProvider`](api:SilverStripe\TemplateEngine\TemplateIteratorProvider)| +|`SilverStripe\View\TemplateParser`|[`SilverStripe\TemplateEngine\TemplateParser`](api:SilverStripe\TemplateEngine\TemplateParser)| + If you want to just keep using the ss template syntax you're familiar with, you shouldn't need to change anything (except as specified in other sections or if you were using API that has moved or been removed). #### Strong typing for `ModelData` and `DBField` diff --git a/en/12_Project_Governance/07_Supported_Modules.md b/en/12_Project_Governance/07_Supported_Modules.md index 81220eb45..00c575da0 100644 --- a/en/12_Project_Governance/07_Supported_Modules.md +++ b/en/12_Project_Governance/07_Supported_Modules.md @@ -43,6 +43,7 @@ Core Module | Supported major release line [silverstripe/reports](https://packagist.org/packages/silverstripe/reports) | 5 [silverstripe/session-manager](https://packagist.org/packages/silverstripe/session-manager) | 2 [silverstripe/siteconfig](https://packagist.org/packages/silverstripe/siteconfig) | 5 +[silverstripe/template-engine](https://packagist.org/packages/silverstripe/silverstripe-template-engine) | 1 [silverstripe/vendor-plugin](https://packagist.org/packages/silverstripe/vendor-plugin) | 2 [silverstripe/versioned](https://packagist.org/packages/silverstripe/versioned) | 2 [silverstripe/versioned-admin](https://packagist.org/packages/silverstripe/versioned-admin) | 2