Integrated Template Extension - ITX With this class you get the full power of the phplib template class. More...

Inheritance diagram for HTML_Template_ITX:

Collaboration diagram for HTML_Template_ITX:

Public Member Functions
	__construct (string $root='')
	Builds some complex regexps and calls the constructor of the parent class. More...

	replaceBlock (string $block, string $template, bool $keep_content=false)
	Replaces an existing block with new content. More...

	addBlock (string $placeholder, string $blockname, string $template)
	Adds a block to the template changing a variable placeholder to a block placeholder. More...

	addBlockfile (string $placeholder, string $blockname, string $filename)
	Adds a block taken from a file to the template changing a variable placeholder to a block placeholder. More...

	removeBlockData (string $block)
	Recursively removes all data assiciated with a block, including all inner blocks. More...

	blockExists (string $blockname)
	Checks wheter a block exists. More...

	buildFunctionlist ()
	Builds a functionlist from the template. More...

	getValue (string $code, $delimiter)
	Truncates the given code from the first occurence of $delimiter but ignores $delimiter enclosed by " or '. More...

	deleteFromBlockvariablelist (string $block, $variables)
	Deletes one or many variables from the block variable list. More...

	updateBlockvariablelist (string $block)
	Updates the variable list of a block. More...

	findPlaceholderBlocks (string $variable)
	Returns an array of blocknames where the given variable placeholder is used. More...

	warning (string $message, string $file='', int $line=0)
	Handles warnings, saves them to $warn and prints them or calls die() depending on the flags. More...

Public Member Functions inherited from HTML_Template_IT
	__construct (string $root='', ?array $options=null)
	Builds some complex regular expressions and optinally sets the file root directory. More...

	setOption (string $option, $value)
	Sets the option for the template class. More...

	setOptions (array $options)
	Sets the options for the template class. More...

	show (string $block=self::IT_DEFAULT_BLOCK)
	Print a certain block with all replacements done. More...

	get (string $block=self::IT_DEFAULT_BLOCK)
	Returns a block with all replacements done. More...

	parse (string $block=self::IT_DEFAULT_BLOCK, bool $flag_recursion=false)
	Parses the given block. More...

	parseCurrentBlock ()
	Parses the current block. More...

	setVariable ($variable, $value='')
	Sets a variable value. More...

	setCurrentBlock (string $block=self::IT_DEFAULT_BLOCK)
	Sets the name of the current block that is the block where variables are added. More...

	touchBlock (string $block)
	Preserves an empty block even if removeEmptyBlocks is true. More...

	free ()
	Clears all datafields of the object. More...

	setTemplate (string $template, bool $removeUnknownVariables=true, bool $removeEmptyBlocks=true)
	Sets the template. More...

	loadTemplatefile (string $filename, bool $removeUnknownVariables=true, bool $removeEmptyBlocks=true)
	Reads a template file from the disk. More...

	setRoot (string $root)
	Sets the file root. More...

	buildBlockvariablelist ()
	Build a list of all variables within of a block. More...

	findBlocks (string $string)
	Recusively builds a list of all blocks within the template. More...

	getFile (string $filename)
	Reads a file from disk and returns its content. More...

	_addPregDelimiters (string $str)
	Adds delimiters to a string, so it can be used as a pattern in preg_* functions. More...

	_preserveOpeningDelimiter (string $str)
	Replaces an opening delimiter by a special string. More...

	errorMessage (int $value, string $blockname='')
	Return a textual error message for a IT error code. More...

Data Fields
array	$warn = []
	Array with all warnings. More...

bool	$printWarning = false
	Print warnings? More...

bool	$haltOnWarning = false
	Call die() on warning? More...

string	$checkblocknameRegExp = ''
	RegExp used to test for a valid blockname. More...

string	$functionPrefix = 'func_'
	Functionnameprefix used when searching function calls in the template. More...

string	$functionnameRegExp = '[_a-zA-Z]+[A-Za-z_0-9]*'
	Functionname RegExp. More...

