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

Traits

Provides extensions to this object to integrate it with standard config API methods.

A class that can be instantiated or replaced via DI

Constants

DEFAULT_THEME

Identifier for the default theme

PUBLIC_THEME

Identifier for the public theme

Config options

themes string

A list (highest priority first) of themes to use Only used when $theme_enabled is set to TRUE.

theme string

The used "theme", which usually consists of templates, images and stylesheets.

theme_enabled bool

Use the theme. Set to FALSE in order to disable themes, which can be useful for scenarios where theme overrides are temporarily undesired, such as an administrative interface separate from the website theme.

global_key string

Default prepended cache key for partial caching

source_file_comments bool

Properties

protected static array $current_themes

Overridden value of $themes config

bool $current_rewrite_hash_links

Overridden value of rewrite_hash_links config

bool|null $rewriteHashlinks

Instance variable to disable rewrite_hash_links (overrides global default) Leave null to use global state.

protected static array $topLevel

List of items being processed

protected array $templates

List of templates to select from

protected string $chosen

Absolute path to chosen template file

protected array $subTemplates

Templates to use when looking up 'Layout' or 'Content'

protected bool $includeRequirements
protected TemplateParser $parser
protected CacheInterface $partialCacheStore

Methods

public static 
config()

Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .....).

public
mixed
stat(string $name) deprecated

Get inherited config value

public
mixed
uninherited(string $name)

Gets the uninherited value for the given config option

public
$this
set_stat(string $name, mixed $value) deprecated

Update the config value for a given property

public static 
create(mixed ...$args)

An implementation of the factory method, allows you to create an instance of a class

public static 
singleton(string $class = null)

Creates a class instance by the "singleton" design pattern.

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

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_themes(array $themes = [])

Assign the list of active themes to apply.

public static 
add_themes(array $themes = [])

Add to the list of active themes to apply

public static 
array
get_themes()

Get the list of active themes

public static 
set_theme(string $theme) deprecated

No description

public static 
array
get_templates_by_class(string|object $classOrObject, string $suffix = '', string $baseClass = null)

Traverses the given the given class context looking for candidate template names which match each item in the class hierarchy. The resulting list of template candidates may or may not exist, but you can invoke {SSViewer::chooseTemplate} on any list to determine the best candidate based on the current themes.

public static 
topLevel()

Get the current item being processed

public
bool
getRewriteHashLinks()

Check if rewrite hash links are enabled on this instance

public
$this
setRewriteHashLinks(bool $rewrite)

Set if hash links are rewritten for this instance

public static 
bool
getRewriteHashLinksDefault()

Get default value for rewrite hash links for all modules

public static 
setRewriteHashLinksDefault(bool $rewrite)

Set default rewrite hash links

public
setTemplate(string|array $templates)

No description

public static 
string
chooseTemplate(array|string $templates)

Find the template to use for a given list

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|string $templates)

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

public
$this
public
string
exists()

No description

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

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(CacheInterface $cache)

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

public
CacheInterface
getPartialCacheStore()

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

public
includeRequirements(bool $incl = true)

Flag whether to include the requirements in this response.

protected
string
includeGeneratedTemplate(string $cacheFile, ViewableData $item, array $overlay, array $underlay, ViewableData $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, ViewableData $inheritedScope = null)

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

protected
array|null
getSubtemplateFor(string $subtemplate)

Get the appropriate template to use for the named sub-template, or null if none are appropriate

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

Execute the given template, passing it the given data.

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

Execute the evaluated string, passing it the given data.

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

Parse given template contents

public
array
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 
string
get_base_tag(string $contentGeneratedSoFar)

Return an appropriate base tag for the given template.

Details

static Config_ForClass config()

Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .....).

Return Value

Config_ForClass

mixed stat(string $name) deprecated

deprecated 5.0 Use ->config()->get() instead

Get inherited config value

Parameters

string $name

Return Value

mixed

mixed uninherited(string $name)

Gets the uninherited value for the given config option

Parameters

string $name

Return Value

mixed

$this set_stat(string $name, mixed $value) deprecated

deprecated 5.0 Use ->config()->set() instead

Update the config value for a given property

Parameters

string $name
mixed $value

Return Value

