CRM/Core/Resources.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.5                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   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-2014
  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    * @var bool
  99    */
 100   public $ajaxPopupsEnabled;
 101
 102   /**
 103    * Get or set the single instance of CRM_Core_Resources
 104    *
 105    * @param $instance CRM_Core_Resources, new copy of the manager
 106    * @return CRM_Core_Resources
 107    */
 108   static public function singleton(CRM_Core_Resources $instance = NULL) {
 109     if ($instance !== NULL) {
 110       self::$_singleton = $instance;
 111     }
 112     if (self::$_singleton === NULL) {
 113       $sys = CRM_Extension_System::singleton();
 114       $cache = new CRM_Utils_Cache_SqlGroup(array(
 115         'group' => 'js-strings',
 116         'prefetch' => FALSE,
 117       ));
 118       self::$_singleton = new CRM_Core_Resources(
 119         $sys->getMapper(),
 120         $cache,
 121         CRM_Core_Config::isUpgradeMode() ? NULL : 'resCacheCode'
 122       );
 123     }
 124     return self::$_singleton;
 125   }
 126
 127   /**
 128    * Construct a resource manager
 129    *
 130    * @param CRM_Extension_Mapper $extMapper Map extension names to their base path or URLs.
 131    * @param CRM_Utils_Cache_Interface $cache JS-localization cache
 132    * @param string|null $cacheCodeKey Random code to append to resource URLs; changing the code forces clients to reload resources
 133    */
 134   public function __construct($extMapper, $cache, $cacheCodeKey = NULL) {
 135     $this->extMapper = $extMapper;
 136     $this->cache = $cache;
 137     $this->cacheCodeKey = $cacheCodeKey;
 138     if ($cacheCodeKey !== NULL) {
 139       $this->cacheCode = CRM_Core_BAO_Setting::getItem(CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME, $cacheCodeKey);
 140     }
 141     if (!$this->cacheCode) {
 142       $this->resetCacheCode();
 143     }
 144     $this->ajaxPopupsEnabled = (bool) CRM_Core_BAO_Setting::getItem(
 145       CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME, 'ajaxPopupsEnabled', NULL, TRUE
 146     );
 147   }
 148
 149   /**
 150    * Add a JavaScript file to the current page using <SCRIPT SRC>.
 151    *
 152    * @param $ext string, extension name; use 'civicrm' for core
 153    * @param $file string, file path -- relative to the extension base dir
 154    * @param $weight int, relative weight within a given region
 155    * @param $region string, location within the file; 'html-header', 'page-header', 'page-footer'
 156    * @param $translate, whether to parse this file for strings enclosed in ts()
 157    *
 158    * @return CRM_Core_Resources
 159    */
 160   public function addScriptFile($ext, $file, $weight = self::DEFAULT_WEIGHT, $region = self::DEFAULT_REGION, $translate = TRUE) {
 161     if ($translate) {
 162       $this->translateScript($ext, $file);
 163     }
 164     // Look for non-minified version if we are in debug mode
 165     if (CRM_Core_Config::singleton()->debug && strpos($file, '.min.js') !== FALSE) {
 166       $nonMiniFile = str_replace('.min.js', '.js', $file);
 167       if ($this->getPath($ext, $nonMiniFile)) {
 168         $file = $nonMiniFile;
 169       }
 170     }
 171     return $this->addScriptUrl($this->getUrl($ext, $file, TRUE), $weight, $region);
 172   }
 173
 174   /**
 175    * Add a JavaScript file to the current page using <SCRIPT SRC>.
 176    *
 177    * @param $url string
 178    * @param $weight int, relative weight within a given region
 179    * @param $region string, location within the file; 'html-header', 'page-header', 'page-footer'
 180    * @return CRM_Core_Resources
 181    */
 182   public function addScriptUrl($url, $weight = self::DEFAULT_WEIGHT, $region = self::DEFAULT_REGION) {
 183     CRM_Core_Region::instance($region)->add(array(
 184       'name' => $url,
 185       'type' => 'scriptUrl',
 186       'scriptUrl' => $url,
 187       'weight' => $weight,
 188       'region' => $region,
 189     ));
 190     return $this;
 191   }
 192
 193   /**
 194    * Add a JavaScript file to the current page using <SCRIPT SRC>.
 195    *
 196    * @param $code string, JavaScript source code
 197    * @param $weight int, relative weight within a given region
 198    * @param $region string, location within the file; 'html-header', 'page-header', 'page-footer'
 199    * @return CRM_Core_Resources
 200    */
 201   public function addScript($code, $weight = self::DEFAULT_WEIGHT, $region = self::DEFAULT_REGION) {
 202     CRM_Core_Region::instance($region)->add(array(
 203       // 'name' => automatic
 204       'type' => 'script',
 205       'script' => $code,
 206       'weight' => $weight,
 207       'region' => $region,
 208     ));
 209     return $this;
 210   }
 211
 212   /**
 213    * Add JavaScript variables to the global CRM object.
 214    *
 215    * Example:
 216    * From the server:
 217    * CRM_Core_Resources::singleton()->addSetting(array('myNamespace' => array('foo' => 'bar')));
 218    * From javascript:
 219    * CRM.myNamespace.foo // "bar"
 220    *
 221    * @see http://wiki.civicrm.org/confluence/display/CRMDOC/Javascript+Reference
 222    *
 223    * @param $settings array
 224    * @return CRM_Core_Resources
 225    */
 226   public function addSetting($settings) {
 227     $this->settings = $this->mergeSettings($this->settings, $settings);
 228     if (!$this->addedSettings) {
 229       $resources = $this;
 230       CRM_Core_Region::instance('html-header')->add(array(
 231         'callback' => function(&$snippet, &$html) use ($resources) {
 232           $html .= "\n" . $resources->renderSetting();
 233         },
 234         'weight' => -100000,
 235       ));
 236       $this->addedSettings = TRUE;
 237     }
 238     return $this;
 239   }
 240
 241   /**
 242    * Add JavaScript variables to the global CRM object via a callback function.
 243    *
 244    * @param callable $callable
 245    * @return CRM_Core_Resources
 246    */
 247   public function addSettingsFactory($callable) {
 248     // Make sure our callback has been registered
 249     $this->addSetting(array());
 250     $this->settingsFactories[] = $callable;
 251     return $this;
 252   }
 253
 254   /**
 255    * Helper fn for addSettingsFactory
 256    */
 257   public function getSettings() {
 258     $result = $this->settings;
 259     foreach ($this->settingsFactories as $callable) {
 260       $result = $this->mergeSettings($result, $callable());
 261     }
 262     return $result;
 263   }
 264
 265   /**
 266    * @param array $settings
 267    * @param array $additions
 268    * @return array combination of $settings and $additions
 269    */
 270   protected function mergeSettings($settings, $additions) {
 271     foreach ($additions as $k => $v) {
 272       if (isset($settings[$k]) && is_array($settings[$k]) && is_array($v)) {
 273         $v += $settings[$k];
 274       }
 275       $settings[$k] = $v;
 276     }
 277     return $settings;
 278   }
 279
 280   /**
 281    * Helper fn for addSetting
 282    * Render JavaScript variables for the global CRM object.
 283    *
 284    * @return string
 285    */
 286   public function renderSetting() {
 287     $js = 'var CRM = ' . json_encode($this->getSettings()) . ';';
 288     return sprintf("<script type=\"text/javascript\">\n%s\n</script>\n", $js);
 289   }
 290
 291   /**
 292    * Add translated string to the js CRM object.
 293    * It can then be retrived from the client-side ts() function
 294    * Variable substitutions can happen from client-side
 295    *
 296    * Note: this function rarely needs to be called directly and is mostly for internal use.
 297    * @see CRM_Core_Resources::addScriptFile which automatically adds translated strings from js files
 298    *
 299    * Simple example:
 300    * // From php:
 301    * CRM_Core_Resources::singleton()->addString('Hello');
 302    * // The string is now available to javascript code i.e.
 303    * ts('Hello');
 304    *
 305    * Example with client-side substitutions:
 306    * // From php:
 307    * CRM_Core_Resources::singleton()->addString('Your %1 has been %2');
 308    * // ts() in javascript works the same as in php, for example:
 309    * ts('Your %1 has been %2', {1: objectName, 2: actionTaken});
 310    *
 311    * NOTE: This function does not work with server-side substitutions
 312    * (as this might result in collisions and unwanted variable injections)
 313    * Instead, use code like:
 314    * CRM_Core_Resources::singleton()->addSetting(array('myNamespace' => array('myString' => ts('Your %1 has been %2', array(subs)))));
 315    * And from javascript access it at CRM.myNamespace.myString
 316    *
 317    * @param $text string|array
 318    * @return CRM_Core_Resources
 319    */
 320   public function addString($text) {
 321     foreach ((array) $text as $str) {
 322       $translated = ts($str);
 323       // We only need to push this string to client if the translation
 324       // is actually different from the original
 325       if ($translated != $str) {
 326         $this->addSetting(array('strings' => array($str => $translated)));
 327       }
 328     }
 329     return $this;
 330   }
 331
 332   /**
 333    * Add a CSS file to the current page using <LINK HREF>.
 334    *
 335    * @param $ext string, extension name; use 'civicrm' for core
 336    * @param $file string, file path -- relative to the extension base dir
 337    * @param $weight int, relative weight within a given region
 338    * @param $region string, location within the file; 'html-header', 'page-header', 'page-footer'
 339    * @return CRM_Core_Resources
 340    */
 341   public function addStyleFile($ext, $file, $weight = self::DEFAULT_WEIGHT, $region = self::DEFAULT_REGION) {
 342     return $this->addStyleUrl($this->getUrl($ext, $file, TRUE), $weight, $region);
 343   }
 344
 345   /**
 346    * Add a CSS file to the current page using <LINK HREF>.
 347    *
 348    * @param $url string
 349    * @param $weight int, relative weight within a given region
 350    * @param $region string, location within the file; 'html-header', 'page-header', 'page-footer'
 351    * @return CRM_Core_Resources
 352    */
 353   public function addStyleUrl($url, $weight = self::DEFAULT_WEIGHT, $region = self::DEFAULT_REGION) {
 354     CRM_Core_Region::instance($region)->add(array(
 355       'name' => $url,
 356       'type' => 'styleUrl',
 357       'styleUrl' => $url,
 358       'weight' => $weight,
 359       'region' => $region,
 360     ));
 361     return $this;
 362   }
 363
 364   /**
 365    * Add a CSS content to the current page using <STYLE>.
 366    *
 367    * @param $code string, CSS source code
 368    * @param $weight int, relative weight within a given region
 369    * @param $region string, location within the file; 'html-header', 'page-header', 'page-footer'
 370    * @return CRM_Core_Resources
 371    */
 372   public function addStyle($code, $weight = self::DEFAULT_WEIGHT, $region = self::DEFAULT_REGION) {
 373     CRM_Core_Region::instance($region)->add(array(
 374       // 'name' => automatic
 375       'type' => 'style',
 376       'style' => $code,
 377       'weight' => $weight,
 378       'region' => $region,
 379     ));
 380     return $this;
 381   }
 382
 383   /**
 384    * Determine file path of a resource provided by an extension
 385    *
 386    * @param $ext string, extension name; use 'civicrm' for core
 387    * @param $file string, file path -- relative to the extension base dir
 388    *
 389    * @return bool|string (string|bool), full file path or FALSE if not found
 390    */
 391   public function getPath($ext, $file) {
 392     // TODO consider caching results
 393     $path = $this->extMapper->keyToBasePath($ext) . '/' . $file;
 394     if (is_file($path)) {
 395       return $path;
 396     }
 397     return FALSE;
 398   }
 399
 400   /**
 401    * Determine public URL of a resource provided by an extension
 402    *
 403    * @param $ext string, extension name; use 'civicrm' for core
 404    * @param $file string, file path -- relative to the extension base dir
 405    * @param bool $addCacheCode
 406    *
 407    * @return string, URL
 408    */
 409   public function getUrl($ext, $file = NULL, $addCacheCode = FALSE) {
 410     if ($file === NULL) {
 411       $file = '';
 412     }
 413     if ($addCacheCode) {
 414       $file .= '?r=' . $this->getCacheCode();
 415     }
 416     // TODO consider caching results
 417     return $this->extMapper->keyToUrl($ext) . '/' . $file;
 418   }
 419
 420   /**
 421    * @return string
 422    */
 423   public function getCacheCode() {
 424     return $this->cacheCode;
 425   }
 426
 427   /**
 428    * @param $value
 429    */
 430   public function setCacheCode($value) {
 431     $this->cacheCode = $value;
 432     if ($this->cacheCodeKey) {
 433       CRM_Core_BAO_Setting::setItem($value, CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME, $this->cacheCodeKey);
 434     }
 435   }
 436
 437   public function resetCacheCode() {
 438     $this->setCacheCode(CRM_Utils_String::createRandom(5, CRM_Utils_String::ALPHANUMERIC));
 439   }
 440
 441   /**
 442    * This adds CiviCRM's standard css and js to the specified region of the document.
 443    * It will only run once.
 444    *
 445    * TODO: Separate the functional code (like addStyle/addScript) from the policy code
 446    * (like addCoreResources/addCoreStyles).
 447    *
 448    * @param string $region
 449    * @return CRM_Core_Resources
 450    * @access public
 451    */
 452   public function addCoreResources($region = 'html-header') {
 453     if (!isset($this->addedCoreResources[$region])) {
 454       $this->addedCoreResources[$region] = TRUE;
 455       $config = CRM_Core_Config::singleton();
 456
 457       // Add resources from coreResourceList
 458       $jsWeight = -9999;
 459       foreach ($this->coreResourceList() as $file) {
 460         if (substr($file, -2) == 'js') {
 461           // Don't bother  looking for ts() calls in packages, there aren't any
 462           $translate = (substr($file, 0, 9) != 'packages/');
 463           $this->addScriptFile('civicrm', $file, $jsWeight++, $region, $translate);
 464         }
 465         else {
 466           $this->addStyleFile('civicrm', $file, -100, $region);
 467         }
 468       }
 469
 470       // Dynamic localization script
 471       $this->addScriptUrl($this->addLocalizationJs(), $jsWeight++, $region);
 472
 473       // Add global settings
 474       $settings = array('config' => array(
 475         'ajaxPopupsEnabled' => $this->ajaxPopupsEnabled,
 476       ));
 477       // Disable profile creation if user lacks permission
 478       if (!CRM_Core_Permission::check('edit all contacts') && !CRM_Core_Permission::check('add contacts')) {
 479         $settings['profileCreate'] = FALSE;
 480       }
 481       $this->addSetting($settings);
 482
 483       // Give control of jQuery and _ back to the CMS - this loads last
 484       $this->addScriptFile('civicrm', 'js/noconflict.js', 9999, $region, FALSE);
 485
 486       $this->addCoreStyles($region);
 487     }
 488     return $this;
 489   }
 490
 491   /**
 492    * This will add CiviCRM's standard CSS
 493    *
 494    * TODO: Separate the functional code (like addStyle/addScript) from the policy code
 495    * (like addCoreResources/addCoreStyles).
 496    *
 497    * @param string $region
 498    * @return CRM_Core_Resources
 499    */
 500   public function addCoreStyles($region = 'html-header') {
 501     if (!isset($this->addedCoreStyles[$region])) {
 502       $this->addedCoreStyles[$region] = TRUE;
 503
 504       // Load custom or core css
 505       $config = CRM_Core_Config::singleton();
 506       if (!empty($config->customCSSURL)) {
 507         $this->addStyleUrl($config->customCSSURL, 99, $region);
 508       }
 509       if (!CRM_Core_BAO_Setting::getItem(CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME, 'disable_core_css')) {
 510         $this->addStyleFile('civicrm', 'css/civicrm.css', -99, $region);
 511       }
 512     }
 513     return $this;
 514   }
 515
 516   /**
 517    * Flushes cached translated strings
 518    */
 519   public function flushStrings() {
 520     $this->cache->flush();
 521   }
 522
 523   /**
 524    * Translate strings in a javascript file
 525    *
 526    * @param $ext string, extension name
 527    * @param $file string, file path
 528    * @return void
 529    */
 530   private function translateScript($ext, $file) {
 531     // For each extension, maintain one cache record which
 532     // includes parsed (translatable) strings for all its JS files.
 533     $stringsByFile = $this->cache->get($ext); // array($file => array(...strings...))
 534     if (!$stringsByFile) {
 535       $stringsByFile = array();
 536     }
 537     if (!isset($stringsByFile[$file])) {
 538       $filePath = $this->getPath($ext, $file);
 539       if ($filePath && is_readable($filePath)) {
 540         $stringsByFile[$file] = CRM_Utils_JS::parseStrings(file_get_contents($filePath));
 541       } else {
 542         $stringsByFile[$file] = array();
 543       }
 544       $this->cache->set($ext, $stringsByFile);
 545     }
 546     $this->addString($stringsByFile[$file]);
 547   }
 548
 549   /**
 550    * Add dynamic l10n js
 551    */
 552   private function addLocalizationJs() {
 553     $config = CRM_Core_Config::singleton();
 554     $fileName = 'l10n-' . $config->lcMessages . '.js';
 555     if (!is_file(CRM_Utils_File::dynamicResourcePath($fileName))) {
 556       $this->createLocalizationJs($fileName);
 557     }
 558     // Dynamic localization script
 559     return CRM_Utils_File::dynamicResourceUrl($fileName);
 560   }
 561
 562   /**
 563    * Create dymanic script for localizing js widgets
 564    */
 565   private function createLocalizationJs($fileName) {
 566     $config = CRM_Core_Config::singleton();
 567     $vars = array(
 568       'moneyFormat' => json_encode(CRM_Utils_Money::format(1234.56)),
 569       'contactSearch' => json_encode($config->includeEmailInName ? ts('Start typing a name or email...') : ts('Start typing a name...')),
 570       'otherSearch' => json_encode(ts('Enter search term...')),
 571       'contactCreate' => CRM_Core_BAO_UFGroup::getCreateLinks(),
 572     );
 573     CRM_Utils_File::addDynamicResource($fileName, CRM_Core_Page_AJAX::returnDynamicJS('CRM/common/localization.js.tpl', $vars));
 574   }
 575
 576   /**
 577    * List of core resources we add to every CiviCRM page
 578    *
 579    * @return array
 580    */
 581   public function coreResourceList() {
 582     $config = CRM_Core_Config::singleton();
 583     // Use minified files for production, uncompressed in debug mode
 584     // Note, $this->addScriptFile would automatically search for the non-minified file in debug mode but this is probably faster
 585     $min = $config->debug ? '' : '.min';
 586
 587     // Scripts needed by everyone, everywhere
 588     // FIXME: This is too long; list needs finer-grained segmentation
 589     $items = array(
 590       "packages/jquery/jquery-1.11.1$min.js",
 591       "packages/jquery/jquery-ui/jquery-ui$min.js",
 592       "packages/jquery/jquery-ui/jquery-ui$min.css",
 593
 594       "packages/backbone/lodash.compat$min.js",
 595
 596       "packages/jquery/plugins/jquery.mousewheel$min.js",
 597
 598       "packages/jquery/plugins/select2/select2$min.js",
 599       "packages/jquery/plugins/select2/select2.css",
 600
 601       "packages/jquery/plugins/jquery.tableHeader.js",
 602
 603       "packages/jquery/plugins/jquery.textarearesizer.js",
 604
 605       "packages/jquery/plugins/jquery.form$min.js",
 606
 607       "packages/jquery/plugins/jquery.timeentry$min.js",
 608
 609       "packages/jquery/plugins/DataTables/media/js/jquery.dataTables$min.js",
 610       "packages/jquery/plugins/DataTables/media/css/jquery.dataTables$min.css",
 611
 612       "packages/jquery/plugins/jquery.validate$min.js",
 613       "packages/jquery/plugins/jquery.ui.datepicker.validation.pack.js",
 614
 615       "js/Common.js",
 616       "js/crm.ajax.js",
 617     );
 618
 619     // These scripts are only needed by back-office users
 620     if (CRM_Core_Permission::check('access CiviCRM')) {
 621       $items[] = "packages/jquery/plugins/jquery.menu$min.js";
 622       $items[] = "packages/jquery/css/menu.css";
 623       $items[] = "packages/jquery/plugins/jquery.jeditable$min.js";
 624       $items[] = "packages/jquery/plugins/jquery.blockUI$min.js";
 625       $items[] = "packages/jquery/plugins/jquery.notify$min.js";
 626       $items[] = "js/jquery/jquery.crmeditable.js";
 627     }
 628
 629     // Enable administrators to edit option lists in a dialog
 630     if (CRM_Core_Permission::check('administer CiviCRM') && $this->ajaxPopupsEnabled) {
 631       $items[] = "js/crm.optionEdit.js";
 632     }
 633
 634     // Add localized jQuery UI files
 635     if ($config->lcMessages && $config->lcMessages != 'en_US') {
 636       // Search for i18n file in order of specificity (try fr-CA, then fr)
 637       list($lang) = explode('_', $config->lcMessages);
 638       $path = "packages/jquery/jquery-ui/i18n";
 639       foreach (array(str_replace('_', '-', $config->lcMessages), $lang) as $language) {
 640         $localizationFile = "$path/datepicker-{$language}.js";
 641         if ($this->getPath('civicrm', $localizationFile)) {
 642           $items[] = $localizationFile;
 643           break;
 644         }
 645       }
 646     }
 647     return $items;
 648   }
 649 }