SSTemplateParser
class SSTemplateParser extends Parser implements TemplateParser
This is the parser for the SilverStripe template language. It gets called on a string and uses a php-peg parser to match that string against the language structure, building up the PHP code to execute that structure as it parses
The $result array that is built up as part of the parsing (see thirdparty/php-peg/README.md for more on how parsers build results) has one special member, 'php', which contains the php equivalent of that part of the template tree.
Some match rules generate alternate php, or other variations, so check the per-match documentation too.
Terms used:
Marked: A string or lookup in the template that has been explictly marked as such - lookups by prepending with "$" (like $Foo.Bar), strings by wrapping with single or double quotes ('Foo' or "Foo")
Bare: The opposite of marked. An argument that has to has it's type inferred by usage and 2.4 defaults.
Example of using a bare argument for a loop block: <% loop Foo %>
Block: One of two SS template structures. The special characters "<%" and "%>" are used to wrap the opening and (required or forbidden depending on which block exactly) closing block marks.
Open Block: An SS template block that doesn't wrap any content or have a closing end tag (in fact, a closing end tag is forbidden)
Closed Block: An SS template block that wraps content, and requires a counterpart <% end_blockname %> tag
Angle Bracket: angle brackets "<" and ">" are used to eat whitespace between template elements N: eats white space including newlines (using in legacy _t support)
Methods
Allow the injection of new closed & open block callables
Override the function that constructs the result arrays to also prepare a 'php' item in the array
Set the closed blocks that the template parser should use
Set the open blocks that the template parser should use
Add a closed block callable to allow <% name %><% end_name %> syntax
Add a closed block callable to allow <% name %> syntax
No description
No description
No description
No description
No description
No description
Values are bare words in templates, but strings in PHP. We rely on PHP's type conversion to back-convert strings to numbers when needed.
No description
No description
No description
No description
No description
The basic generated PHP of LookupStep and LastLookupStep is the same, except that LookupStep calls 'obj' to get the next ViewableData in the sequence, and LastLookupStep calls different methods (XML_val, hasValue, obj) depending on the context the lookup is used in.
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
If we get a bare value, we don't know enough to determine exactly what php would be the translation, because we don't know if the position of use indicates a lookup or a string argument.
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
As mentioned in the parser comment, block handling is kept fairly generic for extensibility. The match rule builds up two important elements in the match result array: 'ArgumentCount' - how many arguments were passed in the opening tag 'Arguments' an array of the Argument match rule result arrays
No description
No description
This is an example of a block handler function. This one handles the loop tag.
The closed block handler for with blocks
No description
No description
No description
No description
This is an open block handler, for the <% debug %> utility tag
This is an open block handler, for the <% base_tag %> tag
This is an open block handler, for the <% current_page %> tag
No description
No description
No description
No description
No description
No description
No description
No description
No description
No description
The TopTemplate also includes the opening stanza to start off the template
No description
We convert text
Compiles some passed template source code into the php code that will execute as per the template source.
Compiles some file that contains template source code, and returns the php code that will execute as per that source
Details
at line 107
__construct(array $closedBlocks = array(), array $openBlocks = array())
Allow the injection of new closed & open block callables
at line 115
construct($matchrule, $name, $arguments = null)
Override the function that constructs the result arrays to also prepare a 'php' item in the array
at line 129
setClosedBlocks(array $closedBlocks)
Set the closed blocks that the template parser should use
This method will delete any existing closed blocks, please use addClosedBlock if you don't want to overwrite
at line 144
setOpenBlocks(array $openBlocks)
Set the open blocks that the template parser should use
This method will delete any existing open blocks, please use addOpenBlock if you don't want to overwrite
at line 157
addClosedBlock(string $name, callable $callable)
Add a closed block callable to allow <% name %><% end_name %> syntax
at line 168
addOpenBlock(string $name, callable $callable)
Add a closed block callable to allow <% name %> syntax
at line 202
match_Template($stack = array())
at line 450
Template_STR($res, $sub)
at line 456
match_Word($stack = array())
at line 468
match_Number($stack = array())
at line 480
match_Value($stack = array())
at line 492
match_CallArguments($stack = array())
at line 545
CallArguments_Argument($res, $sub)
Values are bare words in templates, but strings in PHP. We rely on PHP's type conversion to back-convert strings to numbers when needed.
at line 554
match_Call($stack = array())
at line 612
match_LookupStep($stack = array())
at line 645
match_LastLookupStep($stack = array())
at line 659
match_Lookup($stack = array())
at line 731
Lookup__construct($res)
at line 741
Lookup_AddLookupStep($res, $sub, $method)
The basic generated PHP of LookupStep and LastLookupStep is the same, except that LookupStep calls 'obj' to get the next ViewableData in the sequence, and LastLookupStep calls different methods (XML_val, hasValue, obj) depending on the context the lookup is used in.
at line 754
Lookup_LookupStep($res, $sub)
at line 758
Lookup_LastLookupStep($res, $sub)
at line 766
match_Translate($stack = array())
at line 875
match_InjectionVariables($stack = array())
at line 918
match_Entity($stack = array())
at line 930
Translate__construct($res)
at line 934
Translate_Entity($res, $sub)
at line 938
Translate_Default($res, $sub)
at line 942
Translate_Context($res, $sub)
at line 946
Translate_InjectionVariables($res, $sub)
at line 950
Translate__finalise($res)
at line 954
InjectionVariables__construct($res)
at line 958
InjectionVariables_InjectionName($res, $sub)
at line 962
InjectionVariables_Argument($res, $sub)
at line 966
InjectionVariables__finalise($res)
at line 974
match_SimpleInjection($stack = array())
at line 999
match_BracketInjection($stack = array())
at line 1026
match_Injection($stack = array())
at line 1057
Injection_STR($res, $sub)
at line 1063
match_DollarMarkedLookup($stack = array())
at line 1076
DollarMarkedLookup_STR($res, $sub)
at line 1082
match_QuotedString($stack = array())
at line 1118
match_FreeString($stack = array())
at line 1134
match_Argument($stack = array())
at line 1245
Argument_DollarMarkedLookup($res, $sub)
If we get a bare value, we don't know enough to determine exactly what php would be the translation, because we don't know if the position of use indicates a lookup or a string argument.
Instead, we record 'ArgumentMode' as a member of this matches results node, which can be: - lookup if this argument was unambiguously a lookup (marked as such) - string is this argument was unambiguously a string (marked as such, or impossible to parse as lookup) - default if this argument needs to be handled as per 2.4
In the case of 'default', there is no php member of the results node, but instead 'lookup_php', which should be used by the parent if the context indicates a lookup, and 'string_php' which should be used if the context indicates a string
at line 1250
Argument_QuotedString($res, $sub)
at line 1255
Argument_Lookup($res, $sub)
at line 1267
Argument_FreeString($res, $sub)
at line 1274
match_ComparisonOperator($stack = array())
at line 1385
match_Comparison($stack = array())
at line 1412
Comparison_Argument($res, $sub)
at line 1422
Comparison_ComparisonOperator($res, $sub)
at line 1428
match_PresenceCheck($stack = array())
at line 1469
PresenceCheck_Not($res, $sub)
at line 1473
PresenceCheck_Argument($res, $sub)
at line 1487
match_IfArgumentPortion($stack = array())
at line 1518
IfArgumentPortion_STR($res, $sub)
at line 1524
match_BooleanOperator($stack = array())
at line 1552
match_IfArgument($stack = array())
at line 1601
IfArgument_IfArgumentPortion($res, $sub)
at line 1605
IfArgument_BooleanOperator($res, $sub)
at line 1611
match_IfPart($stack = array())
at line 1654
match_ElseIfPart($stack = array())
at line 1697
match_ElsePart($stack = array())
at line 1732
match_If($stack = array())
at line 1782
If_IfPart($res, $sub)
at line 1789
If_ElseIfPart($res, $sub)
at line 1796
If_ElsePart($res, $sub)
at line 1805
match_Require($stack = array())
at line 1866
Require_Call($res, $sub)
at line 1879
match_CacheBlockArgument($stack = array())
at line 1976
CacheBlockArgument_DollarMarkedLookup($res, $sub)
at line 1980
CacheBlockArgument_QuotedString($res, $sub)
at line 1984
CacheBlockArgument_Lookup($res, $sub)
at line 1990
match_CacheBlockArguments($stack = array())
at line 2034
CacheBlockArguments_CacheBlockArgument($res, $sub)
at line 2044
match_CacheBlockTemplate($stack = array())
at line 2262
match_UncachedBlock($stack = array())
at line 2413
UncachedBlock_Template($res, $sub)
at line 2420
match_CacheRestrictedTemplate($stack = array())
at line 2668
CacheRestrictedTemplate_CacheBlock($res, $sub)
at line 2673
CacheRestrictedTemplate_UncachedBlock($res, $sub)
at line 2684
match_CacheBlock($stack = array())
at line 2918
CacheBlock__construct($res)
at line 2922
CacheBlock_CacheBlockArguments($res, $sub)
at line 2926
CacheBlock_Condition($res, $sub)
at line 2930
CacheBlock_CacheBlock($res, $sub)
at line 2934
CacheBlock_UncachedBlock($res, $sub)
at line 2938
CacheBlock_CacheBlockTemplate($res, $sub)
at line 2972
match_OldTPart($stack = array())
at line 3066
match_N($stack = array())
at line 3077
OldTPart__construct($res)
at line 3081
OldTPart_QuotedString($res, $sub)
at line 3091
OldTPart_CallArguments($res, $sub)
at line 3095
OldTPart__finalise($res)
at line 3101
match_OldTTag($stack = array())
at line 3124
OldTTag_OldTPart($res, $sub)
at line 3130
match_OldSprintfTag($stack = array())
at line 3179
OldSprintfTag__construct($res)
at line 3183
OldSprintfTag_OldTPart($res, $sub)
at line 3187
OldSprintfTag_CallArguments($res, $sub)
at line 3193
match_OldI18NTag($stack = array())
at line 3224
OldI18NTag_STR($res, $sub)
at line 3230
match_NamedArgument($stack = array())
at line 3260
NamedArgument_Name($res, $sub)
at line 3264
NamedArgument_Value($res, $sub)
at line 3282
match_Include($stack = array())
at line 3357
Include__construct($res)
at line 3361
Include_Template($res, $sub)
at line 3365
Include_NamedArgument($res, $sub)
at line 3369
Include__finalise($res)
at line 3386
match_BlockArguments($stack = array())
at line 3435
match_NotBlockTag($stack = array())
at line 3590
match_ClosedBlock($stack = array())
at line 3698
ClosedBlock__construct($res)
As mentioned in the parser comment, block handling is kept fairly generic for extensibility. The match rule builds up two important elements in the match result array: 'ArgumentCount' - how many arguments were passed in the opening tag 'Arguments' an array of the Argument match rule result arrays
Once a block has successfully been matched against, it will then look for the actual handler, which should be on this class (either defined or extended on) as ClosedBlock_Handler_Name(&$res), where Name is the tag name, first letter captialized (i.e Control, Loop, With, etc).
This function will be called with the match rule result array as it's first argument. It should return the php result of this block as it's return value, or throw an error if incorrect arguments were passed.
at line 3702
ClosedBlock_BlockArguments($res, $sub)
at line 3713
ClosedBlock__finalise($res)
at line 3730
ClosedBlock_Handle_Loop($res)
This is an example of a block handler function. This one handles the loop tag.
at line 3758
ClosedBlock_Handle_Control($res)
deprecated
deprecated
The deprecated closed block handler for control blocks
at line 3766
ClosedBlock_Handle_With($res)
The closed block handler for with blocks
at line 3786
match_OpenBlock($stack = array())
at line 3848
OpenBlock__construct($res)
at line 3852
OpenBlock_BlockArguments($res, $sub)
at line 3863
OpenBlock__finalise($res)
at line 3880
OpenBlock_Handle_Debug($res)
This is an open block handler, for the <% debug %> utility tag
at line 3898
OpenBlock_Handle_Base_tag($res)
This is an open block handler, for the <% base_tag %> tag
at line 3906
OpenBlock_Handle_Current_page($res)
This is an open block handler, for the <% current_page %> tag
at line 3913
match_MismatchedEndBlock($stack = array())
at line 3940
MismatchedEndBlock__finalise($res)
at line 3948
match_MalformedOpenTag($stack = array())
at line 4026
MalformedOpenTag__finalise($res)
at line 4034
match_MalformedCloseTag($stack = array())
at line 4091
MalformedCloseTag__finalise($res)
at line 4099
match_MalformedBlock($stack = array())
at line 4133
match_Comment($stack = array())
at line 4184
Comment__construct($res)
at line 4191
match_TopTemplate($stack = array())
at line 4461
TopTemplate__construct($res)
The TopTemplate also includes the opening stanza to start off the template
at line 4474
match_Text($stack = array())
at line 4675
Text__finalise($res)
We convert text
at line 4713
mixed|string
compileString($string, string $templateName = "", bool $includeDebuggingComments = false, bool $topTemplate = true)
Compiles some passed template source code into the php code that will execute as per the template source.
at line 4787
mixed|string
compileFile($template)
Compiles some file that contains template source code, and returns the php code that will execute as per that source