Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

Blueprints/TypoScriptConditions

From TYPO3Wiki
Jump to: navigation, search

<- Back to blueprints overview

Blueprint: JavaScript/PHP like syntax for TypoScript Conditions and the stdWrap if

Proposal Specify a syntax of conditions, that match with the standards of JavaScript and PHP.
Owner/Starter Elmar Hinz
Participants/Members -
Status Draft, Discussion, Voting Phase, Accepted, Declined, Withdrawn
Current Progress Unknown, Started, Good Progress, Bad Progress, Stalled, Review Needed
Topic for Gerrit ts-conditions

Target Versions/Milestones

  • Started during TYPO3 CMS 8.2 development

Preface

Currently conditions are accused to be evil, to blow up the cache. This issue can be solved. This blueprint is about the time when the issue is solved.

Goals / Motivation

The conditions syntax of TypoScript lacks in several points. While the promise is, to be easier to learn than the conditions of a a full-blown programming like PHP or JavaScript, the promise is not really kept. The syntax is as at least as difficult to learn than the syntax of JavaScript or PHP.

As many TypoScript developers already have basic skills in JavaScript or work in a team having those skills at hand, it is an additional burden to learn a new syntax only to handle conditions of TypoScript.

Another flaw is, that the TypoScript developer has to learn another new syntax to handle the stdWrap if of TypoScript. Below the line he has to learn two new languages instead of being able to apply a knowledge that is likely there and can be reused elsewhere, if to be learned from scratch.

Finally both syntaxes – the conditions and the stdWrap if – are limited because both are not scientifically developed as languages.

The goal is to introduce a syntax, that is basically the intersection of JavaScript and PHP, so that it is easy for every web developer to get started with TypoScript conditions and to overcome some limitations like the the missing not operator or the logical structuring by parentheses.

The same syntax can be applied as well with conditions as with the stdWrap if.

Concept

1. Deprecate [GLOBAL]

2. Write a parser to evaluate the logical expression.

( $_POST.tx_myext_pi1.showUid && ( hour() > 8 || dayOfWeek() != 1 ) )

3. Introduce the full [IF] [ELSEIF] [ELSE] [END] structure set into the TypoScript parser.

    [IF] (logical expression):

    ...

    [ELSEIF] (logical expression):

    ...

    [ELSE]

    ...

    [END]

4. Extend TypoScript stdWrap if, to call the expression parser.

page.10.if.expression = ( logical expression )

Implementation Details

Deprecation of [GLOBAL]

If TypoScript is not inside a condition, it is in the global scope. There is no reason to have a [GLOBAL] instruction. The historical function of this instruction was, to reset the nesting of braces to zero at the beginning of a template, if there was an issue in the previous template. Similar for mulitline comments and values. This can be solved differently as the beginning of a template is easy to detect.

Extended bracket syntax

The TypoScript parser detects conditions by the leading bracket. There are no conflicts to introduce the structuring elements [IF], [ELSEIF], [ELSE], [END].

stdWrap if

Extending the stdWrap if by a new property to set the condition is trivial.

Multiline

The logical expressions become most comfortable, if they are allowed to span multiple lines. As they are enclosed by parentheses this is possible, but it requires a clean escaping of closing parentheses within the expression, if they are used within strings or regular expression. The syntax follows PHP and JavaScript.

Logical expression parser

Already the parsing of the current conditions is delegated to the ConditionMatcher class. The new syntax is to delegate in the same way to a differnt class.

Both styles can be mixed, as the matcher class just returns false or true. An error shall be thrown, if both styles are mixed within one line.

The class that evaluates the new type of condition, is responsible to cover the full set of operators:

  • paraentheses: ()
  • not: !
  • and: &&
  • or: ||
  • equal: ==
  • not equal: !=
  • greater than: >
  • less than: <
  • greater than or equal to: >=
  • less than or equal to: <=
  • matches regular expression: ~=

Apart from this operators an "in list" operator (or function) may be useful, as often the question is, if an integer is contained in a given list

loginUser() in (3, 5, 7)

Apart from operators other syntax elements need to be supported. To name the minimum.

  • double quoted strings
  • regular expressions or single quoted strings to put them into
  • dot syntax to access nested variables of the environment
  • inbuilt functions
  • custom conditions

Array access by dot syntax

The array access takes up the do philosophy of TypoScript and Fluid.

$_POST.tx_myext_pi1.showUid

The $ sign must not interfere with constants of TypoScript, wich are additionally written in curly braces: {$my.constant}.

Public properties of classes shall be accessed in the same way. If getter functions replace them, the syntax stays the same.For simple getter functions the parentheses may be omitted. The parser tries different options to fetch the value.

Shortcuts to array access

A set of shortcuts marked by colons has been introduced to access public properties of common classes:

TSFE:page|layout
TSFE:fe_user|user|username
IENV:REMOTE_ADDR

This becomes:

$TSFE.page.layout
$TSFE.fe_user.user.username
$IENV.REMOTE_ADDR

Inbuilt functions

A set of functions like hour(), dayofweek(), usergroup() is to be supported by the expression parser. These set is defined by the existing set of functions of the TypoScript conditions. Often they simply can return a single value that can be compared by the above operators.

Parameters

Few functions need parameters, meaning parameters need to be supported.

PIDinRootline(34, 36)

This condition matches, if the page viewed is or is a subpage to page 34 or page 36.

Custom conditions

Since TYPO3 7.0 custom conditions are supported. Custom conditions need to be supported again, using PHP namespaces and the dot syntax.

YourVendor\YourPackage\YourClass.yourCondition(param, param)

Custom conditions functions have to be registered, to prohibit the execution of risky code. They are only allowed to return booleans.

Discussion of Syntax Alternatives

If/Elseif Statement

[IF] (loginUser() < 10):

[IF: (loginUser() < 10)]

[IF: loginUser() < 10]

[IF (loginUser() < 10)]

[IF loginUser() < 10]

The last one is most similar to the accustomed style and there is few interpunction for simple expressions.

Multi lines

The drawback to include everything into squared brackets may be, that they occur on different lines for multiline expressions:

[IF loginUser() < 10
     && hour() > 8
     && hour() < 22
]

They don't form a squared figure any more, but they are still well to match visually.

[IF] (loginUser() < 10
         && hour() > 8
         && hour() < 22
      )

Uppercase vs. Lowercase

  [IF: loginUser() < 10]
   ...
  [END]

  [if loginUser() < 10]
   ...
  [end]

Uppercase:

  • The community is used to it.
  • Visually it is more easy to separate conditions and TS.

Lowercase:

  • More fluent to read with the logical expression.

getText()

Default access by function:

  [IF: getText('TSFE:fe_user|user|username') == 'Peter' ]

Syntactical sugar alternatives:

  [IF: {TSFE:fe_user|user|username} == 'Peter' ]
  [IF: `TSFE:fe_user|user|username` == 'Peter' ]

Curly braces:

  • same syntax as in dataWrap
  • significant for getText

Backticks:

  • PHP style to include an executable string.
  • From the perspective of PHP curly braces are a strange delimiter.

Risks

???

Issues and Reviews

None.

Dependencies upon other Blueprints

None.

External Links for Clarification of Technologies

PHP:

JavaScript: