Changeset 25812


Ignore:
Timestamp:
Dec 7, 2013, 1:00:41 AM (10 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.