class SSViewer implements Flushable

Parses a template file with an *.ss file extension.

In addition to a full template in the templates/ folder, a template in templates/Content or templates/Layout will be rendered into $Content and $Layout, respectively.

A single template can be parsed by multiple nested {@link SSViewer} instances through $Layout/$Content placeholders, as well as <% include MyTemplateFile %> template commands.

Themes

See http://doc.silverstripe.org/themes and http://doc.silverstripe.org/themes:developing

Caching

Compiled templates are cached via {@link SS_Cache}, usually on the filesystem. If you put ?flush=1 on your URL, it will force the template to be recompiled.

Properties

$rewriteHashlinks
protected boolean $includeRequirements
protected TemplateParser $parser
static protected $topLevel
protected Zend_Cache_Core $partialCacheStore

Methods

static 
set_source_file_comments(boolean $val) deprecated

Set whether HTML comments indicating the source .SS file used to render this page should be included in the output. This is enabled by default

static boolean
get_source_file_comments() deprecated

No description

static 
flush()

Triggered early in the request when someone requests a flush.

static SSViewer
fromString(string $content, bool|void $cacheTemplate = null)

Create a template from a string instead of a .ss file

static 
set_theme(string $theme) deprecated

No description

static string
current_theme() deprecated

No description

static string
get_theme_folder()

Returns the path to the theme folder

static array
get_themes(string $path = null, bool $subthemes = false)

Returns an array of theme names present in a directory.

static string
current_custom_theme() deprecated

No description

static array
get_templates_by_class($className, $suffix = '', $baseClass = null)

Traverses the given the given class context looking for templates with the relevant name.

__construct($templateList, TemplateParser $parser = null)

No description

setParser(TemplateParser $parser)

Set the template parser that will be used in template generation

getParser()

Returns the parser that is set for template generation

static boolean
hasTemplate(array $templates)

Returns true if at least one of the listed templates exists.

static 
setOption(string $optionName, mixed $optionVal) deprecated

Set a global rendering option.

static mixed
getOption(string $optionName) deprecated

No description

static 
topLevel()

No description

static Zend_Cache_Core
defaultPartialCacheStore()

No description

exists()

No description

static string
getTemplateFileByType(string $identifier, string $type)

No description

static 
flush_template_cache(bool $force = false)

Clears all parsed template files in the cache folder.

static 
flush_cacheblock_cache(bool $force = false)

Clears all partial cache blocks.

setPartialCacheStore(Zend_Cache_Core $cache)

Set the cache object to use when storing / retrieving partial cache blocks.

Zend_Cache_Core
getPartialCacheStore()

Get the cache object to use when storing / retrieving partial cache blocks.

includeRequirements(boolean $incl = true)

Flag whether to include the requirements in this response.

string
includeGeneratedTemplate(string $cacheFile, SS_Object $item, array|null $overlay, array|null $underlay, SS_Object $inheritedScope = null)

An internal utility function to set up variables in preparation for including a compiled template, then do the include

process(ViewableData $item, array|null $arguments = null, SS_Object $inheritedScope = null)

The process() method handles the "meat" of the template processing.

static string
execute_template($template, $data, $arguments = null, $scope = null)

Execute the given template, passing it the given data.

static string
execute_string(string $content, mixed $data, array $arguments = null)

Execute the evaluated string, passing it the given data.

parseTemplateContent($content, $template = "")

No description

templates()

Returns the filenames of the template that will be rendered. It is a map that may contain 'Content' & 'Layout', and will have to contain 'main'

setTemplateFile(string $type, string $file)

No description

static 
get_base_tag($contentGeneratedSoFar)

Return an appropriate base tag for the given template.

Details

at line 705
static set_source_file_comments(boolean $val) deprecated

deprecated 4.0 Use the "SSViewer.source_file_comments" config setting instead

Set whether HTML comments indicating the source .SS file used to render this page should be included in the output. This is enabled by default

Parameters

boolean $val

at line 714
static boolean get_source_file_comments() deprecated

deprecated 4.0 Use the "SSViewer.source_file_comments" config setting instead

Return Value

boolean

at line 768
static flush()

Triggered early in the request when someone requests a flush.

at line 780
static SSViewer fromString(string $content, bool|void $cacheTemplate = null)

Create a template from a string instead of a .ss file

Parameters

string $content The template content
bool|void $cacheTemplate Whether or not to cache the template from string

Return Value

SSViewer

at line 792
static set_theme(string $theme) deprecated

deprecated 4.0 Use the "SSViewer.theme" config setting instead

Parameters

string $theme The "base theme" name (without underscores).

at line 801
static string current_theme() deprecated

deprecated 4.0 Use the "SSViewer.theme" config setting instead

Return Value

string

at line 811
static string get_theme_folder()

Returns the path to the theme folder

Return Value

string

at line 823
static array get_themes(string $path = null, bool $subthemes = false)

Returns an array of theme names present in a directory.

Parameters

string $path
bool $subthemes Include subthemes (default false).

Return Value

array

at line 844
static string current_custom_theme() deprecated

