Civi/Angular/Manager.php

   1 <?php
   2 namespace Civi\Angular;
   3
   4 /**
   5  * Manage Angular resources.
   6  *
   7  * @package Civi\Angular
   8  */
   9 class Manager {
  10
  11   /**
  12    * @var \CRM_Core_Resources
  13    */
  14   protected $res = NULL;
  15
  16   /**
  17    * Modules.
  18    *
  19    * @var array|null
  20    *   Each item has some combination of these keys:
  21    *   - ext: string
  22    *     The Civi extension which defines the Angular module.
  23    *   - js: array(string $relativeFilePath)
  24    *     List of JS files (relative to the extension).
  25    *   - css: array(string $relativeFilePath)
  26    *     List of CSS files (relative to the extension).
  27    *   - partials: array(string $relativeFilePath)
  28    *     A list of partial-HTML folders (relative to the extension).
  29    *     This will be mapped to "~/moduleName" by crmResource.
  30    *   - settings: array(string $key => mixed $value)
  31    *     List of settings to preload.
  32    */
  33   protected $modules = NULL;
  34
  35   /**
  36    * @var \CRM_Utils_Cache_Interface
  37    */
  38   protected $cache;
  39
  40   /**
  41    * @var array
  42    *   Array(string $name => ChangeSet $change).
  43    */
  44   protected $changeSets = NULL;
  45
  46   /**
  47    * @param \CRM_Core_Resources $res
  48    *   The resource manager.
  49    * @param $cache
  50    */
  51   public function __construct($res, \CRM_Utils_Cache_Interface $cache = NULL) {
  52     $this->res = $res;
  53     $this->cache = $cache ? $cache : new \CRM_Utils_Cache_ArrayCache([]);
  54   }
  55
  56   /**
  57    * Get a list of AngularJS modules which should be autoloaded.
  58    *
  59    * @return array
  60    *   Each item has some combination of these keys:
  61    *   - ext: string
  62    *     The Civi extension which defines the Angular module.
  63    *   - js: array(string $relativeFilePath)
  64    *     List of JS files (relative to the extension).
  65    *   - css: array(string $relativeFilePath)
  66    *     List of CSS files (relative to the extension).
  67    *   - partials: array(string $relativeFilePath)
  68    *     A list of partial-HTML folders (relative to the extension).
  69    *     This will be mapped to "~/moduleName" by crmResource.
  70    *   - settings: array(string $key => mixed $value)
  71    *     List of settings to preload.
  72    */
  73   public function getModules() {
  74     if ($this->modules === NULL) {
  75       $config = \CRM_Core_Config::singleton();
  76       global $civicrm_root;
  77
  78       // Note: It would be nice to just glob("$civicrm_root/ang/*.ang.php"), but at time
  79       // of writing CiviMail and CiviCase have special conditionals.
  80
  81       $angularModules = [];
  82       $angularModules['angularFileUpload'] = include "$civicrm_root/ang/angularFileUpload.ang.php";
  83       $angularModules['checklist-model'] = include "$civicrm_root/ang/checklist-model.ang.php";
  84       $angularModules['crmApp'] = include "$civicrm_root/ang/crmApp.ang.php";
  85       $angularModules['crmAttachment'] = include "$civicrm_root/ang/crmAttachment.ang.php";
  86       $angularModules['crmAutosave'] = include "$civicrm_root/ang/crmAutosave.ang.php";
  87       $angularModules['crmCxn'] = include "$civicrm_root/ang/crmCxn.ang.php";
  88       // $angularModules['crmExample'] = include "$civicrm_root/ang/crmExample.ang.php";
  89       $angularModules['crmResource'] = include "$civicrm_root/ang/crmResource.ang.php";
  90       $angularModules['crmRouteBinder'] = include "$civicrm_root/ang/crmRouteBinder.ang.php";
  91       $angularModules['crmUi'] = include "$civicrm_root/ang/crmUi.ang.php";
  92       $angularModules['crmUtil'] = include "$civicrm_root/ang/crmUtil.ang.php";
  93       $angularModules['dialogService'] = include "$civicrm_root/ang/dialogService.ang.php";
  94       $angularModules['ngRoute'] = include "$civicrm_root/ang/ngRoute.ang.php";
  95       $angularModules['ngSanitize'] = include "$civicrm_root/ang/ngSanitize.ang.php";
  96       $angularModules['ui.utils'] = include "$civicrm_root/ang/ui.utils.ang.php";
  97       $angularModules['ui.bootstrap'] = include "$civicrm_root/ang/ui.bootstrap.ang.php";
  98       $angularModules['ui.sortable'] = include "$civicrm_root/ang/ui.sortable.ang.php";
  99       $angularModules['unsavedChanges'] = include "$civicrm_root/ang/unsavedChanges.ang.php";
 100       $angularModules['statuspage'] = include "$civicrm_root/ang/crmStatusPage.ang.php";
 101       $angularModules['exportui'] = include "$civicrm_root/ang/exportui.ang.php";
 102       $angularModules['api4Explorer'] = include "$civicrm_root/ang/api4Explorer.ang.php";
 103       $angularModules['api4'] = include "$civicrm_root/ang/api4.ang.php";
 104
 105       foreach (\CRM_Core_Component::getEnabledComponents() as $component) {
 106         $angularModules = array_merge($angularModules, $component->getAngularModules());
 107       }
 108       \CRM_Utils_Hook::angularModules($angularModules);
 109       foreach (array_keys($angularModules) as $module) {
 110         if (!isset($angularModules[$module]['basePages'])) {
 111           $angularModules[$module]['basePages'] = ['civicrm/a'];
 112         }
 113       }
 114       $this->modules = $this->resolvePatterns($angularModules);
 115     }
 116
 117     return $this->modules;
 118   }
 119
 120   /**
 121    * Get the descriptor for an Angular module.
 122    *
 123    * @param string $name
 124    *   Module name.
 125    * @return array
 126    *   Details about the module:
 127    *   - ext: string, the name of the Civi extension which defines the module
 128    *   - js: array(string $relativeFilePath).
 129    *   - css: array(string $relativeFilePath).
 130    *   - partials: array(string $relativeFilePath).
 131    * @throws \Exception
 132    */
 133   public function getModule($name) {
 134     $modules = $this->getModules();
 135     if (!isset($modules[$name])) {
 136       throw new \Exception("Unrecognized Angular module");
 137     }
 138     return $modules[$name];
 139   }
 140
 141   /**
 142    * Resolve a full list of Angular dependencies.
 143    *
 144    * @param array $names
 145    *   List of Angular modules.
 146    *   Ex: array('crmMailing').
 147    * @return array
 148    *   List of Angular modules, include all dependencies.
 149    *   Ex: array('crmMailing', 'crmUi', 'crmUtil', 'ngRoute').
 150    */
 151   public function resolveDependencies($names) {
 152     $allModules = $this->getModules();
 153     $visited = [];
 154     $result = $names;
 155     while (($missingModules = array_diff($result, array_keys($visited))) && !empty($missingModules)) {
 156       foreach ($missingModules as $module) {
 157         $visited[$module] = 1;
 158         if (!isset($allModules[$module])) {
 159           \Civi::log()->warning('Unrecognized Angular module {name}. Please ensure that all Angular modules are declared.', [
 160             'name' => $module,
 161             'civi.tag' => 'deprecated',
 162           ]);
 163         }
 164         elseif (isset($allModules[$module]['requires'])) {
 165           $result = array_unique(array_merge($result, $allModules[$module]['requires']));
 166         }
 167       }
 168     }
 169     sort($result);
 170     return $result;
 171   }
 172
 173   /**
 174    * Get a list of Angular modules that should be loaded on the given
 175    * base-page.
 176    *
 177    * @param string $basePage
 178    *   The name of the base-page for which we want a list of moudles.
 179    * @return array
 180    *   List of Angular modules.
 181    *   Ex: array('crmMailing', 'crmUi', 'crmUtil', 'ngRoute').
 182    */
 183   public function resolveDefaultModules($basePage) {
 184     $modules = $this->getModules();
 185     $result = [];
 186     foreach ($modules as $moduleName => $module) {
 187       if (in_array($basePage, $module['basePages']) || in_array('*', $module['basePages'])) {
 188         $result[] = $moduleName;
 189       }
 190     }
 191     return $result;
 192   }
 193
 194   /**
 195    * Convert any globs in an Angular module to file names.
 196    *
 197    * @param array $modules
 198    *   List of Angular modules.
 199    * @return array
 200    *   Updated list of Angular modules
 201    */
 202   protected function resolvePatterns($modules) {
 203     $newModules = [];
 204
 205     foreach ($modules as $moduleKey => $module) {
 206       foreach (['js', 'css', 'partials'] as $fileset) {
 207         if (!isset($module[$fileset])) {
 208           continue;
 209         }
 210         $module[$fileset] = $this->res->glob($module['ext'], $module[$fileset]);
 211       }
 212       $newModules[$moduleKey] = $module;
 213     }
 214
 215     return $newModules;
 216   }
 217
 218   /**
 219    * Get the partial HTML documents for a module (unfiltered).
 220    *
 221    * @param string $name
 222    *   Angular module name.
 223    * @return array
 224    *   Array(string $extFilePath => string $html)
 225    * @throws \Exception
 226    *   Invalid partials configuration.
 227    */
 228   public function getRawPartials($name) {
 229     $module = $this->getModule($name);
 230     $result = !empty($module['partialsCallback'])
 231       ? \Civi\Core\Resolver::singleton()->call($module['partialsCallback'], [$name, $module])
 232       : [];
 233     if (isset($module['partials'])) {
 234       foreach ($module['partials'] as $partialDir) {
 235         $partialDir = $this->res->getPath($module['ext']) . '/' . $partialDir;
 236         $files = \CRM_Utils_File::findFiles($partialDir, '*.html', TRUE);
 237         foreach ($files as $file) {
 238           $filename = '~/' . $name . '/' . $file;
 239           $result[$filename] = file_get_contents($partialDir . '/' . $file);
 240         }
 241       }
 242       return $result;
 243     }
 244     return $result;
 245   }
 246
 247   /**
 248    * Get the partial HTML documents for a module.
 249    *
 250    * @param string $name
 251    *   Angular module name.
 252    * @return array
 253    *   Array(string $extFilePath => string $html)
 254    * @throws \Exception
 255    *   Invalid partials configuration.
 256    */
 257   public function getPartials($name) {
 258     $cacheKey = "angular-partials_$name";
 259     $cacheValue = $this->cache->get($cacheKey);
 260     if ($cacheValue === NULL) {
 261       $cacheValue = ChangeSet::applyResourceFilters($this->getChangeSets(), 'partials', $this->getRawPartials($name));
 262       $this->cache->set($cacheKey, $cacheValue);
 263     }
 264     return $cacheValue;
 265   }
 266
 267   /**
 268    * Get list of translated strings for a module.
 269    *
 270    * @param string $name
 271    *   Angular module name.
 272    * @return array
 273    *   Translated strings: array(string $orig => string $translated).
 274    */
 275   public function getTranslatedStrings($name) {
 276     $module = $this->getModule($name);
 277     $result = [];
 278     $strings = $this->getStrings($name);
 279     foreach ($strings as $string) {
 280       // TODO: should we pass translation domain based on $module[ext] or $module[tsDomain]?
 281       // It doesn't look like client side really supports the domain right now...
 282       $translated = ts($string, [
 283         'domain' => [$module['ext'], NULL],
 284       ]);
 285       if ($translated != $string) {
 286         $result[$string] = $translated;
 287       }
 288     }
 289     return $result;
 290   }
 291
 292   /**
 293    * Get list of translatable strings for a module.
 294    *
 295    * @param string $name
 296    *   Angular module name.
 297    * @return array
 298    *   Translatable strings.
 299    */
 300   public function getStrings($name) {
 301     $module = $this->getModule($name);
 302     $result = [];
 303     if (isset($module['js'])) {
 304       foreach ($module['js'] as $file) {
 305         $strings = $this->res->getStrings()->get(
 306           $module['ext'],
 307           $this->res->getPath($module['ext'], $file),
 308           'text/javascript'
 309         );
 310         $result = array_unique(array_merge($result, $strings));
 311       }
 312     }
 313     $partials = $this->getPartials($name);
 314     foreach ($partials as $partial) {
 315       $result = array_unique(array_merge($result, \CRM_Utils_JS::parseStrings($partial)));
 316     }
 317     return $result;
 318   }
 319
 320   /**
 321    * Get resources for one or more modules.
 322    *
 323    * @param string|array $moduleNames
 324    *   List of module names.
 325    * @param string $resType
 326    *   Type of resource ('js', 'css', 'settings').
 327    * @param string $refType
 328    *   Type of reference to the resource ('cacheUrl', 'rawUrl', 'path', 'settings').
 329    * @return array
 330    *   List of URLs or paths.
 331    * @throws \CRM_Core_Exception
 332    */
 333   public function getResources($moduleNames, $resType, $refType) {
 334     $result = [];
 335     $moduleNames = (array) $moduleNames;
 336     foreach ($moduleNames as $moduleName) {
 337       $module = $this->getModule($moduleName);
 338       if (isset($module[$resType])) {
 339         foreach ($module[$resType] as $file) {
 340           $refTypeSuffix = '';
 341           if (is_string($file) && preg_match(';^(assetBuilder|ext)://;', $file)) {
 342             $refTypeSuffix = '-' . parse_url($file, PHP_URL_SCHEME);
 343           }
 344
 345           switch ($refType . $refTypeSuffix) {
 346             case 'path':
 347               $result[] = $this->res->getPath($module['ext'], $file);
 348               break;
 349
 350             case 'rawUrl':
 351               $result[] = $this->res->getUrl($module['ext'], $file);
 352               break;
 353
 354             case 'cacheUrl':
 355               $result[] = $this->res->getUrl($module['ext'], $file, TRUE);
 356               break;
 357
 358             case 'path-assetBuilder':
 359               $assetName = parse_url($file, PHP_URL_HOST) . parse_url($file, PHP_URL_PATH);
 360               $assetParams = [];
 361               parse_str('' . parse_url($file, PHP_URL_QUERY), $assetParams);
 362               $result[] = \Civi::service('asset_builder')->getPath($assetName, $assetParams);
 363               break;
 364
 365             case 'rawUrl-assetBuilder':
 366             case 'cacheUrl-assetBuilder':
 367               $assetName = parse_url($file, PHP_URL_HOST) . parse_url($file, PHP_URL_PATH);
 368               $assetParams = [];
 369               parse_str('' . parse_url($file, PHP_URL_QUERY), $assetParams);
 370               $result[] = \Civi::service('asset_builder')->getUrl($assetName, $assetParams);
 371               break;
 372
 373             case 'path-ext':
 374               $result[] = $this->res->getPath(parse_url($file, PHP_URL_HOST), ltrim(parse_url($file, PHP_URL_PATH), '/'));
 375               break;
 376
 377             case 'rawUrl-ext':
 378               $result[] = $this->res->getUrl(parse_url($file, PHP_URL_HOST), ltrim(parse_url($file, PHP_URL_PATH), '/'));
 379               break;
 380
 381             case 'cacheUrl-ext':
 382               $result[] = $this->res->getUrl(parse_url($file, PHP_URL_HOST), ltrim(parse_url($file, PHP_URL_PATH), '/'), TRUE);
 383               break;
 384
 385             case 'settings':
 386             case 'requires':
 387               if (!empty($module[$resType])) {
 388                 $result[$moduleName] = $module[$resType];
 389               }
 390               break;
 391
 392             default:
 393               throw new \CRM_Core_Exception("Unrecognized resource format");
 394           }
 395         }
 396       }
 397     }
 398
 399     return ChangeSet::applyResourceFilters($this->getChangeSets(), $resType, $result);
 400   }
 401
 402   /**
 403    * @return array
 404    *   Array(string $name => ChangeSet $changeSet).
 405    */
 406   public function getChangeSets() {
 407     if ($this->changeSets === NULL) {
 408       $this->changeSets = [];
 409       \CRM_Utils_Hook::alterAngular($this);
 410     }
 411     return $this->changeSets;
 412   }
 413
 414   /**
 415    * @param ChangeSet $changeSet
 416    * @return \Civi\Angular\Manager
 417    */
 418   public function add($changeSet) {
 419     $this->changeSets[$changeSet->getName()] = $changeSet;
 420     return $this;
 421   }
 422
 423 }