string	$functionRegExp = ''
	RegExp used to grep function calls in the template. More...

array	$functions = []
	List of functions found in the template. More...

array	$callback = []
	List of callback functions specified by the user. More...

Data Fields inherited from HTML_Template_IT
const	IT_OK = 1

const	IT_ERROR = -1

const	IT_TPL_NOT_FOUND = -2

const	IT_BLOCK_NOT_FOUND = -3

const	IT_BLOCK_DUPLICATE = -4

const	IT_UNKNOWN_OPTION = -6

const	IT_DEFAULT_BLOCK = '__global__'

array	$err = []
	Contains the error objects. More...

bool	$clearCache = false
	Clear cache on get()? More...

string	$openingDelimiter = '{'
	First character of a variable placeholder ( _{_VARIABLE} ). More...

string	$closingDelimiter = '}'
	Last character of a variable placeholder ( {VARIABLE_}_ ). More...

string	$blocknameRegExp = '[\.0-9A-Za-z_-]+'
	RegExp matching a block in the template. More...

string	$variablenameRegExp = '[\.0-9A-Za-z_-]+'
	RegExp matching a variable placeholder in the template. More...

string	$variablesRegExp = ''
	RegExp used to find variable placeholder, filled by the constructor. More...

string	$removeVariablesRegExp = ''
	RegExp used to strip unused variable placeholder. More...

bool	$removeUnknownVariables = true
	Controls the handling of unknown variables, default is remove. More...

bool	$removeEmptyBlocks = true
	Controls the handling of empty blocks, default is remove. More...

string	$blockRegExp = ''
	RegExp used to find blocks an their content, filled by the constructor. More...

string	$currentBlock = self::IT_DEFAULT_BLOCK
	Name of the current block. More...

string	$template = ''
	Content of the template. More...

array	$blocklist = []
	Array of all blocks and their content. More...

array	$blockdata = []
	Array with the parsed content of a block. More...

array	$blockvariables = []
	Array of variables in a block. More...

array	$blockparents = []
	Array of block parents. More...

array	$blockinner = []
	Array of inner blocks of a block. More...

array	$touchedBlocks = []
	List of blocks to preverse even if they are "empty". More...

array	$variableCache = []
	Variable cache. More...

bool	$clearCacheOnParse = false
	Clear the variable cache on parse? If you're not an expert just leave the default false. More...

string	$fileRoot = ''
	Root directory for all file operations. More...

bool	$flagBlocktrouble = false
	Internal flag indicating that a blockname was used multiple times. More...

bool	$flagGlobalParsed = false
	Flag indicating that the global block was parsed. More...

bool	$flagCacheTemplatefile = true
	EXPERIMENTAL! FIXME! Flag indication that a template gets cached. More...

string	$lastTemplatefile = ''
	EXPERIMENTAL! FIXME! More...

