Class StringTemplate

Provides an interface for registering and inserting content into simple logic-less string templates.

Used by several helpers to provide simple flexible templates for generating HTML and other content.

Namespace: Cake\View

Properties summary

  • $_compactAttributes protected
    array

    List of attributes that can be made compact.

  • $_compiled protected
    array

    Contains the list of compiled templates

  • $_config protected
    array

    Runtime config

  • $_configInitialized protected
    bool

    Whether the config property has already been configured with defaults

  • $_configStack protected
    array

    A stack of template sets that have been stashed temporarily.

  • $_defaultConfig protected
    array

    The default templates this instance holds.

Method Summary

  • __construct() public

    Constructor.

  • _compileTemplates() protected

    Compile templates into a more efficient printf() compatible format.

  • _configDelete() protected

    Deletes a single config key.

  • _configRead() protected

    Reads a config key.

  • _configWrite() protected

    Writes a config key.

  • _formatAttribute() protected

    Formats an individual attribute, and returns the string value of the composed attribute.

  • add() public

    Registers a list of templates by name

  • addClass() public

    Adds a class and returns a unique list either in array or space separated

  • configShallow() public

    Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.

  • format() public

    Format a template string with $data

  • formatAttributes() public

    Returns a space-delimited string with items of the $options array. If a key of $options array happens to be one of those listed in StringTemplate::$_compactAttributes and its value is one of:

  • getConfig() public

    Returns the config.

  • getConfigOrFail() public

    Returns the config for this specific key.

  • load() public

    Load a config file containing templates.

  • pop() public

    Restore the most recently pushed set of templates.

  • push() public

    Push the current templates into the template stack.

  • remove() public

    Remove the named template.

  • setConfig() public

    Sets the config.

Method Detail

__construct() public 

__construct(array $config)

Constructor.

Parameters

array $config optional

A set of templates to add.

_compileTemplates() protected 

_compileTemplates(array $templates)

Compile templates into a more efficient printf() compatible format.

Parameters

string[] $templates optional

The template names to compile. If empty all templates will be compiled.

_configDelete() protected 

_configDelete(string $key)

Deletes a single config key.

Parameters

string $key

Key to delete.

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

_configRead() protected 

_configRead(?string $key)

Reads a config key.

Parameters

string|null $key

Key to read.

Returns

mixed

_configWrite() protected 

_configWrite(mixed $key, mixed $value, mixed $merge)

Writes a config key.

Parameters

string|array $key

Key to write to.

mixed $value

Value to write.

bool|string $merge optional

True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

_formatAttribute() protected 

_formatAttribute(string $key, mixed $value, mixed $escape)

Formats an individual attribute, and returns the string value of the composed attribute.

Works with minimized attributes that have the same value as their name such as 'disabled' and 'checked'

Parameters

string $key

The name of the attribute to create

string|string[] $value

The value of the attribute to create.

bool $escape optional

Define if the value must be escaped

Returns

string

The composed attribute.

add() public 

add(array $templates)

Registers a list of templates by name

Example:

$templater->add([
  'link' => '<a href="{{url}}">{{title}}</a>'
  'button' => '<button>{{text}}</button>'
]);

Parameters

string[] $templates

An associative list of named templates.

Returns

$this

addClass() public 

addClass(mixed $input, mixed $newClass, string $useIndex)

Adds a class and returns a unique list either in array or space separated

Parameters

array|string $input

The array or string to add the class to

array|string $newClass

the new class or classes to add

string $useIndex optional

if you are inputting an array with an element other than default of 'class'.

Returns

string|string[]

configShallow() public 

configShallow(mixed $key, mixed $value)

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.

Setting a specific value:

$this->configShallow('key', $value);

Setting a nested value:

$this->configShallow('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->configShallow(['one' => 'value', 'another' => 'value']);

Parameters

string|array $key

The key to set, or a complete array of configs.

mixed|null $value optional

The value to set.

Returns

$this

format() public 

format(string $name, array $data)

Format a template string with $data

Parameters

string $name

The template name.

array $data

The data to insert.

Returns

string

Formatted string

Throws

RuntimeException
If template not found.

formatAttributes() public 

formatAttributes(?array $options, ?array $exclude)

Returns a space-delimited string with items of the $options array. If a key of $options array happens to be one of those listed in StringTemplate::$_compactAttributes and its value is one of:

  • '1' (string)
  • 1 (integer)
  • true (boolean)
  • 'true' (string)

Then the value will be reset to be identical with key's name. If the value is not one of these 4, the parameter is not output.

'escape' is a special option in that it controls the conversion of attributes to their HTML-entity encoded equivalents. Set to false to disable HTML-encoding.

If value for any option key is set to null or false, that option will be excluded from output.

This method uses the 'attribute' and 'compactAttribute' templates. Each of these templates uses the name and value variables. You can modify these templates to change how attributes are formatted.

Parameters

array|null $options

Array of options.

array|null $exclude optional

Array of options to be excluded, the options here will not be part of the return.

Returns

string

Composed attributes.

getConfig() public 

getConfig(?string $key, mixed $default)

Returns the config.

Usage

Reading the whole config:

$this->getConfig();

Reading a specific value:

$this->getConfig('key');

Reading a nested value:

$this->getConfig('some.nested.key');

Reading with default value:

$this->getConfig('some-key', 'default-value');

Parameters

string|null $key optional

The key to get or null for the whole config.

mixed $default optional

The return value when the key does not exist.

Returns

mixed

Configuration data at the named key or null if the key does not exist.

getConfigOrFail() public 

getConfigOrFail(string $key)

Returns the config for this specific key.

The config value for this key must exist, it can never be null.

Parameters

string $key

The key to get.

Returns

mixed

Configuration data at the named key

Throws

InvalidArgumentException

load() public 

load(string $file)

Load a config file containing templates.

Template files should define a $config variable containing all the templates to load. Loaded templates will be merged with existing templates.

Parameters

string $file

The file to load

pop() public 

pop()

Restore the most recently pushed set of templates.

push() public 

push()

Push the current templates into the template stack.

remove() public 

remove(string $name)

Remove the named template.

Parameters

string $name

The template to remove.

setConfig() public 

setConfig(mixed $key, mixed $value, mixed $merge)

Sets the config.

Usage

Setting a specific value:

$this->setConfig('key', $value);

Setting a nested value:

$this->setConfig('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->setConfig(['one' => 'value', 'another' => 'value']);

Parameters

string|array $key

The key to set, or a complete array of configs.

mixed|null $value optional

The value to set.

bool $merge optional

Whether to recursively merge or overwrite existing config, defaults to true.

Returns

$this

Throws

Cake\Core\Exception\Exception
When trying to set a key that is invalid.

Property Detail

$_compactAttributes protected

List of attributes that can be made compact.

Type

array

$_compiled protected

Contains the list of compiled templates

Type

array

$_config protected

Runtime config

Type

array

$_configInitialized protected

Whether the config property has already been configured with defaults

Type

bool

$_configStack protected

A stack of template sets that have been stashed temporarily.

Type

array

$_defaultConfig protected

The default templates this instance holds.

Type

array

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.0/class-Cake.View.StringTemplate.html