Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC Document moving template engine into its own module #622

Merged
merged 1 commit into from
Nov 6, 2024
+24 −11
Merged

DOC Document moving template engine into its own module #622

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion en/02_Developer_Guides/01_Templates/01_Syntax.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions en/02_Developer_Guides/01_Templates/04_Rendering_Templates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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;
Expand Down
8 changes: 4 additions & 4 deletions en/02_Developer_Guides/01_Templates/11_Partial_Template_Caching.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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'
```

Expand All @@ -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
Expand Down Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion en/02_Developer_Guides/08_Performance/01_Caching.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
18 changes: 15 additions & 3 deletions en/08_Changelogs/6.0.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)|
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you sure about this one? I don't see a deleted SSViewer_DataPresenter.php file in the framework PR, and it's being renamed to ScopeManager which seems wrong.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was removed in an earlier PR, merged into scope. The effect for anyone upgrading straight from 5 to 6 is that the class is removed and everything is used to do is handled by the scope manager.

|`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`
Expand Down
1 change: 1 addition & 0 deletions en/12_Project_Governance/07_Supported_Modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down