TYPO3-Documentation/TYPO3CMS-Book-ExtbaseFluid

Appendix C is missing

LeoniePhiline opened this issue · 4 comments

LeoniePhiline commented

Hi!

I am having a hard time finding all the options of calculation expressions and boolean expressions possible in fluid.

In the text at https://docs.typo3.org/m/typo3/book-extbasefluid/master/en-us/8-Fluid/7-using-boolean-conditions.html a text box is saying:

You find a complete list of all evaluating possibilities in appendix C in the section “Boolean expressions”.

I was unable to find an appendix C, unfortunately. Neither did I find any more or less up to date documentation about calculation and evaluation (e.g. a fluid variant of the in_array php function might exist as in operator, but no list seems to exist).

My use case would be something like {iterator.index} % 4 in [1, 2] to make a two-column chess-board layout. However, this bug report is not about the specific use case, but about the referenced but missing documentation. (I'll probably be better off with the fluid core CycleViewHelper for this implementation.)

sypets commented

Ok, about the specific "bug" in the documentation: First of all, I am sorry about that. You are right, the Appendix C is missing (or rather, has been renamed).

See

In Appendix C, Reference of Fluid, you can find a reference of all standard Fluid ViewHelpers and of the API which is needed to create your own ViewHelpers.

https://docs.typo3.org/m/typo3/book-extbasefluid/master/en-us/About.html#structure-of-this-book

So, "Appendic" C is currently not a Reference of Fluid, it is just a link to the Fluid ViewHelper reference.

Of course, you are not expected to know this, this is just something that was omitted when this book was created or restructured.

I will fix the reference to the "Appendix C" on that page. I will also try to track down the information that is missing.

About the documentation in general:

To be honest, the state of Extbase and Fluid documentation is currently not really in a "finished" state and we are having a hard time maintaining it.

There is the added difficulty, that the "Extbase / Fluid book" was a translation of a hardcover German book, that since then both Fluid and Extbase evolved and also the way extensions are developed, that Fluid is now its separate standalone project independently of TYPO3 CMS.

Because of the last thing, there are 2 things to document (TYPO3 Fluid itself, independently of TYPO3 CMS and Fluid in TYPO3 CMS).

The more general documentation of Fluid, you can find in the Fluid project:

Your question above is not really a TYPO3 question. It is a more general Fluid question, which should probably rather be documented there (and not in the Extbase / Fluid book).

What you could do to get an answer for your concrete question (I assume you know all this, I am just mentioning it in case there is something that might be helpful):

P.S. I would really appreciate it if you let me know if you found an answer to your question.

  • 👍1
LeoniePhiline commented

Hi Sybille!

No need to apologize. Also let me say that I very much appreciate the time and effort you took to write your response. Thank you.

My issue is indeed a more general lack of documentation:

While the interaction between extbase and fluid is more or less well documented, Fluid as a standalone product has been developed further quite a lot in the recent years without hardly any initiative to keep the documentation up to date or even more or less complete.

The documentation in the typo3fluid/fluid package / repository is quite minimal. (Maths are handled by noting: "{myNumber + 3} (and other mathematical operations) will for example output the sum of {myNumber} plus 3.")

For example, I find it generally tricky to determine (or to extrapolate a generic rule) when to wrap expressions in curly braces (like apparently necessary for the \TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\Expression\MathExpressionNode) and when to only wrap variable accessors but not operators (like in boolean operations, e.g. in the f:if viewhelper).

Note: \TYPO3Fluid\Fluid\ViewHelpers\IfViewHelper supports the modulo operator (%), and \TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\Expression\MathExpressionNode does so, too - but the syntax in both cases is inconsistent and I cannot find a clear pattern.

It is not clear to me why these are inconsistently present and how to apply braces and even escaped quotes when trying to express a mixture of an arithmetic operation and a boolean expression (e.g. {iterator.index} % 4 >= 2 vs. {iterator.index % 4} >= 2 vs. {iterator.index % 4 >= 2} or {iterator.index} % 4 in [1, 2], which is probably unsupported due to the lack of an in operator, but could probably be replaced by an InViewHelper).
Operator precedence and support for braces (/) in mathematical operations is unclear, too.

I guess this specific lack of documentation (or the difficulty to find it) is an Issue we should bring to the Fluid project. (@mbrodala ?)

However, since Fluid is almost exclusively used via TYPO3, it could indeed be a good idea to give clearer examples of Fluid usage also in the Fluid+Extbase / Fluid Standalone Views+TYPO3 documentation. After all, the documentation is meant to enable people to competently start templating their TYPO3 output.

One of several possible places would be https://docs.typo3.org/other/typo3/view-helper-reference/master/en-us/typo3fluid/fluid/latest/If.html - I believe there has been an Issue about this page already. (&& and || are not even mentioned on the IfViewHelper documentation page. And can we also use and and or? No information to be found, except by digging through the very minimalistically documented code. How about a logic like (iterator.index % 10 >= 3) && (iterator.index % 10 < 7)? Where do the curly braces go?)

However, expressions and compound operations are not just used in f:if situations, but also when directly outputting the result of maths operations and possibly the further evaluation of their results.
How do you use expressions together with the TernaryExpressionNode ({var ? thenvar : elsevar})? Do you need to assign variables first? Can you replace var / thenvar / elsevar by expressions? Do they need to be wrapped in escaped quotation marks, or is this simply unsupported?

The best fluid source of knowledge for me as of yet has been https://usetypo3.com/24-fluid-tips.html .

sypets commented

While the interaction between extbase and fluid is more or less well documented, Fluid as a standalone product has been developed further quite a lot in the recent years

Exactly! When Fluid was introduced in the core, this was used for developing with Extbase. Now, it has much more use cases without Extbase.

What we did though, was create a start page for Fluid in "TYPO3 Explained": This does reflect these newer applications for Fluid and is at least a good start: https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/ApiOverview/Fluid/Index.html

What is still required though is looking at the general structure as a whole. I think it would be a good idea, to shorten this manual to a basic tutorial and handle Extbase and Fluid separately in "TYPO3 Explained" or as separate guides (kind of depends on how extensive the stuff is, if it is not be too much, it should be put in "TYPO3 Explained").

These tasks need someone to do them, though. So if you would like to work on this new structure, you are welcome to do so. (I would propose to do a proof-of-concept first and get some feedback) You can ask for help in Slack #typo3-documentation. You might also find others that are willing to work with you on this.

For example, I find it generally tricky to determine (or to extrapolate a generic rule) when to wrap expressions in curly braces (like apparently necessary for the

Agreed. I also had problems figuring out what is quoted and what not and especially with the inline syntax.

However, since Fluid is almost exclusively used via TYPO3, it could indeed be a good idea to give clearer examples of Fluid usage also in the Fluid+Extbase / Fluid Standalone Views+TYPO3 documentation.

You are also right about that. I was reluctant to document general Fluid syntax in the TYPO3 CMS documentation. But then again, documentation is always not very well readable if you have, "ok here is your introduction and your code examples and for explanation of this see resource a and for that see recourse b etc."

I think if someone comes up with a good structure for Fluid in TYPO3 and has some syntax explanations as well - I think no one would complain.

I guess this specific lack of documentation (or the difficulty to find it) is an issue we should bring to the Fluid project. (@mbrodala ?)

Claus Due is the maintainer of Fluid.

To summarize: Most of these are known problems (though you did a good job of summarizing them and adding examples and I think no one has done it this way yet). The main problem is, no one stepping up to handle them.

What you can do in general (these are my personal tips, not necessarily official policy):

  1. Break your observations and proposals down into concrete suggestions. While, what you wrote above makes sense, it is not so easy to handle. See if you can find something that can be translated to a concrete proposal and change (e.g. as 1 issue or pull request handling one thing).
  2. Add one issue or pull request per suggestion only. Keep it short and to the point. Do not add all your proposals at once, start with one at a time.
  3. The more you do yourself, the more chances you have that your change will get finished and merged. If you are thinking, ok, I did 50% and now someone must do 50% more (and that would be about 2 hours), see if you can get to a state where you did 90% and someone just has to look at the results and merge it for example. (Sometimes before you make a change as pull requests, it is good to talk about it first and get some feedback, e.g. as an issue or on Slack. Must use your common sense for this. If it needs clarification, create an issue first, wait for feedback and then proceed.).
  4. Always try to follow up and finish your task. There are some things where you can't do much, e.g. you can't merge yourself, but always try to get it to a state where it is "merge-worthy".

Some concrete suggestions:

  1. Raise not TYPO3 related Fluid issues in the Fluid project: https://github.com/TYPO3/Fluid

One of several possible places would be https://docs.typo3.org/other/typo3/view-helper-reference/master/en-us/typo3fluid/fluid/latest/If.html - I believe there has been an Issue about this page already. (&& and || are not even mentioned on the IfViewHelper documentation page. And can we also use and and or? No information to be found, except by digging through the very minimalistically documented code. How about a logic like (iterator.index % 10 >= 3) && (iterator.index % 10 < 7)? Where do the curly braces go?)

The If-Viewhelper is documented in the Source code comments of the If-Viewhelper, specifically in https://github.com/TYPO3/Fluid/blob/master/src/ViewHelpers/IfViewHelper.php

It might help a lot if you created an issue with a suggestion or a pull request (e.g. by editing the file directly). In this case I would probably write an issue first to discuss if that should be documented directly in the If ViewHelper or in the Syntax documentation.

  1. I think what might help would be to create a hierarchical table of contents of Fluid content and the structure and what is missing, e.g.

This can be done in a number of different ways. It would be good to take into account what is already there or you might want to start from scratch ...

Some content already exists:

While this is again a big thing, I think it would be good to map out the general structure and then go from there.

linawolf commented

This book is very outdated. We currently rescue what is still correct and will write new tutorials. Therefore closing this issue