array	$_options
	$_options['preserve_data'] Whether to substitute variables and remove empty placeholders in data passed through setVariable (see also bugs #20199, #21951). More...

Protected Member Functions
	init ()

Protected Member Functions inherited from HTML_Template_IT
	init ()
	Clears all datafields of the object and rebuild the internal blocklist LoadTemplatefile() and setTemplate() automatically call this function when a new template is given. More...

Additional Inherited Members
Protected Attributes inherited from HTML_Template_IT
array string	$real_filename = ''
	Holds the real template file name. More...

Detailed Description

Integrated Template Extension - ITX With this class you get the full power of the phplib template class.

You may have one file with blocks in it but you have as well one main file and multiple files one for each block. This is quite usefull when you have user configurable websites. Using blocks not in the main template allows you to modify some parts of your layout easily. Note that you can replace an existing block and add new blocks at runtime. Adding new blocks means changing a variable placeholder to a block.

Author: Ulf Wendel uw@ne.nosp@m.tuse.nosp@m..de

Definition at line 44 of file ITX.php.

Constructor & Destructor Documentation

◆ __construct()

HTML_Template_ITX::__construct ( string $root = '' )

Builds some complex regexps and calls the constructor of the parent class.

Make sure that you call this constructor if you derive your own template class from this one.

Exceptions

ilTemplateException

Definition at line 99 of file ITX.php.

References ILIAS\GlobalScreen\Provider\__construct().

     {
         $this->checkblocknameRegExp = '@' . $this->blocknameRegExp . '@';
         $this->functionRegExp = '@' . $this->functionPrefix . '(' .
             $this->functionnameRegExp . ')\s*\(@sm';
 
         parent::__construct($root);
     }

Here is the call graph for this function:

Member Function Documentation

◆ addBlock()

HTML_Template_ITX::addBlock	(	string	$placeholder,
		string	$blockname,
		string	$template
	)

Adds a block to the template changing a variable placeholder to a block placeholder.

Add means "replace a variable placeholder by a new block". This is different to PHPLibs templates. The function loads a block, creates a handle for it and assigns it to a certain variable placeholder. To to the same with PHPLibs templates you would call set_file() to create the handle and parse() to assign the parsed block to a variable. By this PHPLibs templates assume that you tend to assign a block to more than one one placeholder. To assign a parsed block to more than only the placeholder you specify in this function you have to use a combination of getBlock() and setVariable(). As no updates to cached data is necessary addBlock() and addBlockfile() are rather "cheap" meaning quick operations. The block content must not start with and end with this would cause overhead and produce an error.

Exceptions

ilTemplateException

Definition at line 186 of file ITX.php.

References deleteFromBlockvariablelist(), HTML_Template_IT\findBlocks(), findPlaceholderBlocks(), and updateBlockvariablelist().

Referenced by ilTemplate\addBlockFile(), and addBlockfile().

                                                                                       : bool
     {
         // Don't trust any user even if it's a programmer or yourself...
         if ($placeholder === '') {
             throw new ilTemplateException('No variable placeholder given.');
         }
 
         if ($blockname === '' ||
             !preg_match($this->checkblocknameRegExp, $blockname)) {
             throw new ilTemplateException("No or invalid blockname '$blockname' given.");
         }
 
         if ($template === '') {
             throw new ilTemplateException('No block content given.');
         }
 
         if (isset($this->blocklist[$blockname])) {
             throw new ilTemplateException('The block ' . $blockname . ' already exists.');
         }
 
         // find out where to insert the new block
         $parents = $this->findPlaceholderBlocks($placeholder);
         if (count($parents) === 0) {
             throw (new ilTemplateException("The variable placeholder" .
                 " '$placeholder' was not found in the template."));
         }
 
         if (count($parents) > 1) {
             $msg = '';
             foreach ($parents as $index => $parent) {
                 $msg .= (isset($parents[$index + 1])) ?
                     "$parent, " : $parent;
             }
 
             throw new ilTemplateException("The variable placeholder " . "'$placeholder'" . " must be unique, found in multiple blocks '$msg'.");
         }
 
         $template = "<!-- BEGIN $blockname -->" . $template . "<!-- END $blockname -->";
         $this->findBlocks($template);
         if ($this->flagBlocktrouble) {
             return false;    // findBlocks() already throws an exception
         }
         $this->blockinner[$parents[0]][] = $blockname;
         $this->blocklist[$parents[0]] = preg_replace(
             '@' . $this->openingDelimiter . $placeholder .
             $this->closingDelimiter . '@',
             $this->openingDelimiter . '__' . $blockname . '__' .
             $this->closingDelimiter,
             $this->blocklist[$parents[0]]
         );
 
         $this->deleteFromBlockvariablelist($parents[0], $placeholder);
         $this->updateBlockvariablelist($blockname);
 
         return true;
     }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ addBlockfile()

HTML_Template_ITX::addBlockfile	(	string	$placeholder,
		string	$blockname,
		string	$filename
	)

Adds a block taken from a file to the template changing a variable placeholder to a block placeholder.

Exceptions

ilTemplateException

Definition at line 248 of file ITX.php.

References addBlock(), and HTML_Template_IT\getFile().

                                                                                           : bool
     {
         return $this->addBlock($placeholder, $blockname, $this->getFile($filename));
     }

Here is the call graph for this function:

◆ blockExists()

HTML_Template_ITX::blockExists ( string $blockname )

Checks wheter a block exists.

Definition at line 277 of file ITX.php.

                                                   : bool
     {
         return isset($this->blocklist[$blockname]);
     }

◆ buildFunctionlist()

HTML_Template_ITX::buildFunctionlist ( )

Builds a functionlist from the template.

Definition at line 285 of file ITX.php.

References HTML_Template_IT\$closingDelimiter, HTML_Template_IT\$template, and getValue().

Referenced by ilTemplate\init(), and init().

                                        : void
     {
         $this->functions = [];
 
         $template = $this->template;
         $num = 0;
 
         while (preg_match($this->functionRegExp, $template, $regs)) {
             $pos = strpos($template, $regs[0]);
             $template = substr($template, $pos + strlen($regs[0]));
 
             $head = $this->getValue($template, ')');
             $args = [];
 
             $search = $regs[0] . $head . ')';
 
             $replace = $this->openingDelimiter .
                 '__function' . $num . '__' .
                 $this->closingDelimiter;
 
             $this->template = str_replace($search, $replace, $this->template);
             $template = str_replace($search, $replace, $template);
 
             while ($head !== '' && $args2 = $this->getValue($head, ',')) {
                 $arg2 = trim($args2);
                 $args[] = ('"' === $arg2[0] || "'" === $arg2[0]) ?
                     substr($arg2, 1, -1) : $arg2;
                 if ($arg2 === $head) {
                     break;
                 }
                 $head = substr($head, strlen($arg2) + 1);
             }
 
             $this->functions[$num++] = [
                 'name' => $regs[1],
                 'args' => $args
             ];
         }
     }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ deleteFromBlockvariablelist()

HTML_Template_ITX::deleteFromBlockvariablelist	(	string	$block,
			$variables
	)

Deletes one or many variables from the block variable list.

Parameters

array | string $variables Name of one variable or array of variables ( array ( name => true ) ) to be stripped.

Definition at line 377 of file ITX.php.

Referenced by addBlock().

                                                                           : void
     {
         if (!is_array($variables)) {
             $variables = [$variables => true];
         }
 
         reset($this->blockvariables[$block]);
         foreach ($this->blockvariables[$block] as $varname => $val) {
             if (isset($variables[$varname])) {
                 unset($this->blockvariables[$block][$varname]);
             }
         }
     }

Here is the caller graph for this function:

◆ findPlaceholderBlocks()

HTML_Template_ITX::findPlaceholderBlocks ( string $variable )

Returns an array of blocknames where the given variable placeholder is used.

Definition at line 429 of file ITX.php.

Referenced by addBlock().

                                                            : array
     {
         $parents = [];
         reset($this->blocklist);
         foreach ($this->blocklist as $blockname => $content) {
             reset($this->blockvariables[$blockname]);
             foreach ($this->blockvariables[$blockname] as $varname => $val) {
                 if ($variable === $varname) {
                     $parents[] = $blockname;
                 }
             }
         }
 
         return $parents;
     }

Here is the caller graph for this function:

◆ getValue()

HTML_Template_ITX::getValue	(	string	$code,
			$delimiter
	)

Truncates the given code from the first occurence of $delimiter but ignores $delimiter enclosed by " or '.

Parameters

array | string $delimiter

Definition at line 330 of file ITX.php.

Referenced by buildFunctionlist().

                                                       : string
     {
         if ($code === '') {
             return '';
         }
 
         if (!is_array($delimiter)) {
             $delimiter = [$delimiter => true];
         }
 
         $len = strlen($code);
         $enclosed = false;
         $enclosed_by = '';
 
         if (isset($delimiter[$code[0]])) {
             $i = 1;
         } else {
             for ($i = 0; $i < $len; ++$i) {
                 $char = $code[$i];
 
                 if (
                     ($char === '"' || $char === "'") &&
                     ($char === $enclosed_by || '' === $enclosed_by) &&
                     (0 === $i || ($i > 0 && '\\' !== $code[$i - 1]))
                 ) {
                     if (!$enclosed) {
                         $enclosed_by = $char;
                     } else {
                         $enclosed_by = "";
                     }
                     $enclosed = !$enclosed;
                 }
 
                 if (!$enclosed && isset($delimiter[$char])) {
                     break;
                 }
             }
         }
 
         return substr($code, 0, $i);
     }

Here is the caller graph for this function:

◆ init()

HTML_Template_ITX::init ( )

protected

Definition at line 108 of file ITX.php.

References HTML_Template_IT\buildBlockvariablelist(), buildFunctionlist(), HTML_Template_IT\findBlocks(), and HTML_Template_IT\free().

                              : void
     {
         $this->free();
         $this->buildFunctionlist();
         $this->findBlocks($this->template);
         // we don't need it any more
         $this->template = '';
         $this->buildBlockvariablelist();
     }

Here is the call graph for this function:

◆ removeBlockData()

HTML_Template_ITX::removeBlockData ( string $block )

Recursively removes all data assiciated with a block, including all inner blocks.

Definition at line 256 of file ITX.php.

Referenced by replaceBlock().

                                                   : void
     {
         if (isset($this->blockinner[$block])) {
             foreach ($this->blockinner[$block] as $inner) {
                 $this->removeBlockData($inner);
             }
 
             unset($this->blockinner[$block]);
         }
 
         unset(
             $this->blocklist[$block],
             $this->blockdata[$block],
             $this->blockvariables[$block],
             $this->touchedBlocks[$block]
         );
     }

Here is the caller graph for this function:

◆ replaceBlock()

HTML_Template_ITX::replaceBlock	(	string	$block,
		string	$template,
		bool	$keep_content = `false`
	)

Replaces an existing block with new content.

This function will replace a block of the template and all blocks contained in the replaced block and add a new block insted, means you can dynamically change your template. Note that changing the template structure violates one of the IT[X] development goals. I've tried to write a simple to use template engine supporting blocks. In contrast to other systems IT[X] analyses the way you've nested blocks and knows which block belongs into another block. The nesting information helps to make the API short and simple. Replacing blocks does not only mean that IT[X] has to update the nesting information (relatively time consumpting task) but you have to make sure that you do not get confused due to the template change itself.

Parameters

bool $keep_content true if the new block inherits the content of the old block

Exceptions

ilTemplateException

Definition at line 134 of file ITX.php.

References HTML_Template_IT\$blockdata, HTML_Template_IT\buildBlockvariablelist(), HTML_Template_IT\findBlocks(), and removeBlockData().

                                                                                              : bool
     {
         if (!isset($this->blocklist[$block])) {
             throw new ilTemplateException("The block " . "'$block'" . " does not exist in the template and thus it can't be replaced.");
         }
 
         if ($template === '') {
             throw new ilTemplateException('No block content given.');
         }
 
         if ($keep_content) {
             $blockdata = $this->blockdata[$block];
         }
 
         // remove all kinds of links to the block / data of the block
         $this->removeBlockData($block);
 
         $template = "<!-- BEGIN $block -->" . $template . "<!-- END $block -->";
         $parents = $this->blockparents[$block];
         $this->findBlocks($template);
         $this->blockparents[$block] = $parents;
 
         // KLUDGE: rebuild the list for all block - could be done faster
         $this->buildBlockvariablelist();
 
         if ($keep_content) {
             $this->blockdata[$block] = $blockdata;
         }
 
         return true;
     }

Here is the call graph for this function:

◆ updateBlockvariablelist()

HTML_Template_ITX::updateBlockvariablelist ( string $block )

Updates the variable list of a block.

Definition at line 394 of file ITX.php.

Referenced by addBlock().

                                                           : void
     {
         preg_match_all(
             $this->variablesRegExp,
             $this->blocklist[$block],
             $regs
         );
 
         if (count($regs[1]) !== 0) {
             foreach ($regs[1] as $var) {
                 $this->blockvariables[$block][$var] = true;
             }
         } else {
             $this->blockvariables[$block] = [];
         }
 
         // check if any inner blocks were found
         if (isset($this->blockinner[$block]) &&
             is_array($this->blockinner[$block]) &&
             count($this->blockinner[$block]) > 0
         ) {
             /*
              * loop through inner blocks, registering the variable
              * placeholders in each
              */
             foreach ($this->blockinner[$block] as $childBlock) {
                 $this->updateBlockvariablelist($childBlock);
             }
         }
     }

Here is the caller graph for this function:

◆ warning()

HTML_Template_ITX::warning	(	string	$message,
		string	$file = `''`,
		int	$line = `0`
	)

Handles warnings, saves them to $warn and prints them or calls die() depending on the flags.

Definition at line 449 of file ITX.php.

References $message.

                                                                               : void
     {
         $message = sprintf(
             'HTML_Template_ITX Warning: %s [File: %s, Line: %d]',
             $message,
             $file,
             $line
         );
 
         $this->warn[] = $message;
 
         if ($this->printWarning) {
             print $message;
         }
 
         if ($this->haltOnWarning) {
             die($message);
         }
     }

Field Documentation

◆ $callback

array HTML_Template_ITX::$callback = []

List of callback functions specified by the user.

Definition at line 90 of file ITX.php.

◆ $checkblocknameRegExp

string HTML_Template_ITX::$checkblocknameRegExp = ''

RegExp used to test for a valid blockname.

Definition at line 64 of file ITX.php.

◆ $functionnameRegExp

string HTML_Template_ITX::$functionnameRegExp = '[_a-zA-Z]+[A-Za-z_0-9]*'

Functionname RegExp.

Definition at line 74 of file ITX.php.

◆ $functionPrefix

string HTML_Template_ITX::$functionPrefix = 'func_'

Functionnameprefix used when searching function calls in the template.

Definition at line 69 of file ITX.php.

◆ $functionRegExp

string HTML_Template_ITX::$functionRegExp = ''

RegExp used to grep function calls in the template.

The variable gets set by the constructor.

Definition at line 80 of file ITX.php.

◆ $functions

array HTML_Template_ITX::$functions = []

List of functions found in the template.

Definition at line 85 of file ITX.php.

◆ $haltOnWarning

bool HTML_Template_ITX::$haltOnWarning = false

Call die() on warning?

Definition at line 59 of file ITX.php.

◆ $printWarning

bool HTML_Template_ITX::$printWarning = false

Print warnings?

Definition at line 54 of file ITX.php.

◆ $warn

array HTML_Template_ITX::$warn = []

Array with all warnings.

Definition at line 49 of file ITX.php.

The documentation for this class was generated from the following file:

components/ILIAS/UICore/lib/html-it/ITX.php

Public Member Functions

Data Fields

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ addBlock()

◆ addBlockfile()

◆ blockExists()

◆ buildFunctionlist()

◆ deleteFromBlockvariablelist()

◆ findPlaceholderBlocks()

◆ getValue()

◆ init()

◆ removeBlockData()

◆ replaceBlock()

◆ updateBlockvariablelist()

◆ warning()

Field Documentation

◆ $callback

◆ $checkblocknameRegExp

◆ $functionnameRegExp

◆ $functionPrefix

◆ $functionRegExp

◆ $functions

◆ $haltOnWarning

◆ $printWarning

◆ $warn