CRM/Core/Resources.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.3                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2013                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26 */
  27
  28 /**
  29  * This class facilitates the loading of resources
  30  * such as JavaScript files and CSS files.
  31  *
  32  * Any URLs generated for resources may include a 'cache-code'. By resetting the
  33  * cache-code, one may force clients to re-download resource files (regardless of
  34  * any HTTP caching rules).
  35  *
  36  * TODO: This is currently a thin wrapper over CRM_Core_Region. We
  37  * should incorporte services for aggregation, minimization, etc.
  38  *
  39  * @package CRM
  40  * @copyright CiviCRM LLC (c) 2004-2013
  41  * $Id$
  42  *
  43  */
  44 class CRM_Core_Resources {
  45   const DEFAULT_WEIGHT = 0;
  46   const DEFAULT_REGION = 'page-footer';
  47
  48   /**
  49    * We don't have a container or dependency-injection, so use singleton instead
  50    *
  51    * @var object
  52    * @static
  53    */
  54   private static $_singleton = NULL;
  55
  56   /**
  57    * @var CRM_Extension_Mapper
  58    */
  59   private $extMapper = NULL;
  60
  61   /**
  62    * @var CRM_Utils_Cache_Interface
  63    */
  64   private $cache = NULL;
  65
  66   /**
  67    * @var array free-form data tree
  68    */
  69   protected $settings = array();
  70   protected $addedSettings = FALSE;
  71
  72   /**
  73    * @var array of callables
  74    */
  75   protected $settingsFactories = array();
  76
  77   /**
  78    * @var array ($regionName => bool)
  79    */
  80   protected $addedCoreResources = array();
  81
  82   /**
  83    * @var array ($regionName => bool)
  84    */
  85   protected $addedCoreStyles = array();
  86
  87   /**
  88    * @var string a value to append to JS/CSS URLs to coerce cache resets
  89    */
  90   protected $cacheCode = NULL;
  91
  92   /**
  93    * @var string the name of a setting which persistently stores the cacheCode
  94    */
  95   protected $cacheCodeKey = NULL;
  96
  97   /**
  98    * Get or set the single instance of CRM_Core_Resources
  99    *
 100    * @param $instance CRM_Core_Resources, new copy of the manager
 101    * @return CRM_Core_Resources
 102    */
 103   static public function singleton(CRM_Core_Resources $instance = NULL) {
 104     if ($instance !== NULL) {
 105       self::$_singleton = $instance;
 106     }
 107     if (self::$_singleton === NULL) {
 108       $sys = CRM_Extension_System::singleton();
 109       $cache = new CRM_Utils_Cache_SqlGroup(array(
 110         'group' => 'js-strings',
 111         'prefetch' => FALSE,
 112       ));
 113       self::$_singleton = new CRM_Core_Resources(
 114         $sys->getMapper(),
 115         $cache,
 116         CRM_Core_Config::isUpgradeMode() ? NULL : 'resCacheCode'
 117       );
 118     }
 119     return self::$_singleton;
 120   }
 121
 122   /**
 123    * Construct a resource manager
 124    *
 125    * @param CRM_Extension_Mapper $extMapper Map extension names to their base path or URLs.
 126    */
 127   public function __construct($extMapper, $cache, $cacheCodeKey = NULL) {
 128     $this->extMapper = $extMapper;
 129     $this->cache = $cache;
 130     $this->cacheCodeKey = $cacheCodeKey;
 131     if ($cacheCodeKey !== NULL) {
 132       $this->cacheCode = CRM_Core_BAO_Setting::getItem(CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME, $cacheCodeKey);
 133     }
 134     if (!$this->cacheCode) {
 135       $this->resetCacheCode();
 136     }
 137   }
 138
 139   /**
 140    * Add a JavaScript file to the current page using <SCRIPT SRC>.
 141    *
 142    * @param $ext string, extension name; use 'civicrm' for core
 143    * @param $file string, file path -- relative to the extension base dir
 144    * @param $weight int, relative weight within a given region
 145    * @param $region string, location within the file; 'html-header', 'page-header', 'page-footer'
 146    * @param $translate, whether to parse this file for strings enclosed in ts()
 147    *
 148    * @return CRM_Core_Resources
 149    */
 150   public function addScriptFile($ext, $file, $weight = self::DEFAULT_WEIGHT, $region = self::DEFAULT_REGION, $translate = TRUE) {
 151     if ($translate) {
 152       $this->translateScript($ext, $file);
 153     }
 154     return $this->addScriptUrl($this->getUrl($ext, $file, TRUE), $weight, $region);
 155   }
 156
 157   /**
 158    * Add a JavaScript file to the current page using <SCRIPT SRC>.
 159    *
 160    * @param $url string
 161    * @param $weight int, relative weight within a given region
 162    * @param $region string, location within the file; 'html-header', 'page-header', 'page-footer'
 163    * @return CRM_Core_Resources
 164    */
 165   public function addScriptUrl($url, $weight = self::DEFAULT_WEIGHT, $region = self::DEFAULT_REGION) {
 166     CRM_Core_Region::instance($region)->add(array(
 167       'name' => $url,
 168       'type' => 'scriptUrl',
 169       'scriptUrl' => $url,
 170       'weight' => $weight,
 171       'region' => $region,
 172     ));
 173     return $this;
 174   }
 175
 176   /**
 177    * Add a JavaScript file to the current page using <SCRIPT SRC>.
 178    *
 179    * @param $code string, JavaScript source code
 180    * @param $weight int, relative weight within a given region
 181    * @param $region string, location within the file; 'html-header', 'page-header', 'page-footer'
 182    * @return CRM_Core_Resources
 183    */
 184   public function addScript($code, $weight = self::DEFAULT_WEIGHT, $region = self::DEFAULT_REGION) {
 185     CRM_Core_Region::instance($region)->add(array(
 186       // 'name' => automatic
 187       'type' => 'script',
 188       'script' => $code,
 189       'weight' => $weight,
 190       'region' => $region,
 191     ));
 192     return $this;
 193   }
 194
 195   /**
 196    * Add JavaScript variables to the global CRM object.
 197    *
 198    * @param $settings array
 199    * @return CRM_Core_Resources
 200    */
 201   public function addSetting($settings) {
 202     $this->settings = $this->mergeSettings($this->settings, $settings);
 203     if (!$this->addedSettings) {
 204       $resources = $this;
 205       CRM_Core_Region::instance('html-header')->add(array(
 206         'callback' => function(&$snippet, &$html) use ($resources) {
 207           $html .= "\n" . $resources->renderSetting();
 208         },
 209         'weight' => -100000,
 210       ));
 211       $this->addedSettings = TRUE;
 212     }
 213     return $this;
 214   }
 215
 216   /**
 217    * Add JavaScript variables to the global CRM object.
 218    *
 219    * @param $callable function
 220    * @return CRM_Core_Resources
 221    */
 222   public function addSettingsFactory($callable) {
 223     // Make sure our callback has been registered
 224     $this->addSetting(array());
 225     $this->settingsFactories[] = $callable;
 226     return $this;
 227   }
 228
 229   public function getSettings() {
 230     $result = $this->settings;
 231     foreach ($this->settingsFactories as $callable) {
 232       $result = $this->mergeSettings($result, $callable());
 233     }
 234     return $result;
 235   }
 236
 237   /**
 238    * @param array $settings
 239    * @param array $additions
 240    * @return array combination of $settings and $additions
 241    */
 242   protected function mergeSettings($settings, $additions) {
 243     foreach ($additions as $k => $v) {
 244       if (isset($settings[$k]) && is_array($settings[$k]) && is_array($v)) {
 245         $v += $settings[$k];
 246       }
 247       $settings[$k] = $v;
 248     }
 249     return $settings;
 250   }
 251
 252   /**
 253    * Helper fn for addSetting
 254    * Render JavaScript variables for the global CRM object.
 255    *
 256    * Example:
 257    * From the server:
 258    * CRM_Core_Resources::singleton()->addSetting(array('myNamespace' => array('foo' => 'bar')));
 259    * From javascript:
 260    * CRM.myNamespace.foo // "bar"
 261    *
 262    * @return string
 263    */
 264   public function renderSetting() {
 265     $js = 'var CRM = ' . json_encode($this->getSettings()) . ';';
 266     return sprintf("<script type=\"text/javascript\">\n%s\n</script>\n", $js);
 267   }
 268
 269   /**
 270    * Add translated string to the js CRM object.
 271    * It can then be retrived from the client-side ts() function
 272    * Variable substitutions can happen from client-side
 273    *
 274    * Note: this function rarely needs to be called directly and is mostly for internal use.
 275    * @see CRM_Core_Resources::addScriptFile which automatically adds translated strings from js files
 276    *
 277    * Simple example:
 278    * // From php:
 279    * CRM_Core_Resources::singleton()->addString('Hello');
 280    * // The string is now available to javascript code i.e.
 281    * ts('Hello');
 282    *
 283    * Example with client-side substitutions:
 284    * // From php:
 285    * CRM_Core_Resources::singleton()->addString('Your %1 has been %2');
 286    * // ts() in javascript works the same as in php, for example:
 287    * ts('Your %1 has been %2', {1: objectName, 2: actionTaken});
 288    *
 289    * NOTE: This function does not work with server-side substitutions
 290    * (as this might result in collisions and unwanted variable injections)
 291    * Instead, use code like:
 292    * CRM_Core_Resources::singleton()->addSetting(array('myNamespace' => array('myString' => ts('Your %1 has been %2', array(subs)))));
 293    * And from javascript access it at CRM.myNamespace.myString
 294    *
 295    * @param $text string|array
 296    * @return CRM_Core_Resources
 297    */
 298   public function addString($text) {
 299     foreach ((array) $text as $str) {
 300       $translated = ts($str);
 301       // We only need to push this string to client if the translation
 302       // is actually different from the original
 303       if ($translated != $str) {
 304         $this->addSetting(array('strings' => array($str => $translated)));
 305       }
 306     }
 307     return $this;
 308   }
 309
 310   /**
 311    * Add a CSS file to the current page using <LINK HREF>.
 312    *
 313    * @param $ext string, extension name; use 'civicrm' for core
 314    * @param $file string, file path -- relative to the extension base dir
 315    * @param $weight int, relative weight within a given region
 316    * @param $region string, location within the file; 'html-header', 'page-header', 'page-footer'
 317    * @return CRM_Core_Resources
 318    */
 319   public function addStyleFile($ext, $file, $weight = self::DEFAULT_WEIGHT, $region = self::DEFAULT_REGION) {
 320     return $this->addStyleUrl($this->getUrl($ext, $file, TRUE), $weight, $region);
 321   }
 322
 323   /**
 324    * Add a CSS file to the current page using <LINK HREF>.
 325    *
 326    * @param $url string
 327    * @param $weight int, relative weight within a given region
 328    * @param $region string, location within the file; 'html-header', 'page-header', 'page-footer'
 329    * @return CRM_Core_Resources
 330    */
 331   public function addStyleUrl($url, $weight = self::DEFAULT_WEIGHT, $region = self::DEFAULT_REGION) {
 332     CRM_Core_Region::instance($region)->add(array(
 333       'name' => $url,
 334       'type' => 'styleUrl',
 335       'styleUrl' => $url,
 336       'weight' => $weight,
 337       'region' => $region,
 338     ));
 339     return $this;
 340   }
 341
 342   /**
 343    * Add a CSS content to the current page using <STYLE>.
 344    *
 345    * @param $code string, CSS source code
 346    * @param $weight int, relative weight within a given region
 347    * @param $region string, location within the file; 'html-header', 'page-header', 'page-footer'
 348    * @return CRM_Core_Resources
 349    */
 350   public function addStyle($code, $weight = self::DEFAULT_WEIGHT, $region = self::DEFAULT_REGION) {
 351     CRM_Core_Region::instance($region)->add(array(
 352       // 'name' => automatic
 353       'type' => 'style',
 354       'style' => $code,
 355       'weight' => $weight,
 356       'region' => $region,
 357     ));
 358     return $this;
 359   }
 360
 361   /**
 362    * Determine file path of a resource provided by an extension
 363    *
 364    * @param $ext string, extension name; use 'civicrm' for core
 365    * @param $file string, file path -- relative to the extension base dir
 366    *
 367    * @return (string|bool), full file path or FALSE if not found
 368    */
 369   public function getPath($ext, $file) {
 370     // TODO consider caching results
 371     $path = $this->extMapper->keyToBasePath($ext) . '/' . $file;
 372     if (is_file($path)) {
 373       return $path;
 374     }
 375     return FALSE;
 376   }
 377
 378   /**
 379    * Determine public URL of a resource provided by an extension
 380    *
 381    * @param $ext string, extension name; use 'civicrm' for core
 382    * @param $file string, file path -- relative to the extension base dir
 383    * @return string, URL
 384    */
 385   public function getUrl($ext, $file = NULL, $addCacheCode = FALSE) {
 386     if ($file === NULL) {
 387       $file = '';
 388     }
 389     if ($addCacheCode) {
 390       $file .= '?r=' . $this->getCacheCode();
 391     }
 392     // TODO consider caching results
 393     return $this->extMapper->keyToUrl($ext) . '/' . $file;
 394   }
 395
 396   public function getCacheCode() {
 397     return $this->cacheCode;
 398   }
 399
 400   public function setCacheCode($value) {
 401     $this->cacheCode = $value;
 402     if ($this->cacheCodeKey) {
 403       CRM_Core_BAO_Setting::setItem($value, CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME, $this->cacheCodeKey);
 404     }
 405   }
 406
 407   public function resetCacheCode() {
 408     $this->setCacheCode(CRM_Utils_String::createRandom(5, CRM_Utils_String::ALPHANUMERIC));
 409   }
 410
 411   /**
 412    * This adds CiviCRM's standard css and js to the specified region of the document.
 413    * It will only run once.
 414    *
 415    * TODO: Separate the functional code (like addStyle/addScript) from the policy code
 416    * (like addCoreResources/addCoreStyles).
 417    *
 418    * @return CRM_Core_Resources
 419    * @access public
 420    */
 421   public function addCoreResources($region = 'html-header') {
 422     if (!isset($this->addedCoreResources[$region])) {
 423       $this->addedCoreResources[$region] = TRUE;
 424       $config = CRM_Core_Config::singleton();
 425
 426       // Add resources from jquery.files.tpl
 427       $files = self::parseTemplate('CRM/common/jquery.files.tpl');
 428       $jsWeight = -9999;
 429       foreach ($files as $file => $type) {
 430         if ($type == 'js') {
 431           // Don't bother  looking for ts() calls in packages, there aren't any
 432           $translate = (substr($file, 0, 9) != 'packages/');
 433           $this->addScriptFile('civicrm', $file, $jsWeight++, $region, $translate);
 434         }
 435         elseif ($type == 'css') {
 436           $this->addStyleFile('civicrm', $file, -100, $region);
 437         }
 438       }
 439
 440       // Add localized calendar js
 441       // Search for i18n file in order of specificity (try fr-CA, then fr)
 442       list($lang) = explode('_', $config->lcMessages);
 443       foreach (array(str_replace('_', '-', $config->lcMessages), $lang) as $language) {
 444         $localizationFile = "packages/jquery/jquery-ui-1.9.0/development-bundle/ui/i18n/jquery.ui.datepicker-{$language}.js";
 445         if ($this->getPath('civicrm', $localizationFile)) {
 446           $this->addScriptFile('civicrm', $localizationFile, $jsWeight++, $region, FALSE);
 447           break;
 448         }
 449       }
 450
 451       // Initialize CRM.url
 452       $url = CRM_Utils_System::url('civicrm/example', 'placeholder', FALSE, NULL, FALSE);
 453       $js = "CRM.url('init', '$url');";
 454       $this->addScript($js, $jsWeight++, $region);
 455
 456       // Add global settings
 457       $settings = array(
 458         'userFramework' => $config->userFramework,
 459         'resourceBase' => $config->resourceBase,
 460       );
 461       $this->addSetting(array('config' => $settings));
 462
 463       // Give control of jQuery back to the CMS - this loads last
 464       $this->addScriptFile('civicrm', 'js/noconflict.js', 9999, $region, FALSE);
 465
 466       $this->addCoreStyles($region);
 467     }
 468     return $this;
 469   }
 470
 471   /**
 472    * This will add CiviCRM's standard CSS
 473    *
 474    * TODO: Separate the functional code (like addStyle/addScript) from the policy code
 475    * (like addCoreResources/addCoreStyles).
 476    *
 477    * @param string $region
 478    * @return CRM_Core_Resources
 479    */
 480   public function addCoreStyles($region = 'html-header') {
 481     if (!isset($this->addedCoreStyles[$region])) {
 482       $this->addedCoreStyles[$region] = TRUE;
 483
 484       // Load custom or core css
 485       $config = CRM_Core_Config::singleton();
 486       if (!empty($config->customCSSURL)) {
 487         $this->addStyleUrl($config->customCSSURL, -99, $region);
 488       }
 489       else {
 490         $this->addStyleFile('civicrm', 'css/civicrm.css', -99, $region);
 491         $this->addStyleFile('civicrm', 'css/extras.css', -98, $region);
 492       }
 493     }
 494     return $this;
 495   }
 496
 497   /**
 498    * Flushes cached translated strings
 499    */
 500   public function flushStrings() {
 501     $this->cache->flush();
 502   }
 503
 504   /**
 505    * Translate strings in a javascript file
 506    *
 507    * @param $ext string, extension name
 508    * @param $file string, file path
 509    * @return void
 510    */
 511   private function translateScript($ext, $file) {
 512     // For each extension, maintain one cache record which
 513     // includes parsed (translatable) strings for all its JS files.
 514     $stringsByFile = $this->cache->get($ext); // array($file => array(...strings...))
 515     if (!$stringsByFile) {
 516       $stringsByFile = array();
 517     }
 518     if (!isset($stringsByFile[$file])) {
 519       $filePath = $this->getPath($ext, $file);
 520       if ($filePath && is_readable($filePath)) {
 521         $stringsByFile[$file] = CRM_Utils_JS::parseStrings(file_get_contents($filePath));
 522       } else {
 523         $stringsByFile[$file] = array();
 524       }
 525       $this->cache->set($ext, $stringsByFile);
 526     }
 527     $this->addString($stringsByFile[$file]);
 528   }
 529
 530   /**
 531    * Read resource files from a template
 532    *
 533    * @param $tpl (str) template file name
 534    * @return array: filename => filetype
 535    */
 536   static function parseTemplate($tpl) {
 537     $items = array();
 538     $template = CRM_Core_Smarty::singleton();
 539     $buffer = $template->fetch($tpl);
 540     $lines = preg_split('/\s+/', $buffer);
 541     foreach ($lines as $line) {
 542       $line = trim($line);
 543       if ($line) {
 544         $items[$line] = substr($line, 1 + strrpos($line, '.'));
 545       }
 546     }
 547     return $items;
 548   }
 549 }