class SSViewer implements Flushable (View source)

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 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 SS_Cache, usually on the filesystem. If you put ?flush=1 on your URL, it will force the template to be recompiled.

Properties

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

Methods

public static 
set_source_file_comments(bool $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

public static 
bool
get_source_file_comments() deprecated

No description

public static 
flush()

Triggered early in the request when someone requests a flush.

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

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

public static 
set_theme(string $theme) deprecated

No description

public static 
string
current_theme() deprecated

No description

public static 
string
get_theme_folder()

Returns the path to the theme folder

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

Returns an array of theme names present in a directory.

public static 
string
current_custom_theme() deprecated

No description

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

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

public
__construct(string|array $templateList, TemplateParser $parser = null)

No description

public
setParser(TemplateParser $parser)

Set the template parser that will be used in template generation

public
getParser()

Returns the parser that is set for template generation

public static 
bool
hasTemplate(array $templates)

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

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

Set a global rendering option.

public static 
mixed
getOption($optionName) deprecated

No description

public static 
topLevel()

No description

protected static 
Zend_Cache_Core
defaultPartialCacheStore()

No description

public
exists()

No description

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

No description

public static 
flush_template_cache(bool $force = false)

Clears all parsed template files in the cache folder.

public static 
flush_cacheblock_cache(bool $force = false)

Clears all partial cache blocks.

public
setPartialCacheStore(Zend_Cache_Core $cache)

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

public
Zend_Cache_Core
getPartialCacheStore()

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

public
includeRequirements($incl = true)

Flag whether to include the requirements in this response.

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

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

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

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

Execute the given template, passing it the given data.

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

Execute the evaluated string, passing it the given data.

public
parseTemplateContent($content, $template = "")

No description

public
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'

public
setTemplateFile(string $type, string $file)

No description

public static 
get_base_tag($contentGeneratedSoFar)

Return an appropriate base tag for the given template.

Details

static set_source_file_comments(bool $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

bool $val

static bool get_source_file_comments() deprecated

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

No description

Return Value

bool

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

Parameters

string $content

The template content

bool|void $cacheTemplate

Whether or not to cache the template from string

Return Value

SSViewer

static set_theme(string $theme) deprecated

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

No description

Parameters

string $theme

The "base theme" name (without underscores).

static string current_theme() deprecated

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

No description

Return Value

string

static string get_theme_folder()

Returns the path to the theme folder

Return Value

string

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

static string current_custom_theme() deprecated

deprecated since version 4.0

No description

Return Value

string

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

__construct(string|array $templateList, TemplateParser $parser = null)

No description

Parameters

string|array $templateList

If passed as a string with .ss extension, used as the "main" template. If passed as an array, it can be used for template inheritance (first found template "wins"). Usually the array values are PHP class names, which directly correlate to template names.

array('MySpecificPage', 'MyPage', 'Page')
TemplateParser $parser

setParser(TemplateParser $parser)

Set the template parser that will be used in template generation

Parameters

TemplateParser $parser

TemplateParser getParser()

Returns the parser that is set for template generation

Return Value

TemplateParser

static bool hasTemplate(array $templates)

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

Parameters

array $templates

Return Value

bool

static mixed getOption($optionName) deprecated

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

No description

Parameters

$optionName

Return Value

mixed

static topLevel()

No description

static protected Zend_Cache_Core defaultPartialCacheStore()

No description

Return Value

Zend_Cache_Core

exists()

No description

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

No description

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

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.

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.

setPartialCacheStore(Zend_Cache_Core $cache)

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

Parameters

Zend_Cache_Core $cache

Zend_Cache_Core getPartialCacheStore()

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

Return Value

Zend_Cache_Core

includeRequirements($incl = true)

Flag whether to include the requirements in this response.

Parameters

$incl

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

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 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 Requirements::includeInHTML().

Note: You can call this method indirectly by 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.

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

Execute the given template, passing it the given data.

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

Parameters

string $template

Template name

mixed $data

Data context

array $arguments

Additional arguments

$scope

Return Value

string

Evaluated result

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

parseTemplateContent($content, $template = "")

No description

Parameters

$content
$template

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

Parameters

string $type

"Layout" or "main"

string $file

Full system path to the template file

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.