SSViewer

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.

Config options

source_file_comments boolean
theme string
theme_enabled boolean
rewrite_hash_links boolean

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

TemplateParser
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

dontRewriteHashlinks()

Call this to disable rewriting of links. This is useful in Ajax applications.

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.

HTMLText
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

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

Set a global rendering option.

The following options are available: - rewriteHashlinks: If true (the default), will be rewritten to contain the current URL. This lets it play nicely with our tag. - If rewriteHashlinks = 'php' then, a piece of PHP script will be inserted before the hash links: "". This is useful if you're generating a page that will be saved to a .php file and may be accessed from different URLs.

Parameters

string $optionName
mixed $optionVal

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()

Call this to disable rewriting of links. This is useful in Ajax applications.

It returns the SSViewer objects, so that you can call new SSViewer("X")->dontRewriteHashlinks()->process();

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 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.