[FEATURE] Introduce optional .fluid.* file extension #1258
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Historically, Fluid has always used generic file extensions for template files, such as `.html`, `.txt` or `.xml`. While this provides IDE integration out-of-the-box, it makes it hard to distinguish files that are interpreted by Fluid and others that are just text or html files. This patch introduces an optional (!) new file extension for Fluid template files that is added _in addition_ to the generic file extension: `.fluid.html` for html files, `.fluid.txt` for text files, and so on. Template files are now detected in the following order (first existing file wins): ``` templateRootPath: templates/ template: myTemplate format: html 1. templates/myTemplate.fluid.html 2. templates/myTemplate.html 3. templates/myTemplate 4. templates/MyTemplate.fluid.html 5. templates/MyTemplate.html 6. templates/MyTemplate ``` If multiple template paths are defined, this chain is executed for each path separately, before falling back to the next path. This means that (in the TYPO3 context) an extension can ship `.html` files and another extension can override these files with `.fluid.html` files. It also works in reverse: The extension can ship `.fluid.html`, which can be overwritten with `.html` files. In short: The order of paths is respected, regardless of the file extension. This will make it possible to ship TYPO3 extensions compatible with v13/v14 (= ships `.html`), while a sitepackage in a v14 project can already use `.fluid.html` files. It also means that the core can rename all templates to `.fluid.html` without breaking extensions that overwrite core templates (e. g. email templates) with `.html` files. The order of file extensions has been discussed intensively, but in the end we decided to land on `.fluid.*`. Major reasons: * We currently already have mediocre IDE/editor support at best. Using `.fluid` as primary file extension would remove code highlighting completely until we can address each highlighter individually. This would also include things like Gerrit, GitHub or GitLab. Our time is not well spent to introduce a completely new file extension when there's an easier alternative. * With `*.form.yaml` there is already precedent in the TYPO3 cosmos. Introducing this file extension not only helps users to recognize Fluid templates, it also allows us to create better IDE integrations in the future. Also, it enables us to scan a whole project for Fluid templates, which makes cache warmup and linting tasks config-free.
s2b
force-pushed
the
feature/fluidFileExtension
branch
from
0962e46 to
7c59eee
Compare
s2b
added a commit
that referenced
this pull request
Nov 8, 2025
Previous Fluid versions already had a CLI command which could be used to warmup the cache for template files, e. g. during deployment. However, the previous implementation required a lot of additional context and mixed parsing/compilation and rendering state. The previous warmup implementation has already been deprecated with Fluid v4 and removed from Fluid v5 and is now replaced with a more straightforward implementation. The new CLI command needs to be supplied with a list of paths that should be scanned for template files as well as the location of the template cache. By default, the command uses the newly introduced Fluid file extension (see #1258) to identify Fluid templates. However, optionally an alternative file extension can be supplied as well. ``` bin/fluid warmup --paths examples/Resources/ --cacheDirectory examples/cache/ bin/fluid warmup --paths examples/Resources/ --cacheDirectory examples/cache/ --extension html ``` In addition to the cache warmup, the command collects and outputs exceptions and deprecations that happened during parsing and compilation of the found template files. The underlying API, namely `TemplateFinder` for finding template files and `TemplateValidator`, which produces a validation report for each template, are marked as `@internal` for now. Resolves: #1103
s2b
added a commit
that referenced
this pull request
Nov 8, 2025
Previous Fluid versions already had a CLI command which could be used to warmup the cache for template files, e. g. during deployment. However, the previous implementation required a lot of additional context and mixed parsing/compilation and rendering state. The previous warmup implementation has already been deprecated with Fluid v4 and removed from Fluid v5 and is now replaced with a more straightforward implementation. The new CLI command needs to be supplied with a list of paths that should be scanned for template files as well as the location of the template cache. By default, the command uses the newly introduced Fluid file extension (see #1258) to identify Fluid templates. However, optionally an alternative file extension can be supplied as well. ``` bin/fluid warmup --path examples/Resources/ --cacheDirectory examples/cache/ bin/fluid warmup --path examples/Resources/ --path examples/ResourceOverrides/ --cacheDirectory examples/cache/ bin/fluid warmup --path examples/Resources/ --cacheDirectory examples/cache/ --extension html ``` In addition to the cache warmup, the command collects and outputs exceptions and deprecations that happened during parsing and compilation of the found template files. The underlying API, namely `TemplateFinder` for finding template files and `TemplateValidator`, which produces a validation report for each template, are marked as `@internal` for now. Resolves: #1103
s2b
added a commit
that referenced
this pull request
Nov 8, 2025
Previous Fluid versions already had a CLI command which could be used to warmup the cache for template files, e. g. during deployment. However, the previous implementation required a lot of additional context and mixed parsing/compilation and rendering state. The previous warmup implementation has already been deprecated with Fluid v4 and removed from Fluid v5 and is now replaced with a more straightforward implementation. The new CLI command needs to be supplied with a list of paths that should be scanned for template files as well as the location of the template cache. By default, the command uses the newly introduced Fluid file extension (see #1258) to identify Fluid templates. However, optionally an alternative file extension can be supplied as well. ``` bin/fluid warmup --cacheDirectory examples/cache/ --path examples/Resources/ bin/fluid warmup --cacheDirectory examples/cache/ --path examples/Resources/ --path examples/ResourceOverrides/ bin/fluid warmup --cacheDirectory examples/cache/ --path examples/Resources/ --extension html ``` In addition to the cache warmup, the command collects and outputs exceptions and deprecations that happened during parsing and compilation of the found template files. The underlying API, namely `TemplateFinder` for finding template files and `TemplateValidator`, which produces a validation report for each template, are marked as `@internal` for now. Resolves: #1103
s2b
added a commit
that referenced
this pull request
Nov 8, 2025
As a follow-up to #1258, all example templates are now using the new Fluid file extension. In all places where the file extension isn't specified explicitly, the fallback mechanism allows us to just rename the templates without any other changes. However, for `setTemplatePathAndFilename()`, an explicit path is given, which needs to be adjusted. Also, if the file extension is specified explicitly when rendering a partial, this also needs to be adjusted manually.
s2b
added a commit
that referenced
this pull request
Nov 8, 2025
As a follow-up to #1258, all example templates are now using the new Fluid file extension. In all places where the file extension isn't specified explicitly, the fallback mechanism allows us to just rename the templates without any other changes. However, for `setTemplatePathAndFilename()`, an explicit path is given, which needs to be adjusted. Also, if the file extension is specified explicitly when rendering a partial, this also needs to be adjusted manually.
s2b
added a commit
that referenced
this pull request
Nov 9, 2025
As a follow-up to #1258, all example templates are now using the new Fluid file extension. In all places where the file extension isn't specified explicitly, the fallback mechanism allows us to just rename the templates without any other changes. However, for `setTemplatePathAndFilename()`, an explicit path is given, which needs to be adjusted. Also, if the file extension is specified explicitly when rendering a partial, this also needs to be adjusted manually.
lolli42
approved these changes
Nov 10, 2025
s2b
added a commit
that referenced
this pull request
Nov 10, 2025
Previous Fluid versions already had a CLI command which could be used to warmup the cache for template files, e. g. during deployment. However, the previous implementation required a lot of additional context and mixed parsing/compilation and rendering state. The previous warmup implementation has already been deprecated with Fluid v4 and removed from Fluid v5 and is now replaced with a more straightforward implementation. The new CLI command needs to be supplied with a list of paths that should be scanned for template files as well as the location of the template cache. By default, the command uses the newly introduced Fluid file extension (see #1258) to identify Fluid templates. However, optionally an alternative file extension can be supplied as well. ``` bin/fluid warmup --cacheDirectory examples/cache/ --path examples/Resources/ bin/fluid warmup --cacheDirectory examples/cache/ --path examples/Resources/ --path examples/ResourceOverrides/ bin/fluid warmup --cacheDirectory examples/cache/ --path examples/Resources/ --extension html ``` In addition to the cache warmup, the command collects and outputs exceptions and deprecations that happened during parsing and compilation of the found template files. The underlying API, namely `TemplateFinder` for finding template files and `TemplateValidator`, which produces a validation report for each template, are marked as `@internal` for now. Resolves: #1103 [TASK] Use Fluid file extensions in examples As a follow-up to #1258, all example templates are now using the new Fluid file extension. In all places where the file extension isn't specified explicitly, the fallback mechanism allows us to just rename the templates without any other changes. However, for `setTemplatePathAndFilename()`, an explicit path is given, which needs to be adjusted. Also, if the file extension is specified explicitly when rendering a partial, this also needs to be adjusted manually.
Contributor
|
Post +1 (approve). |
s2b
added a commit
that referenced
this pull request
Nov 11, 2025
Previous Fluid versions already had a CLI command which could be used to warmup the cache for template files, e. g. during deployment. However, the previous implementation required a lot of additional context and mixed parsing/compilation and rendering state. The previous warmup implementation has already been deprecated with Fluid v4 and removed from Fluid v5 and is now replaced with a more straightforward implementation. The new CLI command needs to be supplied with a list of paths that should be scanned for template files as well as the location of the template cache. By default, the command uses the newly introduced Fluid file extension (see #1258) to identify Fluid templates. However, optionally an alternative file extension can be supplied as well. ``` bin/fluid warmup --cacheDirectory examples/cache/ --path examples/Resources/ bin/fluid warmup --cacheDirectory examples/cache/ --path examples/Resources/ --path examples/ResourceOverrides/ bin/fluid warmup --cacheDirectory examples/cache/ --path examples/Resources/ --extension html ``` In addition to the cache warmup, the command collects and outputs exceptions and deprecations that happened during parsing and compilation of the found template files. The underlying API, namely `TemplateFinder` for finding template files and `TemplateValidator`, which produces a validation report for each template, are marked as `@internal` for now. Resolves: #1103 [TASK] Use Fluid file extensions in examples As a follow-up to #1258, all example templates are now using the new Fluid file extension. In all places where the file extension isn't specified explicitly, the fallback mechanism allows us to just rename the templates without any other changes. However, for `setTemplatePathAndFilename()`, an explicit path is given, which needs to be adjusted. Also, if the file extension is specified explicitly when rendering a partial, this also needs to be adjusted manually.
s2b
added a commit
that referenced
this pull request
Nov 11, 2025
As a follow-up to #1258, all example templates are now using the new Fluid file extension. In all places where the file extension isn't specified explicitly, the fallback mechanism allows us to just rename the templates without any other changes. However, for `setTemplatePathAndFilename()`, an explicit path is given, which needs to be adjusted. Also, if the file extension is specified explicitly when rendering a partial, this also needs to be adjusted manually.
s2b
added a commit
that referenced
this pull request
Nov 11, 2025
As a follow-up to #1258, all example templates are now using the new Fluid file extension. In all places where the file extension isn't specified explicitly, the fallback mechanism allows us to just rename the templates without any other changes. However, for `setTemplatePathAndFilename()`, an explicit path is given, which needs to be adjusted. Also, if the file extension is specified explicitly when rendering a partial, this also needs to be adjusted manually.
s2b
added a commit
that referenced
this pull request
Nov 11, 2025
Previous Fluid versions already had a CLI command which could be used to warmup the cache for template files, e. g. during deployment. However, the previous implementation required a lot of additional context and mixed parsing/compilation and rendering state. The previous warmup implementation has already been deprecated with Fluid v4 and removed from Fluid v5 and is now replaced with a more straightforward implementation. The new CLI command needs to be supplied with a list of paths that should be scanned for template files as well as the location of the template cache. By default, the command uses the newly introduced Fluid file extension (see #1258) to identify Fluid templates. However, optionally an alternative file extension can be supplied as well. ``` bin/fluid warmup --cacheDirectory examples/cache/ --path examples/Resources/ bin/fluid warmup --cacheDirectory examples/cache/ --path examples/Resources/ --path examples/ResourceOverrides/ bin/fluid warmup --cacheDirectory examples/cache/ --path examples/Resources/ --extension html ``` In addition to the cache warmup, the command collects and outputs exceptions and deprecations that happened during parsing and compilation of the found template files. The underlying API, namely `TemplateFinder` for finding template files and `TemplateValidator`, which produces a validation report for each template, are marked as `@internal` for now. Resolves: #1103 [TASK] Use Fluid file extensions in examples As a follow-up to #1258, all example templates are now using the new Fluid file extension. In all places where the file extension isn't specified explicitly, the fallback mechanism allows us to just rename the templates without any other changes. However, for `setTemplatePathAndFilename()`, an explicit path is given, which needs to be adjusted. Also, if the file extension is specified explicitly when rendering a partial, this also needs to be adjusted manually.
s2b
added a commit
that referenced
this pull request
Nov 11, 2025
Previous Fluid versions already had a CLI command which could be used to warmup the cache for template files, e. g. during deployment. However, the previous implementation required a lot of additional context and mixed parsing/compilation and rendering state. The previous warmup implementation has already been deprecated with Fluid v4 and removed from Fluid v5 and is now replaced with a more straightforward implementation. The new CLI command needs to be supplied with a list of paths that should be scanned for template files as well as the location of the template cache. By default, the command uses the newly introduced Fluid file extension (see #1258) to identify Fluid templates. However, optionally an alternative file extension can be supplied as well. ``` bin/fluid warmup \ --cacheDirectory examples/cache/ \ --path examples/Resources/ bin/fluid warmup \ --cacheDirectory examples/cache/ \ --path examples/Resources/ \ --path examples/ResourceOverrides/ bin/fluid warmup \ --cacheDirectory examples/cache/ \ --path examples/Resources/ \ --extension html ``` In addition to the cache warmup, the command collects and outputs exceptions and deprecations that happened during parsing and compilation of the found template files. The underlying API, namely `TemplateFinder` for finding template files and `TemplateValidator`, which produces a validation report for each template, are marked as `@internal` for now. Resolves: #1103
s2b
added a commit
that referenced
this pull request
Nov 13, 2025
Previous Fluid versions already had a CLI command which could be used to warmup the cache for template files, e. g. during deployment. However, the previous implementation required a lot of additional context and mixed parsing/compilation and rendering state. The previous warmup implementation has already been deprecated with Fluid v4 and removed from Fluid v5 and is now replaced with a more straightforward implementation. The new CLI command needs to be supplied with a list of paths that should be scanned for template files as well as the location of the template cache. By default, the command uses the newly introduced Fluid file extension (see #1258) to identify Fluid templates. However, optionally an alternative file extension can be supplied as well. ``` bin/fluid warmup \ --cacheDirectory examples/cache/ \ --path examples/Resources/ bin/fluid warmup \ --cacheDirectory examples/cache/ \ --path examples/Resources/ \ --path examples/ResourceOverrides/ bin/fluid warmup \ --cacheDirectory examples/cache/ \ --path examples/Resources/ \ --extension html ``` In addition to the cache warmup, the command collects and outputs exceptions and deprecations that happened during parsing and compilation of the found template files. The underlying API, namely `TemplateFinder` for finding template files and `TemplateValidator`, which produces a validation report for each template, are marked as `@internal` for now. Resolves: #1103
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Historically, Fluid has always used generic file extensions for
template files, such as
.html,.txtor.xml. While thisprovides IDE integration out-of-the-box, it makes it hard to
distinguish files that are interpreted by Fluid and others that
are just text or html files.
This patch introduces an optional (!) new file extension for
Fluid template files that is added in addition to the generic
file extension:
.fluid.htmlfor html files,.fluid.txtfortext files, and so on. Template files are now detected in the
following order (first existing file wins):
If multiple template paths are defined, this chain is executed for
each path separately, before falling back to the next path. This
means that (in the TYPO3 context) an extension can ship
.htmlfiles and another extension can override these files with
.fluid.htmlfiles. It also works in reverse: The extension can ship
.fluid.html,which can be overwritten with
.htmlfiles. In short: The orderof paths is respected, regardless of the file extension. This will
make it possible to ship TYPO3 extensions compatible with v13/v14
(= ships
.html), while a sitepackage in a v14 project can alreadyuse
.fluid.htmlfiles. It also means that the core can rename alltemplates to
.fluid.htmlwithout breaking extensions that overwritecore templates (e. g. email templates) with
.htmlfiles.The order of file extensions has been discussed intensively, but in
the end we decided to land on
.fluid.*. Major reasons:Using
.fluidas primary file extension would remove codehighlighting completely until we can address each highlighter
individually. This would also include things like Gerrit, GitHub
or GitLab. Our time is not well spent to introduce a completely
new file extension when there's an easier alternative.
*.form.yamlthere is already precedent in the TYPO3 cosmos.Introducing this file extension not only helps users to
recognize Fluid templates, it also allows us to create better IDE
integrations in the future. Also, it enables us to scan a whole project
for Fluid templates, which makes cache warmup and linting tasks
config-free.