Merge pull request #10783 from totten/master-angldr

CRM-20981 - Allow custom base-pages with less `crmApp` boilerplate
civicrm · Mar 20, 2018 · 9ac4f69 · 9ac4f69
2 parents a6cdd84 + 23a258c
commit 9ac4f69
Show file tree

Hide file tree

Showing 2 changed files with 89 additions and 17 deletions.
diff --git a/Civi/Angular/AngularLoader.php b/Civi/Angular/AngularLoader.php
@@ -61,6 +61,11 @@ class AngularLoader {
    */
   protected $modules;
 
+  /**
+   * @var array|NULL
+   */
+  protected $crmApp = NULL;
+
   /**
    * AngularLoader constructor.
    */
@@ -74,11 +79,32 @@ public function __construct() {
 
   /**
    * Register resources required by Angular.
+   *
+   * @return AngularLoader
    */
   public function load() {
     $angular = $this->getAngular();
     $res = $this->getRes();
 
+    if ($this->crmApp !== NULL) {
+      $this->addModules($this->crmApp['modules']);
+      $region = \CRM_Core_Region::instance($this->crmApp['region']);
+      $region->update('default', array('disabled' => TRUE));
+      $region->add(array('template' => $this->crmApp['file'], 'weight' => 0));
+      $this->res->addSetting(array(
+        'crmApp' => array(
+          'defaultRoute' => $this->crmApp['defaultRoute'],
+        ),
+      ));
+
+      // If trying to load an Angular page via AJAX, the route must be passed as a
+      // URL parameter, since the server doesn't receive information about
+      // URL fragments (i.e, what comes after the #).
+      $this->res->addSetting(array(
+        'angularRoute' => $this->crmApp['activeRoute'],
+      ));
+    }
+
     $moduleNames = $this->findActiveModules();
     if (!$this->isAllModules($moduleNames)) {
       $assetParams = array('modules' => implode(',', $moduleNames));
@@ -135,6 +161,45 @@ public function load() {
         $res->addStyleUrl($url, self::DEFAULT_MODULE_WEIGHT + (++$headOffset), $this->getRegion());
       }
     }
+
+    return $this;
+  }
+
+  /**
+   * Use Civi's generic "application" module.
+   *
+   * This is suitable for use on a basic, standalone Angular page
+   * like `civicrm/a`. (If you need to integrate Angular with pre-existing,
+   * non-Angular pages... then this probably won't help.)
+   *
+   * The Angular bootstrap process requires an HTML directive like
+   * `<div ng-app="foo">`.
+   *
+   * Calling useApp() will replace the page's main body with the
+   * `<div ng-app="crmApp">...</div>` and apply some configuration options
+   * for the `crmApp` module.
+   *
+   * @param array $settings
+   *   A list of settings. Accepted values:
+   *    - activeRoute: string, the route to open up immediately
+   *      Ex: '/case/list'
+   *    - defaultRoute: string, use this to redirect the default route (`/`) to another page
+   *      Ex: '/case/list'
+   *    - region: string, the place on the page where we should insert the angular app
+   *      Ex: 'page-body'
+   * @return AngularLoader
+   * @link https://code.angularjs.org/1.5.11/docs/guide/bootstrap
+   */
+  public function useApp($settings = array()) {
+    $defaults = array(
+      'modules' => array('crmApp'),
+      'activeRoute' => NULL,
+      'defaultRoute' => NULL,
+      'region' => 'page-body',
+      'file' => 'Civi/Angular/Page/Main.tpl',
+    );
+    $this->crmApp = array_merge($defaults, $settings);
+    return $this;
   }
 
   /**
@@ -170,9 +235,11 @@ public function getRes() {
 
   /**
    * @param \CRM_Core_Resources $res
+   * @return AngularLoader
    */
   public function setRes($res) {
     $this->res = $res;
+    return $this;
   }
 
   /**
@@ -184,9 +251,11 @@ public function getAngular() {
 
   /**
    * @param \Civi\Angular\Manager $angular
+   * @return AngularLoader
    */
   public function setAngular($angular) {
     $this->angular = $angular;
+    return $this;
   }
 
   /**
@@ -198,9 +267,11 @@ public function getRegion() {
 
   /**
    * @param string $region
+   * @return AngularLoader
    */
   public function setRegion($region) {
     $this->region = $region;
+    return $this;
   }
 
   /**
@@ -214,9 +285,21 @@ public function getPageName() {
   /**
    * @param string $pageName
    *   Ex: 'civicrm/a'.
+   * @return AngularLoader
    */
   public function setPageName($pageName) {
     $this->pageName = $pageName;
+    return $this;
+  }
+
+  /**
+   * @param array|string $modules
+   * @return AngularLoader
+   */
+  public function addModules($modules) {
+    $modules = (array) $modules;
+    $this->modules = array_unique(array_merge($this->modules, $modules));
+    return $this;
   }
 
   /**
@@ -228,9 +311,11 @@ public function getModules() {
 
   /**
    * @param array $modules
+   * @return AngularLoader
    */
   public function setModules($modules) {
     $this->modules = $modules;
+    return $this;
   }
 
 }
diff --git a/Civi/Angular/Page/Main.php b/Civi/Angular/Page/Main.php
@@ -76,25 +76,12 @@ public function run() {
   public function registerResources() {
     $loader = new \Civi\Angular\AngularLoader();
     $loader->setPageName('civicrm/a');
-    $loader->setModules(array('crmApp'));
-    $loader->load();
-
-    // If trying to load an Angular page via AJAX, the route must be passed as a
-    // URL parameter, since the server doesn't receive information about
-    // URL fragments (i.e, what comes after the #).
-    \CRM_Core_Resources::singleton()->addSetting(array(
-      'crmApp' => array(
-        'defaultRoute' => NULL,
-      ),
-      'angularRoute' => \CRM_Utils_Request::retrieve('route', 'String'),
+    $loader->useApp(array(
+      'activeRoute' => \CRM_Utils_Request::retrieve('route', 'String'),
+      'defaultRoute' => NULL,
     ));
-  }
+    $loader->load();
 
-  /**
-   * @inheritdoc
-   */
-  public function getTemplateFileName() {
-    return 'Civi/Angular/Page/Main.tpl';
   }
 
 }