MarkerBasedTemplateService
Helper functionality for subparts and marker substitution ###MYMARKER###
Table of Contents
Properties
Methods
- __construct() : mixed
- fillInMarkerArray() : array<string|int, mixed>
- Adds elements to the input $markContentArray based on the values from the fields from $fieldList found in $row
- getSubpart() : string
- Returns the first subpart encapsulated in the marker, $marker (possibly present in $content as a HTML comment)
- substituteMarker() : string
- Substitutes a marker string in the input content (by a simple str_replace())
- substituteMarkerAndSubpartArrayRecursive() : string
- Replaces all markers and subparts in a template with the content provided in the structured array.
- substituteMarkerArray() : string
- Traverses the input $markContentArray array and for each key the marker by the same name (possibly wrapped and in upper case) will be substituted with the keys value in the array. This is very useful if you have a data-record to substitute in some content. In particular when you use the $wrap and $uppercase values to pre-process the markers. Eg. a key name like "myfield" could effectively be represented by the marker "###MYFIELD###" if the wrap value was "###|###" and the $uppercase boolean TRUE.
- substituteMarkerArrayCached() : string
- Multi substitution function with caching.
- substituteMarkerInObject() : mixed
- Substitute marker array in an array of values
- substituteSubpart() : string
- Substitutes a subpart in $content with the content of $subpartContent.
- substituteSubpartArray() : string
- Substitutes multiple subparts at once
Properties
$hashCache read-only
protected
FrontendInterface
$hashCache
$runtimeCache read-only
protected
FrontendInterface
$runtimeCache
Methods
__construct()
public
__construct(FrontendInterface $hashCache, FrontendInterface $runtimeCache) : mixed
Parameters
- $hashCache : FrontendInterface
- $runtimeCache : FrontendInterface
fillInMarkerArray()
Adds elements to the input $markContentArray based on the values from the fields from $fieldList found in $row
public
fillInMarkerArray(array<string|int, mixed> $markContentArray, array<string|int, mixed> $row[, string $fieldList = '' ][, bool $nl2br = true ][, string $prefix = 'FIELD_' ][, bool $htmlSpecialCharsValue = false ][, bool $respectXhtml = false ]) : array<string|int, mixed>
Parameters
- $markContentArray : array<string|int, mixed>
-
Array with key/values being marker-strings/substitution values.
- $row : array<string|int, mixed>
-
An array with keys found in the $fieldList (typically a record) which values should be moved to the $markContentArray
- $fieldList : string = ''
-
A list of fields from the $row array to add to the $markContentArray array. If empty all fields from $row will be added (unless they are integers)
- $nl2br : bool = true
-
If set, all values added to $markContentArray will be nl2br()'ed
- $prefix : string = 'FIELD_'
-
Prefix string to the fieldname before it is added as a key in the $markContentArray. Notice that the keys added to the $markContentArray always start and end with "###
- $htmlSpecialCharsValue : bool = false
-
If set, all values are passed through htmlspecialchars() - RECOMMENDED to avoid most obvious XSS and maintain XHTML compliance.
- $respectXhtml : bool = false
-
if set, and $nl2br is set, then the new lines are added with
instead of
Return values
array<string|int, mixed> —The modified $markContentArray
getSubpart()
Returns the first subpart encapsulated in the marker, $marker (possibly present in $content as a HTML comment)
public
getSubpart(string $content, string $marker) : string
Parameters
- $content : string
-
Content with subpart wrapped in fx. "###CONTENT_PART###" inside.
- $marker : string
-
Marker string, eg. "###CONTENT_PART###
Return values
stringsubstituteMarker()
Substitutes a marker string in the input content (by a simple str_replace())
public
substituteMarker(string $content, string $marker, mixed $markContent) : string
Parameters
- $content : string
-
The content stream, typically HTML template content.
- $marker : string
-
The marker string, typically on the form "###[the marker string]###
- $markContent : mixed
-
The content to insert instead of the marker string found.
Tags
Return values
string —The processed HTML content string.
substituteMarkerAndSubpartArrayRecursive()
Replaces all markers and subparts in a template with the content provided in the structured array.
public
substituteMarkerAndSubpartArrayRecursive(string $content, array<string|int, mixed> $markersAndSubparts[, string $wrap = '' ][, bool $uppercase = false ][, bool $deleteUnused = false ]) : string
The array is built like the template with its markers and subparts. Keys represent the marker name and the values the content. If the value is not an array the key will be treated as a single marker. If the value is an array the key will be treated as a subpart marker. Repeated subpart contents are of course elements in the array, so every subpart value must contain an array with its markers.
$markersAndSubparts = array (
'###SINGLEMARKER1###' => 'value 1',
'###SUBPARTMARKER1###' => array(
0 => array(
'###SINGLEMARKER2###' => 'value 2',
),
1 => array(
'###SINGLEMARKER2###' => 'value 3',
)
),
'###SUBPARTMARKER2###' => array(
),
)
Subparts can be nested, so below the 'SINGLEMARKER2' it is possible to have another subpart marker with an array as the value, which in its turn contains the elements of the sub-subparts. Empty arrays for Subparts will cause the subtemplate to be cleared.
Parameters
- $content : string
-
The content stream, typically HTML template content.
- $markersAndSubparts : array<string|int, mixed>
-
The array of single markers and subpart contents.
- $wrap : string = ''
-
A wrap value - [part1] | [part2] - for the markers before substitution.
- $uppercase : bool = false
-
If set, all marker string substitution is done with upper-case markers.
- $deleteUnused : bool = false
-
If set, all unused single markers are deleted.
Return values
string —The processed output stream
substituteMarkerArray()
Traverses the input $markContentArray array and for each key the marker by the same name (possibly wrapped and in upper case) will be substituted with the keys value in the array. This is very useful if you have a data-record to substitute in some content. In particular when you use the $wrap and $uppercase values to pre-process the markers. Eg. a key name like "myfield" could effectively be represented by the marker "###MYFIELD###" if the wrap value was "###|###" and the $uppercase boolean TRUE.
public
substituteMarkerArray(string $content, array<string|int, mixed> $markContentArray[, string $wrap = '' ][, bool $uppercase = false ][, bool $deleteUnused = false ]) : string
Parameters
- $content : string
-
The content stream, typically HTML template content.
- $markContentArray : array<string|int, mixed>
-
The array of key/value pairs being marker/content values used in the substitution. For each element in this array the function will substitute a marker in the content stream with the content.
- $wrap : string = ''
-
A wrap value - [part 1] | [part 2] - for the markers before substitution
- $uppercase : bool = false
-
If set, all marker string substitution is done with upper-case markers.
- $deleteUnused : bool = false
-
If set, all unused marker are deleted.
Tags
Return values
string —The processed output stream
substituteMarkerArrayCached()
Multi substitution function with caching.
public
substituteMarkerArrayCached(string $content[, array<string|int, mixed> $markContentArray = null ][, array<string|int, mixed> $subpartContentArray = null ][, array<string|int, mixed> $wrappedSubpartContentArray = null ]) : string
This function should be a one-stop substitution function for working with HTML-template. It does not substitute by str_replace but by splitting. This secures that the value inserted does not themselves contain markers or subparts.
Note that the "caching" won't cache the content of the substitution, but only the splitting of the template in various parts. So if you want only one cache-entry per template, make sure you always pass the exact same set of marker/subpart keys. Else you will be flooding the user's cache table.
This function takes three kinds of substitutions in one: $markContentArray is a regular marker-array where the 'keys' are substituted in $content with their values
$subpartContentArray works exactly like markContentArray only is whole subparts substituted and not only a single marker.
$wrappedSubpartContentArray is an array of arrays with 0/1 keys where the subparts pointed to by the main key is wrapped with the 0/1 value alternating.
Parameters
- $content : string
-
The content stream, typically HTML template content.
- $markContentArray : array<string|int, mixed> = null
-
Regular marker-array where the 'keys' are substituted in $content with their values
- $subpartContentArray : array<string|int, mixed> = null
-
Exactly like markContentArray only is whole subparts substituted and not only a single marker.
- $wrappedSubpartContentArray : array<string|int, mixed> = null
-
An array of arrays with 0/1 keys where the subparts pointed to by the main key is wrapped with the 0/1 value alternating.
Tags
Return values
string —The output content stream
substituteMarkerInObject()
Substitute marker array in an array of values
public
substituteMarkerInObject(mixed &$tree, array<string|int, mixed> $markContentArray) : mixed
Parameters
- $tree : mixed
-
If string, then it just calls substituteMarkerArray. If array(and even multi-dim) then for each key/value pair the marker array will be substituted (by calling this function recursively)
- $markContentArray : array<string|int, mixed>
-
The array of key/value pairs being marker/content values used in the substitution. For each element in this array the function will substitute a marker in the content string/array values.
Tags
Return values
mixed —The processed input variable.
substituteSubpart()
Substitutes a subpart in $content with the content of $subpartContent.
public
substituteSubpart(string $content, string $marker, string|array<string|int, mixed> $subpartContent[, bool $recursive = true ][, bool $keepMarker = false ]) : string
Parameters
- $content : string
-
Content with subpart wrapped in fx. "###CONTENT_PART###" inside.
- $marker : string
-
Marker string, eg. "###CONTENT_PART###
- $subpartContent : string|array<string|int, mixed>
-
If $subpartContent happens to be an array, it's [0] and [1] elements are wrapped around the content of the subpart (fetched by getSubpart())
- $recursive : bool = true
-
If $recursive is set, the function calls itself with the content set to the remaining part of the content after the second marker. This means that proceeding subparts are ALSO substituted!
- $keepMarker : bool = false
-
If set, the marker around the subpart is not removed, but kept in the output
Return values
string —Processed input content
substituteSubpartArray()
Substitutes multiple subparts at once
public
substituteSubpartArray(string $content, array<string|int, mixed> $subpartsContent) : string
Parameters
- $content : string
-
The content stream, typically HTML template content.
- $subpartsContent : array<string|int, mixed>
-
The array of key/value pairs being subpart/content values used in the substitution. For each element in this array the function will substitute a subpart in the content stream with the content.
Return values
string —The processed HTML content string.