From a429f440d93faa642cf048ddc1a6ed0f00738df5 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Tue, 12 Jun 2018 23:10:16 -0700
Subject: [PATCH] Import Api3Ctrl

---
 ext/afform/ang/afformCore/Api3Ctrl.js | 51 +++++++++++++++++++
 ext/afform/ang/afformCore/Api3Ctrl.md | 73 +++++++++++++++++++++++++++
 2 files changed, 124 insertions(+)
 create mode 100644 ext/afform/ang/afformCore/Api3Ctrl.js
 create mode 100644 ext/afform/ang/afformCore/Api3Ctrl.md

diff --git a/ext/afform/ang/afformCore/Api3Ctrl.js b/ext/afform/ang/afformCore/Api3Ctrl.js
new file mode 100644
index 0000000000..e1f7506f33
--- /dev/null
+++ b/ext/afform/ang/afformCore/Api3Ctrl.js
@@ -0,0 +1,51 @@
+(function(angular, $, _) {
+
+  angular.module('afformCore').directive('afformApi3Ctrl', function() {
+    return {
+      restrict: 'EA',
+      scope: {
+        afformApi3Ctrl: '=',
+        afformApi3: '@',
+        afformApi3Refresh: '@',
+        onRefresh: '@'
+      },
+      controllerAs: 'afformApi3Ctrl',
+      controller: function($scope, $parse, crmThrottle, crmApi) {
+        var ctrl = this;
+
+        // CONSIDER: Trade-offs of upfront vs ongoing evaluation.
+        var parts = $parse($scope.afformApi3)($scope.$parent);
+        ctrl.entity = parts[0];
+        ctrl.action = parts[1];
+        ctrl.params = parts[2];
+        ctrl.result = {};
+        ctrl.loading = ctrl.firstLoad = true;
+
+        ctrl.refresh = function refresh() {
+          ctrl.loading = true;
+          crmThrottle(function () {
+            return crmApi(ctrl.entity, ctrl.action, ctrl.params)
+              .then(function (response) {
+                ctrl.result = response;
+                ctrl.loading = ctrl.firstLoad = false;
+                if ($scope.onRefresh) {
+                  $scope.$parent.$eval($scope.onRefresh, ctrl);
+                }
+              });
+          });
+        };
+
+        $scope.afformApi3Ctrl = this;
+
+        var mode = $scope.afformApi3Refresh ? $scope.afformApi3Refresh : 'auto';
+        switch (mode) {
+          case 'auto': $scope.$watchCollection('afformApi3Ctrl.params', ctrl.refresh); break;
+          case 'init': ctrl.refresh(); break;
+          case 'manual': break;
+          default: throw 'Unrecognized refresh mode: '+ mode;
+        }
+      }
+    };
+  });
+
+})(angular, CRM.$, CRM._);
diff --git a/ext/afform/ang/afformCore/Api3Ctrl.md b/ext/afform/ang/afformCore/Api3Ctrl.md
new file mode 100644
index 0000000000..0b328eca5b
--- /dev/null
+++ b/ext/afform/ang/afformCore/Api3Ctrl.md
@@ -0,0 +1,73 @@
+# afform-api3-ctrl
+
+This directive is designed for querying and displaying data from APIv3. Each API call is represented with an object like this:
+
+```js
+{
+  entity: 'Contact',
+  action: 'get',
+  params: {display_name: 'alice'},
+  result: {
+    is_error: 0,
+    count: 10,
+    values: {...}
+  },
+  refresh: function(){...}
+}
+```
+
+You can initialize this object using `<afform-api3-ctrl>` and `<afform-api3>`, as in:
+
+```html
+<div
+  afform-api3-ctrl="apiData"
+  afform-api3="['Contact','get', {display_name: ''}]">
+
+    <div crm-ui-debug="apiData"></div>
+
+    <div>
+      Filter by name: <input ng-model="apiData.params.display_name" />
+    </div>
+
+    <ul>
+      <li ng-repeat="value in apiData.result.values">{{value.display_name}}</li>
+    </ul>
+</div>
+```
+
+By default, the API call will refresh its results automatically - as soon as the filter parameters change.
+
+If you'd rather wait and trigger the refresh another way, then set the `afform-api3-refresh` policy to `init` or `manual`. Don't forget to fire the refresh some other way, such as `ng-click`:
+
+```html
+<div
+  afform-api3-ctrl="apiData"
+  afform-api3="['Contact','get', {display_name: ''}]"
+  afform-api3-refresh="init">
+
+    <div crm-ui-debug="apiData"></div>
+
+    <div>
+      Filter by name: <input ng-model="apiData.params.display_name" />
+      <button ng-click="apiData.refresh()">Search</button>
+    </div>
+
+    <ul>
+      <li ng-repeat="value in apiData.result.values">{{value.display_name}}</li>
+    </ul>
+
+</div>
+```
+
+And you conditionally execute some logic whenever a refresh occurs -- use
+`on-refresh`. Within the scope of this statement, you have access to the
+properties of the API object (`entity`, `action`, `params`, `result`).
+
+```html
+<div
+  afform-api3-ctrl="apiData"
+  afform-api3="['Contact','get', {display_name: ''}]"
+  on-refresh="doSomething(result)">
+  ...
+</div>
+```
-- 
2.25.1