From 4dc1d52afbc123c0723ecee211ca8ba15f0affec Mon Sep 17 00:00:00 2001 From: mistic100 Date: Sat, 7 Dec 2013 11:21:07 +0000 Subject: feature 2999: finish documentation of template.class.php git-svn-id: http://piwigo.org/svn/trunk@25815 68402e56-0260-453c-a942-63ccdbb3a9ee --- include/template.class.php | 266 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 233 insertions(+), 33 deletions(-) diff --git a/include/template.class.php b/include/template.class.php index 98f09721f..81e21e9a8 100644 --- a/include/template.class.php +++ b/include/template.class.php @@ -75,7 +75,7 @@ class Template * @var string $theme * @var string $path */ - function __construct($root = ".", $theme= "", $path = "template") + function __construct($root=".", $theme="", $path="template") { global $conf, $lang_info; @@ -1192,27 +1192,46 @@ var s,after = document.getElementsByTagName(\'script\')[document.getElementsByTa */ class PwgTemplateAdapter { + /** + * @deprecated use "translate" modifier + */ function l10n($text) { return l10n($text); } + /** + * @deprecated use "translate_dec" modifier + */ function l10n_dec($s, $p, $v) { return l10n_dec($s, $p, $v); } + /** + * @deprecated use "translate" or "sprintf" modifier + */ function sprintf() { $args = func_get_args(); return call_user_func_array('sprintf', $args ); } + /** + * @param string $type + * @param array $img + * @return DerivativeImage + */ function derivative($type, $img) { return new DerivativeImage($type, $img); } + /** + * @param string $type + * @param array $img + * @return string + */ function derivative_url($type, $img) { return DerivativeImage::url($type, $img); @@ -1220,51 +1239,94 @@ class PwgTemplateAdapter } +/** + * A Combinable represents a JS or CSS file ready for cobination and minification. + */ class Combinable { + /** @var string */ public $id; + /** @var string */ public $path; + /** @var string */ public $version; + /** @var bool */ public $is_template; - function __construct($id, $path, $version) + /** + * @param string $id + * @param string $path + * @param string $version + */ + function __construct($id, $path, $version=0) { $this->id = $id; $this->set_path($path); $this->version = $version; + $this->is_template = false; } + /** + * @param string $path + */ function set_path($path) { if (!empty($path)) $this->path = $path; } + /** + * @return bool + */ function is_remote() { - return url_is_remote( $this->path ) || strncmp($this->path, '//', 2)==0; + return url_is_remote($this->path) || strncmp($this->path, '//', 2)==0; } } +/** + * Implementation of Combinable for JS files. + */ final class Script extends Combinable { + /** @var int 0,1,2 */ public $load_mode; - public $precedents = array(); - public $extra = array(); + /** @var array */ + public $precedents; + /** @var array */ + public $extra; - function __construct($load_mode, $id, $path, $version, $precedents) + /** + * @param int 0,1,2 + * @param string $id + * @param string $path + * @param string $version + * @param array $precedents + */ + function __construct($load_mode, $id, $path, $version=0, $precedents=array()) { parent::__construct($id, $path, $version); $this->load_mode = $load_mode; $this->precedents = $precedents; + $this->extra = array(); } } +/** + * Implementation of Combinable for CSS files. + */ final class Css extends Combinable { + /** @var int */ public $order; - function __construct($id, $path, $version, $order) + /** + * @param string $id + * @param string $path + * @param string $version + * @param int $order + */ + function __construct($id, $path, $version=0, $order=0) { parent::__construct($id, $path, $version); $this->order = $order; @@ -1272,12 +1334,14 @@ final class Css extends Combinable } -/** Manage a list of css files */ +/** + * Manages a list of CSS files and combining them in a unique file. + */ class CssLoader { + /** @param Css[] */ private $registered_css; - - /** used to keep declaration order */ + /** @param int used to keep declaration order */ private $counter; function __construct() @@ -1291,6 +1355,9 @@ class CssLoader $this->counter = 0; } + /** + * @return Combinable[] array of combined CSS. + */ function get_css() { uasort($this->registered_css, array('CssLoader', 'cmp_by_order')); @@ -1298,11 +1365,24 @@ class CssLoader return $combiner->combine(); } + /** + * Callback for CSS files sorting. + */ private static function cmp_by_order($a, $b) { return $a->order - $b->order; } + /** + * Adds a new file, if a file with the same $id already exsists, the one with + * the higher $order or higher $version is kept. + * + * @param string $id + * @param string $path + * @param string $version + * @param int $order + * @param bool $is_template + */ function add($id, $path, $version=0, $order=0, $is_template=false) { if (!isset($this->registered_css[$id])) @@ -1326,15 +1406,22 @@ class CssLoader } -/** Manage a list of required scripts for a page, by optimizing their loading location (head, bottom, async) -and later on by combining them in a unique file respecting at the same time dependencies.*/ +/** + * Manage a list of required scripts for a page, by optimizing their loading location (head, footer, async) + * and later on by combining them in a unique file respecting at the same time dependencies. + */ class ScriptLoader { + /** @var Script[] */ private $registered_scripts; + /** @var string[] */ public $inline_scripts; + /** @var bool */ private $did_head; + /** @var bool */ private $head_done_scripts; + /** @var bool */ private $did_footer; private static $known_paths = array( @@ -1363,11 +1450,26 @@ class ScriptLoader $this->did_head = $this->did_footer = false; } + /** + * @return bool + */ + function did_head() + { + return $this->did_head; + } + + /** + * @return Script[] + */ function get_all() { return $this->registered_scripts; } + /** + * @param string $code + * @param string[] $require + */ function add_inline($code, $require) { !$this->did_footer || trigger_error("Attempt to add inline script but the footer has been written", E_USER_WARNING); @@ -1385,6 +1487,13 @@ class ScriptLoader $this->inline_scripts[] = $code; } + /** + * @param string $id + * @param int $load_mode + * @param string[] $require + * @param string $path + * @param string $version + */ function add($id, $load_mode, $require, $path, $version=0) { if ($this->did_head && $load_mode==0) @@ -1430,11 +1539,11 @@ class ScriptLoader } } - function did_head() - { - return $this->did_head; - } - + /** + * Returns combined scripts loaded in header. + * + * @return Combinable[] + */ function get_head_scripts() { self::check_load_dep($this->registered_scripts); @@ -1458,6 +1567,11 @@ class ScriptLoader return self::do_combine($this->head_done_scripts, 0); } + /** + * Returns combined scripts loaded in footer. + * + * @return Combinable[] + */ function get_footer_scripts() { if (!$this->did_head) @@ -1489,13 +1603,23 @@ class ScriptLoader return array( self::do_combine($result[0],1), self::do_combine($result[1],2) ); } + /** + * @param Script[] $scripts + * @param int $load_mode + * @return Combinable[] + */ private static function do_combine($scripts, $load_mode) { $combiner = new FileCombiner('js', $scripts); return $combiner->combine(); } - // checks that if B depends on A, then B->load_mode >= A->load_mode in order to respect execution order + /** + * Checks dependencies among Scripts. + * Checks that if B depends on A, then B->load_mode >= A->load_mode in order to respect execution order. + * + * @param Script[] $scripts + */ private static function check_load_dep($scripts) { global $conf; @@ -1525,7 +1649,12 @@ class ScriptLoader while ($changed); } - + /** + * Fill a script dependancies with the known jQuery UI scripts. + * + * @param string $id in FileCombiner::$known_paths + * @param Script $script + */ private static function fill_well_known($id, $script) { if ( empty($script->path) && isset(self::$known_paths[$id])) @@ -1560,6 +1689,13 @@ class ScriptLoader } } + /** + * Add a known jQuery UI script to loaded scripts. + * + * @param string $id in FileCombiner::$known_paths + * @param int $load_mode + * @return bool + */ private function load_known_required_script($id, $load_mode) { if ( isset(self::$known_paths[$id]) or strncmp($id, 'jquery.ui.', 10)==0 ) @@ -1570,6 +1706,14 @@ class ScriptLoader return false; } + /** + * Compute script order depending on dependencies. + * Assigned to $script->extra['order']. + * + * @param string $script_id + * @param int $recursion_limiter + * @return int + */ private function compute_script_topological_order($script_id, $recursion_limiter=0) { if (!isset($this->registered_scripts[$script_id])) @@ -1590,6 +1734,9 @@ class ScriptLoader return ($script->extra['order'] = $max); } + /** + * Callback for scripts sorter. + */ private static function cmp_by_mode_and_order($s1, $s2) { $ret = $s1->load_mode - $s2->load_mode; @@ -1607,20 +1754,32 @@ class ScriptLoader } -/*Allows merging of javascript and css files into a single one.*/ +/** + * Allows merging of javascript and css files into a single one. + */ final class FileCombiner { - private $type; // js or css + /** @var string 'js' or 'css' */ + private $type; + /** @var bool */ private $is_css; + /** @var Combinable[] */ private $combinables; - function FileCombiner($type, $combinables=array()) + /** + * @param string $type 'js' or 'css' + * @param Combinable[] $combinables + */ + function __construct($type, $combinables=array()) { $this->type = $type; $this->is_css = $type=='css'; $this->combinables = $combinables; } + /** + * Deletes all combined files from cache directory. + */ static function clear_combined_files() { $dir = opendir(PHPWG_ROOT_PATH.PWG_COMBINED_DIR); @@ -1632,19 +1791,24 @@ final class FileCombiner closedir($dir); } - function add($combinables) + /** + * @param Combinable|Combinable[] $combinable + */ + function add($combinable) { - if ($combinables instanceof Combinable) + if (is_array($combinable)) { - $this->combinables[] = $combinables; + $this->combinables = array_merge($this->combinables, $combinable); } else { - foreach($combinables as $combinable) - $this->combinables[] = $combinable; + $this->combinables[] = $combinable; } } + /** + * @return Combinable[] + */ function combine() { global $conf; @@ -1685,6 +1849,14 @@ final class FileCombiner return $result; } + /** + * Process a set of pending files. + * + * @param array &$result + * @param array &$pending + * @param string[] $key + * @param bool $force + */ private function flush_pending(&$result, &$pending, $key, $force) { if (count($pending)>1) @@ -1715,6 +1887,14 @@ final class FileCombiner $pending = array(); } + /** + * Process one combinable file. + * + * @param Combinable $combinable + * @param bool $return_content + * @param bool $force + * @return null|string + */ private function process_combinable($combinable, $return_content, $force) { global $conf; @@ -1741,7 +1921,7 @@ final class FileCombiner $content = $template->parse($handle, true); if ($this->is_css) - $content = self::process_css($content, dirname($combinable->path) ); + $content = self::process_css($content, $combinable->path ); else $content = self::process_js($content, $combinable->path ); @@ -1754,13 +1934,20 @@ final class FileCombiner { $content = file_get_contents(PHPWG_ROOT_PATH . $combinable->path); if ($this->is_css) - $content = self::process_css($content, dirname($combinable->path) ); + $content = self::process_css($content, $combinable->path ); else $content = self::process_js($content, $combinable->path ); return $content; } } + /** + * Process a JS file. + * + * @param string $js file content + * @param string $file + * @return string + */ private static function process_js($js, $file) { if (strpos($file, '.min')===false and strpos($file, '.packed')===false ) @@ -1771,10 +1958,17 @@ final class FileCombiner return trim($js, " \t\r\n;").";\n"; } - private static function process_css($css, $dir) + /** + * Process a CSS file. + * + * @param string $css file content + * @param string $file + * @return string + */ + private static function process_css($css, $file) { - $css = self::process_css_rec($css, $dir); - if (version_compare(PHP_VERSION, '5.2.4', '>=')) + $css = self::process_css_rec($css, dirname($file)); + if (strpos($file, '.min')===false and version_compare(PHP_VERSION, '5.2.4', '>=')) { require_once(PHPWG_ROOT_PATH.'include/cssmin.class.php'); $css = CssMin::minify($css, array('Variables'=>false)); @@ -1783,6 +1977,13 @@ final class FileCombiner return $css; } + /** + * Resolves relative links in CSS file. + * + * @param string $css file content + * @param string $dir + * @return string + */ private static function process_css_rec($css, $dir) { static $PATTERN_URL = "#url\(\s*['|\"]{0,1}(.*?)['|\"]{0,1}\s*\)#"; @@ -1816,7 +2017,6 @@ final class FileCombiner } return $css; } - } ?> \ No newline at end of file -- cgit v1.2.3