Changeset 25812


Ignore:
Timestamp:
12/07/13 01:00:41 (6 years ago)
Author:
mistic100
Message:

feature 2999: documentation of Template class, other classes of template.class.php pending

Location:
trunk/include
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/include/functions.inc.php

    r25615 r25812  
    3737include_once( PHPWG_ROOT_PATH .'include/derivative_std_params.inc.php'); 
    3838include_once( PHPWG_ROOT_PATH .'include/derivative.inc.php'); 
    39 //require_once( PHPWG_ROOT_PATH .'include/smarty/libs/Smarty.class.php'); 
    40 require_once( PHPWG_ROOT_PATH .'include/smarty/libs/SmartyBC.class.php'); 
    4139include_once( PHPWG_ROOT_PATH .'include/template.class.php'); 
    4240 
  • trunk/include/template.class.php

    r25800 r25812  
    2222// +-----------------------------------------------------------------------+ 
    2323 
     24/** 
     25 * @package template 
     26 */ 
     27 
     28//require_once( PHPWG_ROOT_PATH .'include/smarty/libs/Smarty.class.php'); 
     29require_once( PHPWG_ROOT_PATH .'include/smarty/libs/SmartyBC.class.php'); 
     30 
     31 
     32/** default rank for buttons */ 
    2433define('BUTTONS_RANK_NEUTRAL', 50); 
    2534 
    26 class Template { 
    27  
     35/** 
     36 * This a wrapper arround Smarty classes proving various custom mechanisms for templates. 
     37 */ 
     38class Template 
     39{ 
     40  /** @var Smarty */ 
    2841  var $smarty; 
    29  
     42  /** @var string */ 
    3043  var $output = ''; 
    3144 
    32   // Hash of filenames for each template handle. 
     45  /** @var string[] - Hash of filenames for each template handle. */ 
    3346  var $files = array(); 
    34  
    35   // Template extents filenames for each template handle. 
     47  /** @var string[] - Template extents filenames for each template handle. */ 
    3648  var $extents = array(); 
    37  
    38   // Templates prefilter from external sources (plugins) 
     49  /** @var array - Templates prefilter from external sources (plugins) */ 
    3950  var $external_filters = array(); 
    4051 
    41   // used by html_head smarty block to add content before </head> 
     52  /** @var string - Content to add before </head> tag */ 
    4253  var $html_head_elements = array(); 
     54  /** @var string - Runtime CSS rules */ 
    4355  private $html_style = ''; 
    4456 
     57  /** @const string */ 
    4558  const COMBINED_SCRIPTS_TAG = '<!-- COMBINED_SCRIPTS -->'; 
     59  /** @var ScriptLoader */ 
    4660  var $scriptLoader; 
    4761 
     62  /** @const string */ 
    4863  const COMBINED_CSS_TAG = '<!-- COMBINED_CSS -->'; 
     64  /** @var CssLoader */ 
    4965  var $cssLoader; 
    5066 
     67  /** @var array - Runtime buttons on picture page */ 
    5168  var $picture_buttons = array(); 
     69  /** @var array - Runtime buttons on index page */ 
    5270  var $index_buttons = array(); 
    5371 
    54   function Template($root = ".", $theme= "", $path = "template") 
     72 
     73  /** 
     74   * @var string $root 
     75   * @var string $theme 
     76   * @var string $path 
     77   */ 
     78  function __construct($root = ".", $theme= "", $path = "template") 
    5579  { 
    5680    global $conf, $lang_info; 
     
    6387    $this->smarty->debugging = $conf['debug_template']; 
    6488    if (!$this->smarty->debugging) 
     89    { 
    6590      $this->smarty->error_reporting = error_reporting() & ~E_NOTICE; 
     91    } 
    6692    $this->smarty->compile_check = $conf['template_compile_check']; 
    6793    $this->smarty->force_compile = $conf['template_force_compile']; 
     
    134160 
    135161  /** 
    136    * Load theme's parameters. 
     162   * Loads theme's parameters. 
     163   * 
     164   * @param string $root 
     165   * @param string $theme 
     166   * @param string $path 
     167   * @param bool $load_css 
     168   * @param bool $load_local_head 
    137169   */ 
    138170  function set_theme($root, $theme, $path, $load_css=true, $load_local_head=true) 
     
    167199 
    168200  /** 
    169    * Add template directory for this Template object. 
    170    * Set compile id if not exists. 
     201   * Adds template directory for this Template object. 
     202   * Also set compile id if not exists. 
     203   * 
     204   * @param string $dir 
    171205   */ 
    172206  function set_template_dir($dir) 
     
    184218  /** 
    185219   * Gets the template root directory for this Template object. 
     220   * 
     221   * @return string 
    186222   */ 
    187223  function get_template_dir() 
     
    202238  } 
    203239 
     240  /** 
     241   * Returns theme's parameter. 
     242   * 
     243   * @param string $val 
     244   * @return mixed 
     245   */ 
    204246  function get_themeconf($val) 
    205247  { 
     
    210252  /** 
    211253   * Sets the template filename for handle. 
     254   * 
     255   * @param string $handle 
     256   * @param string $filename 
     257   * @return bool 
    212258   */ 
    213259  function set_filename($handle, $filename) 
     
    217263 
    218264  /** 
    219    * Sets the template filenames for handles. $filename_array should be a 
    220    * hash of handle => filename pairs. 
     265   * Sets the template filenames for handles. 
     266   * 
     267   * @param string[] $filename_array hashmap of handle=>filename 
     268   * @return true 
    221269   */ 
    222270  function set_filenames($filename_array) 
     
    243291  /** 
    244292   * Sets template extention filename for handles. 
     293   * 
     294   * @param string $filename 
     295   * @param mixed $param 
     296   * @param string $dir 
     297   * @param bool $overwrite 
     298   * @param string $theme 
     299   * @return bool 
    245300   */ 
    246301  function set_extent($filename, $param, $dir='', $overwrite=true, $theme='N/A') 
     
    251306  /** 
    252307   * Sets template extentions filenames for handles. 
    253    * $filename_array should be an hash of filename => array( handle, param) or filename => handle 
     308   * 
     309   * @param string[] $filename_array hashmap of handle=>filename 
     310   * @param string $dir 
     311   * @param bool $overwrite 
     312   * @param string $theme 
     313   * @return bool 
    254314   */ 
    255315  function set_extents($filename_array, $dir='', $overwrite=true, $theme='N/A') 
     
    289349  } 
    290350 
    291   /** return template extension if exists  */ 
     351  /** 
     352   * Returns template extension if exists. 
     353   * 
     354   * @param string $filename should be empty! 
     355   * @param string $handle 
     356   * @return string 
     357   */ 
    292358  function get_extent($filename='', $handle='') 
    293359  { 
     
    299365  } 
    300366 
    301   /** see smarty assign http://www.smarty.net/manual/en/api.assign.php */ 
    302   function assign($tpl_var, $value = null) 
     367  /** 
     368   * Assigns a template variable. 
     369   * @see http://www.smarty.net/manual/en/api.assign.php 
     370   * 
     371   * @param string|array $tpl_var can be a var name or a hashmap of variables 
     372   *    (in this case, do not use the _$value_ parameter) 
     373   * @param mixed $value 
     374   */ 
     375  function assign($tpl_var, $value=null) 
    303376  { 
    304377    $this->smarty->assign( $tpl_var, $value ); 
     
    306379 
    307380  /** 
    308    * Inserts the uncompiled code for $handle as the value of $varname in the 
    309    * root-level. This can be used to effectively include a template in the 
    310    * middle of another template. 
    311    * This is equivalent to assign($varname, $this->parse($handle, true)) 
     381   * Defines _$varname_ as the compiled result of _$handle_. 
     382   * This can be used to effectively include a template in another template. 
     383   * This is equivalent to assign($varname, $this->parse($handle, true)). 
     384   * 
     385   * @param string $varname 
     386   * @param string $handle 
     387   * @return true 
    312388   */ 
    313389  function assign_var_from_handle($varname, $handle) 
     
    317393  } 
    318394 
    319   /** see smarty append http://www.smarty.net/manual/en/api.append.php */ 
     395  /** 
     396   * Appends a new value in a template array variable, the variable is created if needed. 
     397   * @see http://www.smarty.net/manual/en/api.append.php 
     398   * 
     399   * @param string $tpl_var 
     400   * @param mixed $value 
     401   * @param bool $merge 
     402   */ 
    320403  function append($tpl_var, $value=null, $merge=false) 
    321404  { 
     
    324407 
    325408  /** 
    326    * Root-level variable concatenation. Appends a  string to an existing 
    327    * variable assignment with the same name. 
     409   * Performs a string concatenation. 
     410   * 
     411   * @param string $tpl_var 
     412   * @param string $value 
    328413   */ 
    329414  function concat($tpl_var, $value) 
     
    333418  } 
    334419 
    335   /** see smarty append http://www.smarty.net/manual/en/api.clear_assign.php */ 
     420  /** 
     421   * Removes an assigned template variable. 
     422   * @see http://www.smarty.net/manual/en/api.clear_assign.php 
     423   * 
     424   * @param string $tpl_var 
     425   */ 
    336426  function clear_assign($tpl_var) 
    337427  { 
     
    339429  } 
    340430 
    341   /** see smarty get_template_vars http://www.smarty.net/manual/en/api.get_template_vars.php */ 
    342   function get_template_vars($name=null) 
    343   { 
    344     return $this->smarty->getTemplateVars( $name ); 
    345   } 
    346  
    347  
    348   /** 
    349    * Load the file for the handle, eventually compile the file and run the compiled 
    350    * code. This will add the output to the results or return the result if $return 
    351    * is true. 
     431  /** 
     432   * Returns an assigned template variable. 
     433   * @see http://www.smarty.net/manual/en/api.get_template_vars.php 
     434   * 
     435   * @param string $tpl_var 
     436   */ 
     437  function get_template_vars($tpl_var=null) 
     438  { 
     439    return $this->smarty->getTemplateVars( $tpl_var ); 
     440  } 
     441 
     442  /** 
     443   * Loads the template file of the handle, compiles it and appends the result to the output 
     444   * (or returns it if _$return_ is true). 
     445   * 
     446   * @param string $handle 
     447   * @param bool $return 
     448   * @return null|string 
    352449   */ 
    353450  function parse($handle, $return=false) 
     
    382479 
    383480  /** 
    384    * Load the file for the handle, eventually compile the file and run the compiled 
    385    * code. This will print out the results of executing the template. 
     481   * Loads the template file of the handle, compiles it and appends the result to the output, 
     482   * then sends the output to the browser. 
     483   * 
     484   * @param string $handle 
    386485   */ 
    387486  function pparse($handle) 
     
    391490  } 
    392491 
     492  /** 
     493   * Load and compile JS & CSS into the template and sends the output to the browser. 
     494   */ 
    393495  function flush() 
    394496  { 
     
    450552  } 
    451553 
    452   /** flushes the output */ 
     554  /** 
     555   * Same as flush() but with optional debugging. 
     556   * @see Template::flush() 
     557   */ 
    453558  function p() 
    454559  { 
     
    467572  } 
    468573 
     574  /** 
     575   * Eval a temp string to retrieve the original PHP value. 
     576   * 
     577   * @param string $str 
     578   * @return mixed 
     579   */ 
    469580  static function get_php_str_val($str) 
    470581  { 
     
    482593 
    483594  /** 
    484    * translate variable modifier - translates a text to the currently loaded language 
     595   * "translate" variable modifier. 
     596   * Usage :  
     597   *    - {'Comment'|translate} 
     598   *    - {'%d comments'|translate:$count} 
     599   * @see l10n() 
     600   * 
     601   * @param array $params 
     602   * @return string 
    485603   */ 
    486604  static function modcompiler_translate($params) 
     
    512630  } 
    513631 
     632  /** 
     633   * "translate_dec" variable modifier. 
     634   * Usage : 
     635   *    - {$count|translate_dec:'%d comment':'%d comments'} 
     636   * @see l10n_dec() 
     637   * 
     638   * @param array $params 
     639   * @return string 
     640   */ 
    514641  static function modcompiler_translate_dec($params) 
    515642  { 
     
    538665 
    539666  /** 
    540    * explode variable modifier - similar to php explode 
    541    * 'Yes;No'|@explode:';' -> array('Yes', 'No') 
     667   * "explode" variable modifier. 
     668   * Usage : 
     669   *    - {assign var=valueExploded value=$value|@explode:','} 
     670   * 
     671   * @param string $text 
     672   * @param string $delimiter 
     673   * @return array 
    542674   */ 
    543675  static function mod_explode($text, $delimiter=',') 
     
    547679 
    548680  /** 
    549    * This smarty "html_head" block allows to add content just before 
    550    * </head> element in the output after the head has been parsed. This is 
    551    * handy in order to respect strict standards when <style> and <link> 
    552    * html elements must appear in the <head> element 
     681   * The "html_head" block allows to add content just before 
     682   * </head> element in the output after the head has been parsed. 
     683   * 
     684   * @param array $params (unused) 
     685   * @param string $content 
    553686   */ 
    554687  function block_html_head($params, $content) 
     
    561694  } 
    562695 
     696  /** 
     697   * The "html_style" block allows to add CSS juste before 
     698   * </head> element in the output after the head has been parsed. 
     699   * 
     700   * @param array $params (unused) 
     701   * @param string $content 
     702   */ 
    563703  function block_html_style($params, $content) 
    564704  { 
     
    570710  } 
    571711 
     712  /** 
     713   * The "define_derivative" function allows to define derivative from tpl file. 
     714   * It assigns a DerivativeParams object to _name_ template variable. 
     715   * 
     716   * @param array $params 
     717   *    - name (required) 
     718   *    - type (optional) 
     719   *    - width (required if type is empty) 
     720   *    - height (required if type is empty) 
     721   *    - crop (optional, used if type is empty) 
     722   *    - min_height (optional, used with crop) 
     723   *    - min_height (optional, used with crop) 
     724   * @param Smarty $smarty 
     725   */ 
    572726  function func_define_derivative($params, $smarty) 
    573727  { 
     
    611765  } 
    612766 
    613    /** 
    614     * combine_script smarty function allows inclusion of a javascript file in the current page. 
    615     * The engine will combine several js files into a single one in order to reduce the number of 
    616     * required http requests. 
    617     * param id - required 
    618     * param path - required - the path to js file RELATIVE to piwigo root dir 
    619     * param load - optional - header|footer|async, default header 
    620     * param require - optional - comma separated list of script ids required to be loaded and executed 
    621         before this one 
    622     * param version - optional - plugins could use this and change it in order to force a 
    623        browser refresh 
    624     */ 
     767  /** 
     768   * The "combine_script" functions allows inclusion of a javascript file in the current page. 
     769   * The engine will combine several js files into a single one. 
     770   * 
     771   * @param array $params 
     772   *   - id (required) 
     773   *   - path (required) 
     774   *   - load (optional) 'header', 'footer' or 'async' 
     775   *   - require (optional) comma separated list of script ids required to be loaded 
     776   *     and executed before this one 
     777   *   - version (optional) used to force a browser refresh 
     778   */ 
    625779  function func_combine_script($params) 
    626780  { 
     
    647801  } 
    648802 
    649  
     803  /** 
     804   * The "get_combined_scripts" function returns HTML tag of combined scripts. 
     805   * It can returns a placeholder for delayed JS files combination and minification. 
     806   * 
     807   * @param array $params 
     808   *    - load (required) 
     809   */ 
    650810  function func_get_combined_scripts($params) 
    651811  { 
     
    699859  } 
    700860 
    701  
    702   private static function make_script_src( $script ) 
     861  /** 
     862   * Returns clean relative URL to script file. 
     863   * 
     864   * @param Combinable $script 
     865   * @return string 
     866   */ 
     867  private static function make_script_src($script) 
    703868  { 
    704869    $ret = ''; 
     
    718883  } 
    719884 
     885  /** 
     886   * The "footer_script" block allows to add runtime script in the HTML page. 
     887   * 
     888   * @param array $params 
     889   *    - require (optional) comma separated list of script ids 
     890   * @param string $content 
     891   */ 
    720892  function block_footer_script($params, $content) 
    721893  { 
     
    732904 
    733905  /** 
    734     * combine_css smarty function allows inclusion of a css stylesheet file in the current page. 
    735     * The engine will combine several css files into a single one in order to reduce the number of 
    736     * required http requests. 
    737     * param path - required - the path to css file RELATIVE to piwigo root dir 
    738     * param version - optional - plugins could use this and change it in order to force a 
    739         browser refresh 
    740     */ 
     906   * The "combine_css" function allows inclusion of a css file in the current page. 
     907   * The engine will combine several css files into a single one. 
     908   * 
     909   * @param array $params 
     910   *    - id (optional) used to deal with multiple inclusions from plugins 
     911   *    - path (required) 
     912   *    - version (optional) used to force a browser refresh 
     913   *    - order (optional) 
     914   *    - template (optional) set to true to allow smarty syntax in the css file 
     915   */ 
    741916  function func_combine_css($params) 
    742917  { 
     
    754929  } 
    755930 
     931  /** 
     932   * The "get_combined_scripts" function returns a placeholder for delayed 
     933   * CSS files combination and minification. 
     934   * 
     935   * @param array $params (unused) 
     936   */ 
    756937  function func_get_combined_css($params) 
    757938  { 
     
    759940  } 
    760941 
    761  
    762  /** 
    763    * This function allows to declare a Smarty prefilter from a plugin, thus allowing 
    764    * it to modify template source before compilation and without changing core files 
     942  /** 
     943   * Declares a Smarty prefilter from a plugin, allowing it to modify template 
     944   * source before compilation and without changing core files. 
    765945   * They will be processed by weight ascending. 
    766    * http://www.smarty.net/manual/en/advanced.features.prefilters.php 
     946   * @see http://www.smarty.net/manual/en/advanced.features.prefilters.php 
     947   * 
     948   * @param string $handle 
     949   * @param Callable $callback 
     950   * @param int $weight 
    767951   */ 
    768952  function set_prefilter($handle, $callback, $weight=50) 
     
    772956  } 
    773957 
     958  /** 
     959   * Declares a Smarty postfilter. 
     960   * They will be processed by weight ascending. 
     961   * @see http://www.smarty.net/manual/en/advanced.features.postfilters.php 
     962   * 
     963   * @param string $handle 
     964   * @param Callable $callback 
     965   * @param int $weight 
     966   */ 
    774967  function set_postfilter($handle, $callback, $weight=50) 
    775968  { 
     
    778971  } 
    779972 
     973  /** 
     974   * Declares a Smarty outputfilter. 
     975   * They will be processed by weight ascending. 
     976   * @see http://www.smarty.net/manual/en/advanced.features.outputfilters.php 
     977   * 
     978   * @param string $handle 
     979   * @param Callable $callback 
     980   * @param int $weight 
     981   */ 
    780982  function set_outputfilter($handle, $callback, $weight=50) 
    781983  { 
     
    784986  } 
    785987 
    786  /** 
    787    * This function actually triggers the filters on the tpl files. 
    788    * Called in the parse method. 
    789    * http://www.smarty.net/manual/en/advanced.features.prefilters.php 
     988  /** 
     989   * Register the filters for the tpl file. 
     990   * 
     991   * @param string $handle 
    790992   */ 
    791993  function load_external_filters($handle) 
     
    8071009  } 
    8081010 
     1011  /** 
     1012   * Unregister the filters for the tpl file. 
     1013   * 
     1014   * @param string $handle 
     1015   */ 
    8091016  function unload_external_filters($handle) 
    8101017  { 
     
    8221029  } 
    8231030 
     1031  /** 
     1032   * @toto : description of Template::prefilter_white_space 
     1033   * 
     1034   * @param string $source 
     1035   * @param Smarty $smarty 
     1036   * @param return string 
     1037   */ 
    8241038  static function prefilter_white_space($source, $smarty) 
    8251039  { 
     
    8461060 
    8471061  /** 
    848    * Smarty postfilter 
     1062   * Postfilter used when $conf['compiled_template_cache_language'] is true. 
     1063   * 
     1064   * @param string $source 
     1065   * @param Smarty $smarty 
     1066   * @param return string 
    8491067   */ 
    8501068  static function postfilter_language($source, $smarty) 
     
    8581076  } 
    8591077 
     1078  /** 
     1079   * Prefilter used to add theme local CSS files. 
     1080   * 
     1081   * @param string $source 
     1082   * @param Smarty $smarty 
     1083   * @param return string 
     1084   */ 
    8601085  static function prefilter_local_css($source, $smarty) 
    8611086  { 
     
    8831108  } 
    8841109 
     1110  /** 
     1111   * Loads the configuration file from a theme directory and returns it. 
     1112   * 
     1113   * @param string $dir 
     1114   * @return array 
     1115   */ 
    8851116  function load_themeconf($dir) 
    8861117  { 
     
    8981129  } 
    8991130 
     1131  /** 
     1132   * Registers a button to be displayed on picture page. 
     1133   * 
     1134   * @param string $content 
     1135   * @param int $rank 
     1136   */ 
    9001137  function add_picture_button($content, $rank=BUTTONS_RANK_NEUTRAL) 
    9011138  { 
     
    9031140  } 
    9041141 
     1142  /** 
     1143   * Registers a button to be displayed on index pages. 
     1144   * 
     1145   * @param string $content 
     1146   * @param int $rank 
     1147   */ 
    9051148  function add_index_button($content, $rank=BUTTONS_RANK_NEUTRAL) 
    9061149  { 
     
    9081151  } 
    9091152 
     1153  /** 
     1154   * Assigns PLUGIN_PICTURE_BUTTONS template variable with registered picture buttons. 
     1155   */ 
    9101156  function parse_picture_buttons() 
    9111157  { 
     
    9221168  } 
    9231169 
     1170  /** 
     1171   * Assigns PLUGIN_INDEX_BUTTONS template variable with registered index buttons. 
     1172   */ 
    9241173  function parse_index_buttons() 
    9251174  { 
     
    9351184    } 
    9361185  } 
    937  
    9381186} 
    9391187 
Note: See TracChangeset for help on using the changeset viewer.