[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3  *
   4  * This file is part of the phpBB Forum Software package.
   5  *
   6  * @copyright (c) phpBB Limited <https://www.phpbb.com>
   7  * @license GNU General Public License, version 2 (GPL-2.0)
   8  *
   9  * For full copyright and license information, please see
  10  * the docs/CREDITS.txt file.
  11  *
  12  */
  13  
  14  namespace phpbb\template;
  15  
  16  interface template
  17  {
  18  
  19      /**
  20      * Clear the cache
  21      *
  22      * @return \phpbb\template\template
  23      */
  24  	public function clear_cache();
  25  
  26      /**
  27      * Sets the template filenames for handles.
  28      *
  29      * @param array $filename_array Should be a hash of handle => filename pairs.
  30      * @return \phpbb\template\template $this
  31      */
  32  	public function set_filenames(array $filename_array);
  33  
  34      /**
  35      * Get the style tree of the style preferred by the current user
  36      *
  37      * @return array Style tree, most specific first
  38      */
  39  	public function get_user_style();
  40  
  41      /**
  42      * Set style location based on (current) user's chosen style.
  43      *
  44      * @param array $style_directories The directories to add style paths for
  45      *     E.g. array('ext/foo/bar/styles', 'styles')
  46      *     Default: array('styles') (phpBB's style directory)
  47      * @return \phpbb\template\template $this
  48      */
  49  	public function set_style($style_directories = array('styles'));
  50  
  51      /**
  52      * Set custom style location (able to use directory outside of phpBB).
  53      *
  54      * Note: Templates are still compiled to phpBB's cache directory.
  55      *
  56      * @param string|array $names Array of names or string of name of template(s) in inheritance tree order, used by extensions.
  57      * @param string|array or string $paths Array of style paths, relative to current root directory
  58      * @return \phpbb\template\template $this
  59      */
  60  	public function set_custom_style($names, $paths);
  61  
  62      /**
  63      * Clears all variables and blocks assigned to this template.
  64      *
  65      * @return \phpbb\template\template $this
  66      */
  67  	public function destroy();
  68  
  69      /**
  70      * Reset/empty complete block
  71      *
  72      * @param string $blockname Name of block to destroy
  73      * @return \phpbb\template\template $this
  74      */
  75  	public function destroy_block_vars($blockname);
  76  
  77      /**
  78      * Display a template for provided handle.
  79      *
  80      * The template will be loaded and compiled, if necessary, first.
  81      *
  82      * This function calls hooks.
  83      *
  84      * @param string $handle Handle to display
  85      * @return \phpbb\template\template $this
  86      */
  87  	public function display($handle);
  88  
  89      /**
  90      * Display the handle and assign the output to a template variable
  91      * or return the compiled result.
  92      *
  93      * @param string $handle Handle to operate on
  94      * @param string $template_var Template variable to assign compiled handle to
  95      * @param bool $return_content If true return compiled handle, otherwise assign to $template_var
  96      * @return \phpbb\template\template|string if $return_content is true return string of the compiled handle, otherwise return $this
  97      */
  98  	public function assign_display($handle, $template_var = '', $return_content = true);
  99  
 100      /**
 101      * Assign key variable pairs from an array
 102      *
 103      * @param array $vararray A hash of variable name => value pairs
 104      * @return \phpbb\template\template $this
 105      */
 106  	public function assign_vars(array $vararray);
 107  
 108      /**
 109      * Assign a single scalar value to a single key.
 110      *
 111      * Value can be a string, an integer or a boolean.
 112      *
 113      * @param string $varname Variable name
 114      * @param string $varval Value to assign to variable
 115      * @return \phpbb\template\template $this
 116      */
 117  	public function assign_var($varname, $varval);
 118  
 119      /**
 120      * Append text to the string value stored in a key.
 121      *
 122      * Text is appended using the string concatenation operator (.).
 123      *
 124      * @param string $varname Variable name
 125      * @param string $varval Value to append to variable
 126      * @return \phpbb\template\template $this
 127      */
 128  	public function append_var($varname, $varval);
 129  
 130      /**
 131      * Retrieve multiple template values
 132      *
 133      * @param array $vararray An array with variable names
 134      * @return array A hash of variable name => value pairs (value is null if not set)
 135      */
 136  	public function retrieve_vars(array $vararray);
 137  
 138      /**
 139      * Retreive a single scalar value from a single key.
 140      *
 141      * @param string $varname Variable name
 142      * @return mixed Variable value, or null if not set
 143      */
 144  	public function retrieve_var($varname);
 145  
 146      /**
 147      * Assign key variable pairs from an array to a specified block
 148      * @param string $blockname Name of block to assign $vararray to
 149      * @param array $vararray A hash of variable name => value pairs
 150      * @return \phpbb\template\template $this
 151      */
 152  	public function assign_block_vars($blockname, array $vararray);
 153  
 154      /**
 155      * Assign key variable pairs from an array to a whole specified block loop
 156      * @param string $blockname Name of block to assign $block_vars_array to
 157      * @param array $block_vars_array An array of hashes of variable name => value pairs
 158      * @return \phpbb\template\template $this
 159      */
 160  	public function assign_block_vars_array($blockname, array $block_vars_array);
 161  
 162      /**
 163      * Retrieve variable values from an specified block
 164      * @param string $blockname Name of block to retrieve $vararray from
 165      * @param array $vararray An array with variable names, empty array gets all vars
 166      * @return array A hash of variable name => value pairs (value is null if not set)
 167      */
 168  	public function retrieve_block_vars($blockname, array $vararray);
 169  
 170      /**
 171      * Change already assigned key variable pair (one-dimensional - single loop entry)
 172      *
 173      * An example of how to use this function:
 174      * {@example alter_block_array.php}
 175      *
 176      * @param    string    $blockname    the blockname, for example 'loop'
 177      * @param    array    $vararray    the var array to insert/add or merge
 178      * @param    mixed    $key        Key to search for
 179      *
 180      * array: KEY => VALUE [the key/value pair to search for within the loop to determine the correct position]
 181      *
 182      * int: Position [the position to change or insert at directly given]
 183      *
 184      * If key is false the position is set to 0
 185      * If key is true the position is set to the last entry
 186      *
 187      * @param    string    $mode        Mode to execute (valid modes are 'insert', 'change' and 'delete')
 188      *
 189      *    If insert, the vararray is inserted at the given position (position counting from zero).
 190      *    If change, the current block gets merged with the vararray (resulting in new \key/value pairs be added and existing keys be replaced by the new \value).
 191      *    If delete, the vararray is ignored, and the block at the given position (counting from zero) is removed.
 192      *
 193      * Since counting begins by zero, inserting at the last position will result in this array: array(vararray, last positioned array)
 194      * and inserting at position 1 will result in this array: array(first positioned array, vararray, following vars)
 195      *
 196      * @return bool false on error, true on success
 197      */
 198  	public function alter_block_array($blockname, array $vararray, $key = false, $mode = 'insert');
 199  
 200      /**
 201      * Find the index for a specified key in the innermost specified block
 202      *
 203      * @param    string    $blockname    the blockname, for example 'loop'
 204      * @param    mixed    $key        Key to search for
 205      *
 206      * array: KEY => VALUE [the key/value pair to search for within the loop to determine the correct position]
 207      *
 208      * int: Position [the position to search for]
 209      *
 210      * If key is false the position is set to 0
 211      * If key is true the position is set to the last entry
 212      *
 213      * @return mixed false if not found, index position otherwise; be sure to test with ===
 214      */
 215  	public function find_key_index($blockname, $key);
 216  
 217      /**
 218      * Get path to template for handle (required for BBCode parser)
 219      *
 220      * @param string $handle Handle to retrieve the source file
 221      * @return string
 222      */
 223  	public function get_source_file_for_handle($handle);
 224  }