[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      * Assign key variable pairs from an array to a specified block
 132      * @param string $blockname Name of block to assign $vararray to
 133      * @param array $vararray A hash of variable name => value pairs
 134      * @return \phpbb\template\template $this
 135      */
 136  	public function assign_block_vars($blockname, array $vararray);
 137  
 138      /**
 139      * Assign key variable pairs from an array to a whole specified block loop
 140      * @param string $blockname Name of block to assign $block_vars_array to
 141      * @param array $block_vars_array An array of hashes of variable name => value pairs
 142      * @return \phpbb\template\template $this
 143      */
 144  	public function assign_block_vars_array($blockname, array $block_vars_array);
 145  
 146      /**
 147      * Change already assigned key variable pair (one-dimensional - single loop entry)
 148      *
 149      * An example of how to use this function:
 150      * {@example alter_block_array.php}
 151      *
 152      * @param    string    $blockname    the blockname, for example 'loop'
 153      * @param    array    $vararray    the var array to insert/add or merge
 154      * @param    mixed    $key        Key to search for
 155      *
 156      * array: KEY => VALUE [the key/value pair to search for within the loop to determine the correct position]
 157      *
 158      * int: Position [the position to change or insert at directly given]
 159      *
 160      * If key is false the position is set to 0
 161      * If key is true the position is set to the last entry
 162      *
 163      * @param    string    $mode        Mode to execute (valid modes are 'insert' and 'change')
 164      *
 165      *    If insert, the vararray is inserted at the given position (position counting from zero).
 166      *    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).
 167      *
 168      * Since counting begins by zero, inserting at the last position will result in this array: array(vararray, last positioned array)
 169      * and inserting at position 1 will result in this array: array(first positioned array, vararray, following vars)
 170      *
 171      * @return bool false on error, true on success
 172      */
 173  	public function alter_block_array($blockname, array $vararray, $key = false, $mode = 'insert');
 174  
 175      /**
 176      * Find the index for a specified key in the innermost specified block
 177      *
 178      * @param    string    $blockname    the blockname, for example 'loop'
 179      * @param    mixed    $key        Key to search for
 180      *
 181      * array: KEY => VALUE [the key/value pair to search for within the loop to determine the correct position]
 182      *
 183      * int: Position [the position to search for]
 184      *
 185      * If key is false the position is set to 0
 186      * If key is true the position is set to the last entry
 187      *
 188      * @return mixed false if not found, index position otherwise; be sure to test with ===
 189      */
 190  	public function find_key_index($blockname, $key);
 191  
 192      /**
 193      * Get path to template for handle (required for BBCode parser)
 194      *
 195      * @param string $handle Handle to retrieve the source file
 196      * @return string
 197      */
 198  	public function get_source_file_for_handle($handle);
 199  }