deprecated since version 4.0

Return Value

string

at line 858
static array get_templates_by_class($className, $suffix = '', $baseClass = null)

Traverses the given the given class context looking for templates with the relevant name.

Parameters

$className string - valid class name
$suffix string
$baseClass string

Return Value

array

at line 890
__construct($templateList, TemplateParser $parser = null)

Parameters

$templateList
TemplateParser $parser

at line 926
setParser(TemplateParser $parser)

Set the template parser that will be used in template generation

Parameters

TemplateParser $parser

at line 935
TemplateParser getParser()

Returns the parser that is set for template generation

Return Value

TemplateParser

at line 950
static boolean hasTemplate(array $templates)

Returns true if at least one of the listed templates exists.

Parameters

array $templates

Return Value

boolean

at line 980
static setOption(string $optionName, mixed $optionVal) deprecated

at line 995
static mixed getOption(string $optionName) deprecated

deprecated 4.0 Use the "SSViewer.rewrite_hash_links" config setting instead

Parameters

string $optionName

Return Value

mixed

at line 1013
static topLevel()

at line 1022
static protected Zend_Cache_Core defaultPartialCacheStore()

Return Value

Zend_Cache_Core

at line 1037
exists()

at line 1047
static string getTemplateFileByType(string $identifier, string $type)

Parameters

string $identifier A template name without '.ss' extension or path
string $type The template type, either "main", "Includes" or "Layout"

Return Value

string Full system path to a template file

at line 1073
static flush_template_cache(bool $force = false)

Clears all parsed template files in the cache folder.

Can only be called once per request (there may be multiple SSViewer instances).

Parameters

bool $force Set this to true to force a re-flush. If left to false, flushing may only be performed once a request.

at line 1091
static flush_cacheblock_cache(bool $force = false)

Clears all partial cache blocks.

Can only be called once per request (there may be multiple SSViewer instances).

Parameters

bool $force Set this to true to force a re-flush. If left to false, flushing may only be performed once a request.

at line 1121
setPartialCacheStore(Zend_Cache_Core $cache)

Set the cache object to use when storing / retrieving partial cache blocks.

Parameters

Zend_Cache_Core $cache

at line 1130
Zend_Cache_Core getPartialCacheStore()

Get the cache object to use when storing / retrieving partial cache blocks.

Return Value

Zend_Cache_Core

at line 1139
includeRequirements(boolean $incl = true)

Flag whether to include the requirements in this response.

Parameters

boolean $incl

at line 1157
protected string includeGeneratedTemplate(string $cacheFile,
SS_Object $item, array|null $overlay, array|null $underlay, SS_Object $inheritedScope = null)

An internal utility function to set up variables in preparation for including a compiled template, then do the include

Effectively this is the common code that both SSViewer#process and SSViewer_FromString#process call

Parameters

string $cacheFile
  • The path to the file that contains the template compiled to PHP
SS_Object $item
  • The item to use as the root scope for the template
array|null $overlay
  • Any variables to layer on top of the scope
array|null $underlay
  • Any variables to layer underneath the scope
SS_Object $inheritedScope
  • the current scope of a parent template including a sub-template

Return Value

string
  • The result of executing the template

at line 1194
HTMLText process(ViewableData $item, array|null $arguments = null, SS_Object $inheritedScope = null)

The process() method handles the "meat" of the template processing.

It takes care of caching the output (via {@link SS_Cache}), as well as replacing the special "$Content" and "$Layout" placeholders with their respective subtemplates.

The method injects extra HTML in the header via {@link Requirements::includeInHTML()}.

Note: You can call this method indirectly by {@link ViewableData->renderWith()}.

Parameters

ViewableData $item
array|null $arguments
  • arguments to an included template
SS_Object $inheritedScope
  • the current scope of a parent template including a sub-template

Return Value

HTMLText Parsed template output.

at line 1269
static string execute_template($template, $data, $arguments = null, $scope = null)

Execute the given template, passing it the given data.

Used by the <% include %> template tag to process templates.

Parameters

$template
$data
$arguments
$scope

Return Value

string Evaluated result

at line 1286
static string execute_string(string $content, mixed $data, array $arguments = null)

Execute the evaluated string, passing it the given data.

Used by partial caching to evaluate custom cache keys expressed using template expressions

Parameters

string $content Input string
mixed $data Data context
array $arguments Additional arguments

Return Value

string Evaluated result

at line 1293
parseTemplateContent($content, $template = "")

Parameters

$content
$template

at line 1305
templates()

Returns the filenames of the template that will be rendered. It is a map that may contain 'Content' & 'Layout', and will have to contain 'main'

at line 1313
setTemplateFile(string $type, string $file)

Parameters

string $type "Layout" or "main"
string $file Full system path to the template file

at line 1324
static get_base_tag($contentGeneratedSoFar)

Return an appropriate base tag for the given template.

It will be closed on an XHTML document, and unclosed on an HTML document.

Parameters

$contentGeneratedSoFar The content of the template generated so far; it should contain the DOCTYPE declaration.