From 82c5e5fbf306b823ee5fe57d9362f013f31bd126 Mon Sep 17 00:00:00 2001 From: Simon Praetorius Date: Wed, 20 Nov 2024 11:25:24 +0100 Subject: [PATCH] [DOCS] Documentation overhaul --- .github/workflows/build.yml | 3 +- Documentation/Development/Decisions.rst | 146 ---------- Documentation/Development/Expressions.rst | 2 +- Documentation/Development/Index.rst | 33 ++- Documentation/Index.rst | 39 ++- Documentation/Installation/Index.rst | 19 +- .../Index.rst} | 6 +- Documentation/Internals/Index.rst | 13 + .../{Usage => Internals}/RunningExamples.rst | 0 Documentation/Introduction/Index.rst | 25 ++ Documentation/Syntax/Comments.rst | 33 +++ Documentation/Syntax/ConditionsBooleans.rst | 89 ++++++ Documentation/Syntax/Escaping.rst | 141 +++++++++ Documentation/Syntax/Expressions.rst | 89 ++++++ Documentation/Syntax/Index.rst | 70 +++++ Documentation/Syntax/Variables.rst | 56 ++++ Documentation/Syntax/ViewHelpers.rst | 167 +++++++++++ Documentation/Usage/GettingStarted.rst | 21 ++ Documentation/Usage/Index.rst | 43 ++- Documentation/Usage/Syntax.rst | 252 ---------------- Documentation/Usage/Variables.rst | 94 ++++++ Documentation/Usage/ViewHelpers.rst | 271 +++++++++++------- Documentation/ViewHelpers/Index.rst | 6 +- Documentation/ViewHelpers/SchemaFiles.rst | 41 +++ 24 files changed, 1116 insertions(+), 543 deletions(-) delete mode 100644 Documentation/Development/Decisions.rst rename Documentation/{Development/Implementation.rst => Integrating/Index.rst} (99%) create mode 100644 Documentation/Internals/Index.rst rename Documentation/{Usage => Internals}/RunningExamples.rst (100%) create mode 100644 Documentation/Introduction/Index.rst create mode 100644 Documentation/Syntax/Comments.rst create mode 100644 Documentation/Syntax/ConditionsBooleans.rst create mode 100644 Documentation/Syntax/Escaping.rst create mode 100644 Documentation/Syntax/Expressions.rst create mode 100644 Documentation/Syntax/Index.rst create mode 100644 Documentation/Syntax/Variables.rst create mode 100644 Documentation/Syntax/ViewHelpers.rst create mode 100644 Documentation/Usage/GettingStarted.rst delete mode 100644 Documentation/Usage/Syntax.rst create mode 100644 Documentation/Usage/Variables.rst create mode 100644 Documentation/ViewHelpers/SchemaFiles.rst diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 7bea25ae5..b3101c671 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -48,5 +48,6 @@ jobs: - name: Documentation integrity run: | - FLUID_DOCUMENTATION_OUTPUT_DIR=Documentation/ViewHelpers vendor/bin/fluidDocumentation generate vendor/t3docs/fluid-documentation-generator/config/fluidStandalone/* + FLUID_DOCUMENTATION_OUTPUT_DIR=DocumentationTemp vendor/bin/fluidDocumentation generate vendor/t3docs/fluid-documentation-generator/config/fluidStandalone/* + cp -r DocumentationTemp/Fluid DocumentationTemp/Fluid.json Documentation/ViewHelpers/ && rm -r DocumentationTemp git add Documentation/*; git status; git status | grep -q "nothing to commit, working tree clean" diff --git a/Documentation/Development/Decisions.rst b/Documentation/Development/Decisions.rst deleted file mode 100644 index 2bc002c10..000000000 --- a/Documentation/Development/Decisions.rst +++ /dev/null @@ -1,146 +0,0 @@ -.. include:: /Includes.rst.txt - -.. _decisions: - -====================================== -Decoupling decisions and compatibility -====================================== - -This is a historical elaboration on some details when this project has been -decoupled form `TYPO3.Flow` and made a standalone library. Isn't of too much -help nowadays anymore, but can be helpful for some insight on why things -materialized as is. - -In order to decouple this package from `TYPO3.Flow` a few necessary but -implication-filled decisions had to be made. - -No more dependency injection -============================ - -It is simply gone and will not be implemented again in any shape or form. The DI -concept from `TYPO3.Flow` does not apply on a wider scale and it is every bit as -possible to achieve the same results through the constructor methods. While DI -is a nice concept for usability, it is better to sacrifice it for more universal -class support. - -No more widget support -====================== - -It is also gone and will not be implemented again. However: because of the -nature of Fluid and ViewHelpers, **recreating the implementation that behaves -like Widgets but does so in the context of the framework in which it gets used** -is the correct way to achieve this behavior. - -As an added benefit, all translated labels and a **lot** of functional tests and -fixtures can and have been removed. - -ViewHelpers can't use render method arguments -============================================= - -Although still technically feasible to implement, a decision was made to -sacrifice the support for `render()` method arguments in ViewHelpers -(as opposed to using `registerArgument` inside `initializeArguments`). -The following reasons are given: - -1. Render method type hinting beyond strict types is impossible without - analysing phpdoc comments which implies Reflection as well as a dependency - on the `TYPO3.Flow` annotation parser. -2. Performance and testability is exactly the same. -3. A single method to register arguments now exists and `ArgumentDefinition` can - be reduced in complexity. -4. Having only one method to check in every instance means better performance - overall. - -Overriding these capabilites is possible and implies a custom -`ViewHelperInvoker` returned from a custom `ViewHelperResolver`. - -The View consumes TemplatePaths -=============================== - -Rather than allow the View class to be aware of the Request via the -ControllerContext, both the Request and ControllerContext concepts have been -completely removed. A new strategy has taken the place of these: the -TemplatePaths. - -In order to instantiate a View instance, a special TemplatePaths instance must -now be passed as first argument. This TemplatePaths instance *is then -responsible for all the resolving and retrieval of template files*. This means -that replacing the TemplatePaths instance that gets used will allow another -implementation to **effectively change how Fluid resolves template files**. - -This also means that the View itself no longer has any file resolving -capabilities. Instead, it relies on the provided instance to resolve every file -and template source. For usability, there are dedicated methods to set template -path and filename as well as layout path and filename. - -**Because of this the path treatments are now completely decoupled and no longer -uses expression expansions to create arrays of expected paths**. Instead, each -path is iterated and the epected filename checked and returned if found. In -order to potentially re-implement this decoupled package into `TYPO3.Flow` as -well as `TYPO3.CMS` this means that these paths can then be generated by the MVC -and simply passed along to the View - or, íf more complex behavior is required, -a custom TemplatePaths implementation can be created. - -As a side effect of this, **the View no longer supports any options**. Where -before a user was able to pass paths, filenames and other settings as `options` -on the View, such behavior is no longer required due to the use of -TemplatePaths. However, such behavior can be restored by subclassing the -TemplateView and adding `options` support which simply delegates to -TemplatePaths to change root paths etc. - -Obviously your paths can no longer use any custom syntax or markers for -replacement such as `EXT:...` paths or `@marker` patterns. To use such -expressions make sure you convert the paths *before* you pass them to the View; -e.g. do so inside your custom TemplatePaths or before you pass the paths to the -built-in TemplatePaths object. - -Deprecated code has been evicted -================================ - -This includes all and every support for the legacy path name conventions - only -arrays of paths are now accepted except when specifying the full template- or -layout path and filename on the View. - -Note about injecting functionality -================================== - -It is possible to restore almost all of the removed features by creating custom -implementations of the following classes: - -* https://github.com/TYPO3Fluid/Fluid/blob/main/src/View/TemplatePaths.php to - change how template files are resolved. -* https://github.com/TYPO3Fluid/Fluid/blob/main/src/Core/ViewHelper/ViewHelperResolver.php - to change how each ViewHelper is resolved, how its arguments are retrieved, - which namespaces are available and expected class names of ViewHelpers. - -When combined in a package that implements `TYPO3.Fluid` in a framework, these -two classes together make it possible to change all the behaviors that were -changed to make `TYPO3.Fluid` more portable. The solutions are, in order: - -1. Dependency injection in ViewHelpers can be restored by overriding the - `createViewHelperClassInstance` method of the ViewHelperResolver - implementation. The View itself can of course also be loaded by an object - manager that does injection. -2. Widgets can be reintroduced as a framework-specific feature by making the - ViewHelperResolver return the desired class names when the TemplateParser - tries to load the ViewHelpers that were removed. This includes all of the - other ViewHelpers which were sacrificed for portability because they had too - strong dependencies on the framework; for example the `f:form` helpers known - from TYPO3 CMS and Flow. -3. The arguments of each ViewHelper can be adjusted - or the class itself can be - replaced. This allows the framework to replace those ViewHelpers that have - been "dumbed down" (for example the debug ViewHelper which in CMS or Flow - would use the DebuggerUtility to display variables but in this standalone - version uses a plain `var_dump`). -4. The TemplatePaths implementation can be replaced by one that supports the - necessary folder structures and path treatments, for example allowing the - `EXT:....` syntax in paths and making it possible to "bubble sub package" or - whatever special feature the template file resolving should support. -5. Deprecated code and support for legacy class names can be introduced by - overriding the ViewHelperResolver. The aliases can be defined any way - desired - as long as the ViewHelperResolver is aware of them and will return - the **new** class as replacement. -6. The way the ViewHelpers are themselves executed can be overridden via a - custom ViewHelperInvoker returned from the custom ViewHelperResolver. - Overriding this part allows, among other things, restoring the `render()` - method argument support. diff --git a/Documentation/Development/Expressions.rst b/Documentation/Development/Expressions.rst index d65820be1..6fd3d9eba 100644 --- a/Documentation/Development/Expressions.rst +++ b/Documentation/Development/Expressions.rst @@ -8,7 +8,7 @@ Creating ExpressionNodes To understand what an ExpressionNode is and which cases can be solved by implementing custom ones, first read the -:doc:`chapter about implementing Fluid `. Once you +:ref:`chapter about integrating Fluid `. Once you grasp what an ExpressionNode is and how it works, a very brief example is all you need. diff --git a/Documentation/Development/Index.rst b/Documentation/Development/Index.rst index 72d56a5d8..9671594f4 100644 --- a/Documentation/Development/Index.rst +++ b/Documentation/Development/Index.rst @@ -2,15 +2,34 @@ .. _development: -=========== -Development -=========== +=============== +Extending Fluid +=============== -.. toctree:: - :maxdepth: 2 +.. card-grid:: + :columns: 1 + :columns-md: 2 + :gap: 4 + :class: pb-4 + :card-height: 100 + + .. card:: ViewHelpers + + Learn how to extend Fluid by creating custom ViewHelpers + + .. card-footer:: :ref:`Learn about ViewHelpers ` + :button-style: btn btn-secondary stretched-link + + .. card:: ExpressionNodes + + Learn how to extend Fluid by creating custom expression syntax + + .. card-footer:: :ref:`Learn about ExpressionNodes ` + :button-style: btn btn-secondary stretched-link + +.. toctree:: + :hidden: :titlesonly: - Implementation CreatingViewHelpers Expressions - Decisions diff --git a/Documentation/Index.rst b/Documentation/Index.rst index 9e54f74aa..1dc3a008a 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -14,8 +14,7 @@ Fluid Rendering Engine en :Author: - Claus Due, Sebastian Kurfürst, Karsten Dambekalns, Robert Lemke & Fluid - contributors + Fluid contributors :License: This document is published under the @@ -38,15 +37,33 @@ If using Fluid in combination with TYPO3 CMS, a look at the documentation of **Table of Contents:** -.. toctree:: - :maxdepth: 2 - :titlesonly: - - Installation/Index - Usage/Index - Development/Index - ViewHelpers/Index - Changelog/Index +.. toctree:: + :caption: About Fluid + :maxdepth: 1 + :titlesonly: + + Introduction/Index + Installation/Index + Usage/Index + Syntax/Index + +.. toctree:: + :caption: ViewHelper Reference + :maxdepth: 1 + :titlesonly: + + ViewHelpers/Fluid/Index + ViewHelpers/SchemaFiles + +.. toctree:: + :caption: Appendix + :maxdepth: 1 + :titlesonly: + + Development/Index + Integrating/Index + Internals/Index + Changelog/Index .. Meta Menu diff --git a/Documentation/Installation/Index.rst b/Documentation/Installation/Index.rst index d0db92ac8..f35be11de 100644 --- a/Documentation/Installation/Index.rst +++ b/Documentation/Installation/Index.rst @@ -6,18 +6,13 @@ Installation ============ -1. Include as composer dependency using +Fluid is distributed through composer. It can be added to your project by +executing the following command: - .. code-block:: bash +.. code-block:: bash - composer require typo3fluid/fluid + composer require typo3fluid/fluid -2. Run - - .. code-block:: bash - - composer install - - to generate the vendor class autoloader. - -3. The classes from `TYPO3.Fluid` can now be used in your composer project. +To get started with Fluid, take a look at the +:ref:`Fluid Syntax ` as well as the +:ref:`Getting Started Guide `. diff --git a/Documentation/Development/Implementation.rst b/Documentation/Integrating/Index.rst similarity index 99% rename from Documentation/Development/Implementation.rst rename to Documentation/Integrating/Index.rst index 16605790f..7fc353857 100644 --- a/Documentation/Development/Implementation.rst +++ b/Documentation/Integrating/Index.rst @@ -2,9 +2,9 @@ .. _implementations: -================== -Implementing Fluid -================== +================= +Integrating Fluid +================= `TYPO3.Fluid` provides a standard implementation which works great on simple MVC frameworks and as standalone rendering engine. However, the standard diff --git a/Documentation/Internals/Index.rst b/Documentation/Internals/Index.rst new file mode 100644 index 000000000..7738ad6f6 --- /dev/null +++ b/Documentation/Internals/Index.rst @@ -0,0 +1,13 @@ +.. include:: /Includes.rst.txt + +.. _fluid-internals: + +=============== +Fluid Internals +=============== + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + * diff --git a/Documentation/Usage/RunningExamples.rst b/Documentation/Internals/RunningExamples.rst similarity index 100% rename from Documentation/Usage/RunningExamples.rst rename to Documentation/Internals/RunningExamples.rst diff --git a/Documentation/Introduction/Index.rst b/Documentation/Introduction/Index.rst new file mode 100644 index 000000000..019133b9b --- /dev/null +++ b/Documentation/Introduction/Index.rst @@ -0,0 +1,25 @@ +.. include:: /Includes.rst.txt + +.. _introduction: + +============ +Introduction +============ + +Fluid is a PHP-based templating engine for web projects. In contrast to other +templating engines, it uses an XML-based syntax in its templates, which allows +template authors to apply their existing HTML knowledge in Fluid templates. + +Fluid originated in the TYPO3 and Neos ecosystem before it was extracted +from these projects into a separate PHP package. While its main usage nowadays +is within TYPO3 projects, it can also be used as an independent templating +language in PHP projects. + +In Fluid, all dynamic output is escaped by default, which makes the templating +engine secure by default. This prevents common XSS (Cross Site Scripting) +mistakes that can easily happen in HTML templates. + +Fluid comes with a range of so-called ViewHelpers that allow various formatting +and output modification directly in the template. Custom logic can be added +by providing custom ViewHelper implementations through a straightforward +PHP API. diff --git a/Documentation/Syntax/Comments.rst b/Documentation/Syntax/Comments.rst new file mode 100644 index 000000000..be80d171b --- /dev/null +++ b/Documentation/Syntax/Comments.rst @@ -0,0 +1,33 @@ +.. include:: /Includes.rst.txt + +:navigation-title: Comments + +.. _fluid-syntax-comments: + +====================== +Fluid Syntax: Comments +====================== + +If you want to completely skip parts of your template, you can make use of +the :ref:` ViewHelper `. + +.. versionchanged:: Fluid 4.0 + The content of the :ref:` ViewHelper ` is removed + before parsing. It is no longer necessary to combine it with CDATA tags + to disable parsing. + +.. code-block:: xml + + + This will be ignored by the Fluid parser and will not appear in + the source code of the rendered template + + +You can also use the :ref:` ViewHelper ` to temporarily comment +out invalid Fluid syntax while debugging: + +.. code-block:: xml + + + + diff --git a/Documentation/Syntax/ConditionsBooleans.rst b/Documentation/Syntax/ConditionsBooleans.rst new file mode 100644 index 000000000..d68fe7e94 --- /dev/null +++ b/Documentation/Syntax/ConditionsBooleans.rst @@ -0,0 +1,89 @@ +.. include:: /Includes.rst.txt + +:navigation-title: Conditions & Booleans + +.. _fluid-syntax-conditions: + +=================================== +Fluid Syntax: Conditions & Booleans +=================================== + +.. _fluid-syntax-boolean-conditions: + +Boolean conditions +================== + +Boolean conditions are expressions that evaluate to true or false. + +Boolean conditions can be used as ViewHelper arguments, whenever the datatype +`boolean` is given, e.g. in the `condition` argument of the +:ref:` ViewHelper `. + +1. The expression can be a variable which is evaluated as follows: + + * number: evaluates to `true`, if is not `0`. + * array: evaluates to `true` if it contains at least one element + +2. The expression can be a statement consisting of: `term1 operator term2`, for + example `{variable} > 3` + + * The operator can be one of `>`, `>=`, `<`, `<=`, + `==`, `===`, `!=`, `!==` or `%`, + +3. The previous expressions can be combined with `||` (or) or `&&` (and). + + +Examples: + +.. code-block:: xml + + + ... + + + + + ... + + + ... + + + + + ... + + + +Example using the inline notation: + +.. code-block:: xml + +
+ ... +
+ +Boolean literals +================ + +.. versionadded:: Fluid 4.0 + The boolean literals `{true}` and `{false}` have been introduced. + +You can use the boolean literals `{true}` and `{false}` in ViewHelper calls. This works +both in tag and inline syntax: + +.. code-block:: xml + + + + {f:render(section: 'MySection', optional: true)} + +If a ViewHelper argument is defined as `boolean`, it is also possible to provide +values of different types, which will then be converted to boolean implicitly: + +.. code-block:: xml + + + +This can be used to remain compatible to Fluid 2, which didn't support boolean literals +in all cases. diff --git a/Documentation/Syntax/Escaping.rst b/Documentation/Syntax/Escaping.rst new file mode 100644 index 000000000..7a7035dda --- /dev/null +++ b/Documentation/Syntax/Escaping.rst @@ -0,0 +1,141 @@ +.. include:: /Includes.rst.txt + +:navigation-title: Escaping + +.. _fluid-syntax-escaping: + +====================== +Fluid Syntax: Escaping +====================== + +Escaping behavior in inline syntax +================================== + +At a certain nesting level, `'` needs to be escaped with a backslash: + +.. code-block:: xml + + + + + +While escaping cannot be avoided in all cases, alternatives should always be +preferred to improve the readability of templates. Depending on the use cases, there +are different approaches to achieve this. + + +Passing variables to inline ViewHelpers +--------------------------------------- + +If only a variable is passed as a ViewHelper argument, the single quotes and curly braces +can be omitted: + +.. code-block:: xml + + {f:format.case(mode: 'upper', value: myVariable)} + + +Using ViewHelper chaining if possible +------------------------------------- + +A lot of ViewHelpers that perform changes on a single value also accept that value as +child value. This allows a much cleaner syntax if you combine multiple ViewHelpers for +one value: + +.. code-block:: xml + + {myVariable -> f:format.case(mode: 'upper') -> f:format.trim()} + + +Workarounds for syntax collision with JS and CSS +================================================ + +While it is generally advisable to avoid inline JavaScript and CSS code within +Fluid templates, sometimes it might be unavoidable. This might lead to collisions +between Fluid's inline or variable syntax and the curly braces used in JavaScript +and CSS. + +Currently, there is no clean way to solve this due to limitations of Fluid's parser. +This would need a bigger rewrite, which is not yet feasible due to other more pressing +issues. However, there are workarounds that might be applicable in your use case. + +f:format.json ViewHelper +------------------------ + +If your goal is to create JSON in your template, you can create an object in Fluid +and then use the :ref:` ViewHelper ` +to generate valid JSON: + +.. code-block:: xml + +
+ + +This can also be used directly in JavaScript code: + +.. code-block:: xml + +