Changeset 25815


Ignore:
Timestamp:
12/07/13 12:21:07 (6 years ago)
Author:
mistic100
Message:

feature 2999: finish documentation of template.class.php

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/include/template.class.php

    r25812 r25815  
    7676   * @var string $path 
    7777   */ 
    78   function __construct($root = ".", $theme= "", $path = "template") 
     78  function __construct($root=".", $theme="", $path="template") 
    7979  { 
    8080    global $conf, $lang_info; 
     
    11931193class PwgTemplateAdapter 
    11941194{ 
     1195  /** 
     1196   * @deprecated use "translate" modifier 
     1197   */ 
    11951198  function l10n($text) 
    11961199  { 
     
    11981201  } 
    11991202 
     1203  /** 
     1204   * @deprecated use "translate_dec" modifier 
     1205   */ 
    12001206  function l10n_dec($s, $p, $v) 
    12011207  { 
     
    12031209  } 
    12041210 
     1211  /** 
     1212   * @deprecated use "translate" or "sprintf" modifier 
     1213   */ 
    12051214  function sprintf() 
    12061215  { 
     
    12091218  } 
    12101219 
     1220  /** 
     1221   * @param string $type 
     1222   * @param array $img 
     1223   * @return DerivativeImage 
     1224   */ 
    12111225  function derivative($type, $img) 
    12121226  { 
     
    12141228  } 
    12151229 
     1230  /** 
     1231   * @param string $type 
     1232   * @param array $img 
     1233   * @return string 
     1234   */ 
    12161235  function derivative_url($type, $img) 
    12171236  { 
     
    12211240 
    12221241 
     1242/** 
     1243 * A Combinable represents a JS or CSS file ready for cobination and minification. 
     1244 */ 
    12231245class Combinable 
    12241246{ 
     1247  /** @var string */ 
    12251248  public $id; 
     1249  /** @var string */ 
    12261250  public $path; 
     1251  /** @var string */ 
    12271252  public $version; 
     1253  /** @var bool */ 
    12281254  public $is_template; 
    12291255 
    1230   function __construct($id, $path, $version) 
     1256  /** 
     1257   * @param string $id 
     1258   * @param string $path 
     1259   * @param string $version 
     1260   */ 
     1261  function __construct($id, $path, $version=0) 
    12311262  { 
    12321263    $this->id = $id; 
    12331264    $this->set_path($path); 
    12341265    $this->version = $version; 
    1235   } 
    1236  
     1266    $this->is_template = false; 
     1267  } 
     1268 
     1269  /** 
     1270   * @param string $path 
     1271   */ 
    12371272  function set_path($path) 
    12381273  { 
     
    12411276  } 
    12421277 
     1278  /** 
     1279   * @return bool 
     1280   */ 
    12431281  function is_remote() 
    12441282  { 
    1245     return url_is_remote( $this->path ) || strncmp($this->path, '//', 2)==0; 
     1283    return url_is_remote($this->path) || strncmp($this->path, '//', 2)==0; 
    12461284  } 
    12471285} 
    12481286 
     1287/** 
     1288 * Implementation of Combinable for JS files. 
     1289 */ 
    12491290final class Script extends Combinable 
    12501291{ 
     1292  /** @var int 0,1,2 */ 
    12511293  public $load_mode; 
    1252   public $precedents = array(); 
    1253   public $extra = array(); 
    1254  
    1255   function __construct($load_mode, $id, $path, $version, $precedents) 
     1294  /** @var array */ 
     1295  public $precedents; 
     1296  /** @var array */ 
     1297  public $extra; 
     1298 
     1299  /** 
     1300   * @param int 0,1,2 
     1301   * @param string $id 
     1302   * @param string $path 
     1303   * @param string $version 
     1304   * @param array $precedents 
     1305   */ 
     1306  function __construct($load_mode, $id, $path, $version=0, $precedents=array()) 
    12561307  { 
    12571308    parent::__construct($id, $path, $version); 
    12581309    $this->load_mode = $load_mode; 
    12591310    $this->precedents = $precedents; 
     1311    $this->extra = array(); 
    12601312  } 
    12611313} 
    12621314 
     1315/** 
     1316 * Implementation of Combinable for CSS files. 
     1317 */ 
    12631318final class Css extends Combinable 
    12641319{ 
     1320  /** @var int */ 
    12651321  public $order; 
    12661322 
    1267   function __construct($id, $path, $version, $order) 
     1323  /** 
     1324   * @param string $id 
     1325   * @param string $path 
     1326   * @param string $version 
     1327   * @param int $order 
     1328   */ 
     1329  function __construct($id, $path, $version=0, $order=0) 
    12681330  { 
    12691331    parent::__construct($id, $path, $version); 
     
    12731335 
    12741336 
    1275 /** Manage a list of css files */ 
     1337/** 
     1338 * Manages a list of CSS files and combining them in a unique file. 
     1339 */ 
    12761340class CssLoader 
    12771341{ 
     1342  /** @param Css[] */ 
    12781343  private $registered_css; 
    1279    
    1280   /** used to keep declaration order */ 
     1344  /** @param int used to keep declaration order */ 
    12811345  private $counter; 
    12821346   
     
    12921356  } 
    12931357   
     1358  /** 
     1359   * @return Combinable[] array of combined CSS. 
     1360   */ 
    12941361  function get_css() 
    12951362  { 
     
    12991366  } 
    13001367   
     1368  /** 
     1369   * Callback for CSS files sorting. 
     1370   */ 
    13011371  private static function cmp_by_order($a, $b) 
    13021372  { 
     
    13041374  } 
    13051375   
     1376  /** 
     1377   * Adds a new file, if a file with the same $id already exsists, the one with 
     1378   * the higher $order or higher $version is kept. 
     1379   * 
     1380   * @param string $id 
     1381   * @param string $path 
     1382   * @param string $version 
     1383   * @param int $order 
     1384   * @param bool $is_template 
     1385   */ 
    13061386  function add($id, $path, $version=0, $order=0, $is_template=false) 
    13071387  { 
     
    13271407 
    13281408 
    1329 /** Manage a list of required scripts for a page, by optimizing their loading location (head, bottom, async) 
    1330 and later on by combining them in a unique file respecting at the same time dependencies.*/ 
     1409/** 
     1410 * Manage a list of required scripts for a page, by optimizing their loading location (head, footer, async) 
     1411 * and later on by combining them in a unique file respecting at the same time dependencies. 
     1412 */ 
    13311413class ScriptLoader 
    13321414{ 
     1415  /** @var Script[] */ 
    13331416  private $registered_scripts; 
     1417  /** @var string[] */ 
    13341418  public $inline_scripts; 
    13351419 
     1420  /** @var bool */ 
    13361421  private $did_head; 
     1422  /** @var bool */ 
    13371423  private $head_done_scripts; 
     1424  /** @var bool */ 
    13381425  private $did_footer; 
    13391426 
     
    13641451  } 
    13651452 
     1453  /** 
     1454   * @return bool 
     1455   */ 
     1456  function did_head() 
     1457  { 
     1458    return $this->did_head; 
     1459  } 
     1460 
     1461  /** 
     1462   * @return Script[] 
     1463   */ 
    13661464  function get_all() 
    13671465  { 
     
    13691467  } 
    13701468 
     1469  /** 
     1470   * @param string $code 
     1471   * @param string[] $require 
     1472   */ 
    13711473  function add_inline($code, $require) 
    13721474  { 
     
    13861488  } 
    13871489 
     1490  /** 
     1491   * @param string $id 
     1492   * @param int $load_mode 
     1493   * @param string[] $require 
     1494   * @param string $path 
     1495   * @param string $version 
     1496   */ 
    13881497  function add($id, $load_mode, $require, $path, $version=0) 
    13891498  { 
     
    14311540  } 
    14321541 
    1433   function did_head() 
    1434   { 
    1435     return $this->did_head; 
    1436   } 
    1437  
     1542  /** 
     1543   * Returns combined scripts loaded in header. 
     1544   * 
     1545   * @return Combinable[] 
     1546   */ 
    14381547  function get_head_scripts() 
    14391548  { 
     
    14591568  } 
    14601569 
     1570  /** 
     1571   * Returns combined scripts loaded in footer. 
     1572   * 
     1573   * @return Combinable[] 
     1574   */ 
    14611575  function get_footer_scripts() 
    14621576  { 
     
    14901604  } 
    14911605 
     1606  /** 
     1607   * @param Script[] $scripts 
     1608   * @param int $load_mode 
     1609   * @return Combinable[] 
     1610   */ 
    14921611  private static function do_combine($scripts, $load_mode) 
    14931612  { 
     
    14961615  } 
    14971616 
    1498   // checks that if B depends on A, then B->load_mode >= A->load_mode in order to respect execution order 
     1617  /** 
     1618   * Checks dependencies among Scripts. 
     1619   * Checks that if B depends on A, then B->load_mode >= A->load_mode in order to respect execution order. 
     1620   * 
     1621   * @param Script[] $scripts 
     1622   */ 
    14991623  private static function check_load_dep($scripts) 
    15001624  { 
     
    15261650  } 
    15271651 
    1528  
     1652  /** 
     1653   * Fill a script dependancies with the known jQuery UI scripts. 
     1654   * 
     1655   * @param string $id in FileCombiner::$known_paths 
     1656   * @param Script $script 
     1657   */ 
    15291658  private static function fill_well_known($id, $script) 
    15301659  { 
     
    15611690  } 
    15621691 
     1692  /** 
     1693   * Add a known jQuery UI script to loaded scripts. 
     1694   * 
     1695   * @param string $id in FileCombiner::$known_paths 
     1696   * @param int $load_mode 
     1697   * @return bool 
     1698   */ 
    15631699  private function load_known_required_script($id, $load_mode) 
    15641700  { 
     
    15711707  } 
    15721708 
     1709  /** 
     1710   * Compute script order depending on dependencies. 
     1711   * Assigned to $script->extra['order']. 
     1712   * 
     1713   * @param string $script_id 
     1714   * @param int $recursion_limiter 
     1715   * @return int 
     1716   */ 
    15731717  private function compute_script_topological_order($script_id, $recursion_limiter=0) 
    15741718  { 
     
    15911735  } 
    15921736 
     1737  /** 
     1738   * Callback for scripts sorter. 
     1739   */ 
    15931740  private static function cmp_by_mode_and_order($s1, $s2) 
    15941741  { 
     
    16081755 
    16091756 
    1610 /*Allows merging of javascript and css files into a single one.*/ 
     1757/** 
     1758 * Allows merging of javascript and css files into a single one. 
     1759 */ 
    16111760final class FileCombiner 
    16121761{ 
    1613   private $type; // js or css 
     1762  /** @var string 'js' or 'css' */ 
     1763  private $type; 
     1764  /** @var bool */ 
    16141765  private $is_css; 
     1766  /** @var Combinable[] */ 
    16151767  private $combinables; 
    16161768 
    1617   function FileCombiner($type, $combinables=array()) 
     1769  /** 
     1770   * @param string $type 'js' or 'css' 
     1771   * @param Combinable[] $combinables 
     1772   */ 
     1773  function __construct($type, $combinables=array()) 
    16181774  { 
    16191775    $this->type = $type; 
     
    16221778  } 
    16231779 
     1780  /** 
     1781   * Deletes all combined files from cache directory. 
     1782   */ 
    16241783  static function clear_combined_files() 
    16251784  { 
     
    16331792  } 
    16341793 
    1635   function add($combinables) 
    1636   { 
    1637     if ($combinables instanceof Combinable) 
    1638     { 
    1639       $this->combinables[] = $combinables; 
     1794  /** 
     1795   * @param Combinable|Combinable[] $combinable 
     1796   */ 
     1797  function add($combinable) 
     1798  { 
     1799    if (is_array($combinable)) 
     1800    { 
     1801      $this->combinables = array_merge($this->combinables, $combinable); 
    16401802    } 
    16411803    else 
    16421804    { 
    1643       foreach($combinables as $combinable) 
    1644         $this->combinables[] = $combinable; 
    1645     } 
    1646   } 
    1647  
     1805      $this->combinables[] = $combinable; 
     1806    } 
     1807  } 
     1808 
     1809  /** 
     1810   * @return Combinable[] 
     1811   */ 
    16481812  function combine() 
    16491813  { 
     
    16861850  } 
    16871851 
     1852  /** 
     1853   * Process a set of pending files. 
     1854   * 
     1855   * @param array &$result 
     1856   * @param array &$pending 
     1857   * @param string[] $key 
     1858   * @param bool $force 
     1859   */ 
    16881860  private function flush_pending(&$result, &$pending, $key, $force) 
    16891861  { 
     
    17161888  } 
    17171889 
     1890  /** 
     1891   * Process one combinable file. 
     1892   * 
     1893   * @param Combinable $combinable 
     1894   * @param bool $return_content 
     1895   * @param bool $force 
     1896   * @return null|string 
     1897   */ 
    17181898  private function process_combinable($combinable, $return_content, $force) 
    17191899  { 
     
    17421922 
    17431923      if ($this->is_css) 
    1744         $content = self::process_css($content, dirname($combinable->path) ); 
     1924        $content = self::process_css($content, $combinable->path ); 
    17451925      else 
    17461926        $content = self::process_js($content, $combinable->path ); 
     
    17551935      $content = file_get_contents(PHPWG_ROOT_PATH . $combinable->path); 
    17561936      if ($this->is_css) 
    1757         $content = self::process_css($content, dirname($combinable->path) ); 
     1937        $content = self::process_css($content, $combinable->path ); 
    17581938      else 
    17591939        $content = self::process_js($content, $combinable->path ); 
     
    17621942  } 
    17631943 
     1944  /** 
     1945   * Process a JS file. 
     1946   * 
     1947   * @param string $js file content 
     1948   * @param string $file 
     1949   * @return string 
     1950   */ 
    17641951  private static function process_js($js, $file) 
    17651952  { 
     
    17721959  } 
    17731960 
    1774   private static function process_css($css, $dir) 
    1775   { 
    1776     $css = self::process_css_rec($css, $dir); 
    1777     if (version_compare(PHP_VERSION, '5.2.4', '>=')) 
     1961  /** 
     1962   * Process a CSS file. 
     1963   * 
     1964   * @param string $css file content 
     1965   * @param string $file 
     1966   * @return string 
     1967   */ 
     1968  private static function process_css($css, $file) 
     1969  { 
     1970    $css = self::process_css_rec($css, dirname($file)); 
     1971    if (strpos($file, '.min')===false and version_compare(PHP_VERSION, '5.2.4', '>=')) 
    17781972    { 
    17791973      require_once(PHPWG_ROOT_PATH.'include/cssmin.class.php'); 
     
    17841978  } 
    17851979 
     1980  /** 
     1981   * Resolves relative links in CSS file. 
     1982   * 
     1983   * @param string $css file content 
     1984   * @param string $dir 
     1985   * @return string 
     1986   */ 
    17861987  private static function process_css_rec($css, $dir) 
    17871988  { 
     
    18172018    return $css; 
    18182019  } 
    1819  
    18202020} 
    18212021 
Note: See TracChangeset for help on using the changeset viewer.