Changeset 25815


Ignore:
Timestamp:
Dec 7, 2013, 12:21:07 PM (10 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.