$this

static Injectable create(mixed ...$args)

An implementation of the factory method, allows you to create an instance of a class

This method will defer class substitution to the Injector API, which can be customised via the Config API to declare substitution classes.

This can be called in one of two ways - either calling via the class directly, or calling on Object and passing the class name as the first parameter. The following are equivalent: $list = DataList::create(SiteTree::class); $list = SiteTree::get();

Parameters

mixed ...$args

Return Value

Injectable

static Injectable singleton(string $class = null)

Creates a class instance by the "singleton" design pattern.

It will always return the same instance for this class, which can be used for performance reasons and as a simple way to access instance methods which don't rely on instance data (e.g. the custom SilverStripe static handling).

Parameters

string $class

Optional classname to create, if the called class should not be used

Return Value

Injectable

The singleton instance

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

No description

Parameters

string|array $templates

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

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_themes(array $themes = [])

Assign the list of active themes to apply.

If default themes should be included add $default as the last entry.

Parameters

array $themes

static add_themes(array $themes = [])

Add to the list of active themes to apply

Parameters

array $themes

static array get_themes()

Get the list of active themes

Return Value

array

static set_theme(string $theme) deprecated

deprecated 4.0.1 Use SSViewer::set_themes() instead

No description

Parameters

string $theme

The "base theme" name (without underscores).

static array get_templates_by_class(string|object $classOrObject, string $suffix = '', string $baseClass = null)

Traverses the given the given class context looking for candidate template names which match each item in the class hierarchy. The resulting list of template candidates may or may not exist, but you can invoke {SSViewer::chooseTemplate} on any list to determine the best candidate based on the current themes.

Parameters

string|object $classOrObject

Valid class name, or object

string $suffix
string $baseClass

Class to halt ancestry search at

Return Value

array

static ViewableData topLevel()

Get the current item being processed

Return Value

ViewableData

Check if rewrite hash links are enabled on this instance

Return Value

bool

Set if hash links are rewritten for this instance

Parameters

bool $rewrite

Return Value

$this

static bool getRewriteHashLinksDefault()

Get default value for rewrite hash links for all modules

Return Value

bool

static setRewriteHashLinksDefault(bool $rewrite)

Set default rewrite hash links

Parameters

bool $rewrite

setTemplate(string|array $templates)

No description

Parameters

string|array $templates

static string chooseTemplate(array|string $templates)

Find the template to use for a given list

Parameters

array|string $templates

Return Value

string

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|string $templates)

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

Parameters

array|string $templates

Return Value

bool

string exists()

No description

Return Value

string

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

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(CacheInterface $cache)

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

Parameters

CacheInterface $cache

CacheInterface getPartialCacheStore()

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

Return Value

CacheInterface

includeRequirements(bool $incl = true)

Flag whether to include the requirements in this response.

Parameters

bool $incl

protected string includeGeneratedTemplate(string $cacheFile, ViewableData $item, array $overlay, array $underlay, ViewableData $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

ViewableData $item

The item to use as the root scope for the template

array $overlay

Any variables to layer on top of the scope

array $underlay

Any variables to layer underneath the scope

ViewableData $inheritedScope

The current scope of a parent template including a sub-template

Return Value

string

The result of executing the template

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

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

It takes care of caching the output (via 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

ViewableData $inheritedScope

The current scope of a parent template including a sub-template

Return Value

DBHTMLText

Parsed template output.

protected array|null getSubtemplateFor(string $subtemplate)

Get the appropriate template to use for the named sub-template, or null if none are appropriate

Parameters

string $subtemplate

Sub-template to use

Return Value

array|null

static string execute_template(string $template, mixed $data, array $arguments = null, object $scope = null, bool $globalRequirements = false)

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

object $scope
bool $globalRequirements

Return Value

string

Evaluated result

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

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

bool $globalRequirements

Return Value

string

Evaluated result

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

Parse given template contents

Parameters

string $content

The template contents

string $template

The template file name

Return Value

string

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

Return Value

array

setTemplateFile(string $type, string $file)

No description

Parameters

string $type

"Layout" or "main"

string $file

Full system path to the template file

static string get_base_tag(string $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

string $contentGeneratedSoFar

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

Return Value

string