feat(menu): expose close method on element scope; deprecate $mdOpenMenu (#9193)

crisbeto · kara · commit 1e4ba35d4d7b · 2016-10-14T11:22:16.000-07:00
* Deprecates the `$mdOpenMenu` method in favor of `$mdMenu.open` in order to simplify the API. * Exposes the `$mdMenu.close` method on the menu's scope, allowing for custom closing behavior. Fixes #8446.
diff --git a/src/components/list/list.js b/src/components/list/list.js
@@ -295,7 +295,7 @@ function mdListItemDirective($mdAria, $mdConstant, $mdUtil, $timeout) {
           // When the proxy item is aligned at the end of the list, we have to set the origin to the end.
           xAxisPosition = 'right';
         }
-        
+
         // Set the position mode / origin of the proxied menu.
         if (!menuEl.attr('md-position-mode')) {
           menuEl.attr('md-position-mode', xAxisPosition + ' target');
@@ -304,7 +304,7 @@ function mdListItemDirective($mdAria, $mdConstant, $mdUtil, $timeout) {
         // Apply menu open binding to menu button
         var menuOpenButton = menuEl.children().eq(0);
         if (!hasClickEvent(menuOpenButton[0])) {
-          menuOpenButton.attr('ng-click', '$mdOpenMenu($event)');
+          menuOpenButton.attr('ng-click', '$mdMenu.open($event)');
         }
 
         if (!menuOpenButton.attr('aria-label')) {
diff --git a/src/components/list/list.spec.js b/src/components/list/list.spec.js
@@ -294,7 +294,7 @@ describe('mdListItem directive', function() {
 
     // The actual click button will be a child of the button.md-no-style wrapper.
     var buttonExecutor = buttonWrap.children()[0];
-    
+
     expect(buttonExecutor.nodeName).toBe('MD-BUTTON');
     expect(buttonExecutor.getAttribute('aria-label')).toBe('Hello');
   });
@@ -497,7 +497,7 @@ describe('mdListItem directive', function() {
 
       var mdMenuButton = listItem[0].querySelector('md-menu > md-button');
 
-      expect(mdMenuButton.getAttribute('ng-click')).toBe('$mdOpenMenu($event)');
+      expect(mdMenuButton.getAttribute('ng-click')).toBe('$mdMenu.open($event)');
     });
   });
 
diff --git a/src/components/menu/demoBasicUsage/index.html b/src/components/menu/demoBasicUsage/index.html
@@ -5,7 +5,7 @@ <h2 class="md-title">Simple dropdown menu</h2>
     <p>Applying the <code>md-menu-origin</code> and <code>md-menu-align-target</code> attributes ensure that the menu elements align.
     Note: If you select the Redial menu option, then a modal dialog will zoom out of the phone icon button.</p>
     <md-menu>
-      <md-button aria-label="Open phone interactions menu" class="md-icon-button" ng-click="ctrl.openMenu($mdOpenMenu, $event)">
+      <md-button aria-label="Open phone interactions menu" class="md-icon-button" ng-click="ctrl.openMenu($mdMenu, $event)">
         <md-icon md-menu-origin md-svg-icon="call:phone"></md-icon>
       </md-button>
       <md-menu-content width="4">
diff --git a/src/components/menu/demoBasicUsage/script.js b/src/components/menu/demoBasicUsage/script.js
@@ -8,9 +8,9 @@ angular
   .controller('BasicDemoCtrl', function DemoCtrl($mdDialog) {
     var originatorEv;
 
-    this.openMenu = function($mdOpenMenu, ev) {
+    this.openMenu = function($mdMenu, ev) {
       originatorEv = ev;
-      $mdOpenMenu(ev);
+      $mdMenu.open(ev);
     };
 
     this.notificationsEnabled = true;
diff --git a/src/components/menu/demoCustomTrigger/index.html b/src/components/menu/demoCustomTrigger/index.html
@@ -0,0 +1,21 @@
+<div class="md-menu-demo" ng-cloak>
+  <div class="menu-demo-container" layout-align="center center" layout="column">
+    <h2 class="md-title">Custom triggers</h2>
+    <p>
+      You can customize the events that open and close a menu by using the <code>$mdMenu.open</code> and
+      <code>$mdMenu.close</code> methods. This is an example of triggering a menu on hover, instead of click.
+    </p>
+
+    <md-menu>
+      <md-button aria-label="Open menu with custom trigger" class="md-icon-button" ng-mouseenter="$mdMenu.open()">
+        <md-icon md-menu-origin md-svg-icon="call:textsms"></md-icon>
+      </md-button>
+      <md-menu-content width="4" ng-mouseleave="$mdMenu.close()">
+        <md-menu-item ng-repeat="item in [1, 2, 3]">
+          <md-button>
+            Option {{item}}
+          </md-button>
+        </md-menu-item>
+    </md-menu>
+  </div>
+</div>
diff --git a/src/components/menu/demoCustomTrigger/script.js b/src/components/menu/demoCustomTrigger/script.js
@@ -0,0 +1,6 @@
+angular
+  .module('menuDemoCustomTrigger', ['ngMaterial'])
+  .config(function($mdIconProvider) {
+    $mdIconProvider
+      .iconSet('call', 'img/icons/sets/communication-icons.svg', 24);
+  });
diff --git a/src/components/menu/demoCustomTrigger/style.css b/src/components/menu/demoCustomTrigger/style.css
@@ -0,0 +1,7 @@
+.md-menu-demo {
+  padding: 24px;
+}
+
+.menu-demo-container {
+  min-height: 200px;
+}
diff --git a/src/components/menu/demoMenuPositionModes/index.html b/src/components/menu/demoMenuPositionModes/index.html
@@ -8,14 +8,14 @@ <h2 class="md-title">Position Mode Demos</h2>
       <div layout="column" flex-xs="100" flex-sm="100" flex="33" layout-align="center center">
         <p>Target Mode Positioning (default)</p>
         <md-menu>
-          <md-button aria-label="Open demo menu" class="md-icon-button" ng-click="$mdOpenMenu($event)">
+          <md-button aria-label="Open demo menu" class="md-icon-button" ng-click="$mdMenu.open($event)">
             <md-icon md-menu-origin md-svg-icon="call:business"></md-icon>
           </md-button>
           <md-menu-content width="6">
             <md-menu-item ng-repeat="item in [1, 2, 3]">
               <md-button ng-click="ctrl.announceClick($index)">
                 <md-icon md-menu-align-target md-svg-icon="call:no-sim"></md-icon>
-                Option {{item}} 
+                Option {{item}}
               </md-button>
             </md-menu-item>
           </md-menu-content>
@@ -24,7 +24,7 @@ <h2 class="md-title">Position Mode Demos</h2>
       <div layout="column" flex-xs="100" flex-sm="100" flex="33" layout-align="center center">
         <p>Target mode with <code>md-offset</code></p>
         <md-menu md-offset="0 -5">
-          <md-button aria-label="Open demo menu" class="md-icon-button" ng-click="ctrl.openMenu($mdOpenMenu, $event)">
+          <md-button aria-label="Open demo menu" class="md-icon-button" ng-click="ctrl.openMenu($mdMenu, $event)">
             <md-icon md-menu-origin md-svg-icon="call:ring-volume"></md-icon>
           </md-button>
           <md-menu-content width="4">
@@ -37,7 +37,7 @@ <h2 class="md-title">Position Mode Demos</h2>
       <div layout="column" flex-xs="100" flex-sm="100" flex="33" layout-align="center center">
         <p><code>md-position-mode="target-right target"</code></p>
         <md-menu md-position-mode="target-right target" >
-          <md-button aria-label="Open demo menu" class="md-icon-button" ng-click="$mdOpenMenu($event)">
+          <md-button aria-label="Open demo menu" class="md-icon-button" ng-click="$mdMenu.open($event)">
             <md-icon md-menu-origin md-svg-icon="call:portable-wifi-off"></md-icon>
           </md-button>
           <md-menu-content width="4" >
diff --git a/src/components/menu/demoMenuPositionModes/script.js b/src/components/menu/demoMenuPositionModes/script.js
@@ -7,12 +7,12 @@ angular
   })
   .controller('PositionDemoCtrl', function DemoCtrl($mdDialog) {
     var originatorEv;
-    
+
     this.menuHref = "http://www.google.com/design/spec/components/menus.html#menus-specs";
 
-    this.openMenu = function($mdOpenMenu, ev) {
+    this.openMenu = function($mdMenu, ev) {
       originatorEv = ev;
-      $mdOpenMenu(ev);
+      $mdMenu.open(ev);
     };
 
     this.announceClick = function(index) {
diff --git a/src/components/menu/demoMenuWidth/index.html b/src/components/menu/demoMenuWidth/index.html
@@ -11,7 +11,7 @@ <h2 class="md-title">Different Widths</h2>
       <div layout="column" flex="33" flex-sm="100" flex-xs="100" layout-align="center center">
         <p>Wide menu (<code>width=6</code>)</p>
         <md-menu md-offset="0 -7">
-          <md-button aria-label="Open demo menu" class="md-icon-button" ng-click="$mdOpenMenu($event)">
+          <md-button aria-label="Open demo menu" class="md-icon-button" ng-click="$mdMenu.open($event)">
             <md-icon md-menu-origin md-svg-icon="call:phone"></md-icon>
           </md-button>
           <md-menu-content width="6">
@@ -24,7 +24,7 @@ <h2 class="md-title">Different Widths</h2>
       <div layout="column" flex="33" flex-sm="100" flex-xs="100" layout-align="center center">
         <p>Medium menu (<code>width=4</code>)</p>
         <md-menu md-offset="0 -7">
-          <md-button aria-label="Open demo menu" class="md-icon-button" ng-click="$mdOpenMenu($event)">
+          <md-button aria-label="Open demo menu" class="md-icon-button" ng-click="$mdMenu.open($event)">
             <md-icon md-menu-origin md-svg-icon="call:email"></md-icon>
           </md-button>
           <md-menu-content width="4">
@@ -37,7 +37,7 @@ <h2 class="md-title">Different Widths</h2>
       <div layout="column" flex="33" flex-sm="100" flex-xs="100" layout-align="center center">
         <p>Small menu (<code>width=2</code>)</p>
         <md-menu md-offset="0 -7">
-          <md-button aria-label="Open demo menu" class="md-icon-button" ng-click="$mdOpenMenu($event)">
+          <md-button aria-label="Open demo menu" class="md-icon-button" ng-click="$mdMenu.open($event)">
             <md-icon md-menu-origin md-svg-icon="call:chat"></md-icon>
           </md-button>
           <md-menu-content width="2">
diff --git a/src/components/menu/js/menuController.js b/src/components/menu/js/menuController.js
@@ -7,7 +7,7 @@ angular
 /**
  * @ngInject
  */
-function MenuController($mdMenu, $attrs, $element, $scope, $mdUtil, $timeout, $rootScope, $q) {
+function MenuController($mdMenu, $attrs, $element, $scope, $mdUtil, $timeout, $rootScope, $q, $log) {
 
   var prefixer = $mdUtil.prefixer();
   var menuContainer;
@@ -141,9 +141,6 @@ function MenuController($mdMenu, $attrs, $element, $scope, $mdUtil, $timeout, $r
     });
   };
 
-  // Expose a open function to the child scope for html to use
-  $scope.$mdOpenMenu = this.open;
-
   this.onIsOpenChanged = function(isOpen) {
     if (isOpen) {
       menuContainer.attr('aria-hidden', 'false');
@@ -234,4 +231,16 @@ function MenuController($mdMenu, $attrs, $element, $scope, $mdUtil, $timeout, $r
       throw Error('Invalid offsets specified. Please follow format <x, y> or <n>');
     }
   };
+
+  // Functionality that is exposed in the view.
+  $scope.$mdMenu = {
+    open: this.open,
+    close: this.close
+  };
+
+  // Deprecated APIs
+  $scope.$mdOpenMenu = angular.bind(this, function() {
+    $log.warn('mdMenu: The $mdOpenMenu method is deprecated. Please use `$mdMenu.open`.');
+    return this.open.apply(this, arguments);
+  });
 }
diff --git a/src/components/menu/js/menuDirective.js b/src/components/menu/js/menuDirective.js
@@ -10,9 +10,10 @@
  *
  * Every `md-menu` must specify exactly two child elements. The first element is what is
  * left in the DOM and is used to open the menu. This element is called the trigger element.
- * The trigger element's scope has access to `$mdOpenMenu($event)`
+ * The trigger element's scope has access to `$mdMenu.open($event)`
  * which it may call to open the menu. By passing $event as argument, the
- * corresponding event is stopped from propagating up the DOM-tree.
+ * corresponding event is stopped from propagating up the DOM-tree. Similarly, `$mdMenu.close()`
+ * can be used to close the menu.
  *
  * The second element is the `md-menu-content` element which represents the
  * contents of the menu when it is open. Typically this will contain `md-menu-item`s,
@@ -21,7 +22,7 @@
  * <hljs lang="html">
  * <md-menu>
  *  <!-- Trigger element is a md-button with an icon -->
- *  <md-button ng-click="$mdOpenMenu($event)" class="md-icon-button" aria-label="Open sample menu">
+ *  <md-button ng-click="$mdMenu.open($event)" class="md-icon-button" aria-label="Open sample menu">
  *    <md-icon md-svg-icon="call:phone"></md-icon>
  *  </md-button>
  *  <md-menu-content>
@@ -63,7 +64,7 @@
  *
  * <hljs lang="html">
  * <md-menu>
- *  <md-button ng-click="$mdOpenMenu($event)" class="md-icon-button" aria-label="Open some menu">
+ *  <md-button ng-click="$mdMenu.open($event)" class="md-icon-button" aria-label="Open some menu">
  *    <md-icon md-menu-origin md-svg-icon="call:phone"></md-icon>
  *  </md-button>
  *  <md-menu-content>
@@ -123,22 +124,24 @@
  * Sometimes you would like to be able to click on a menu item without having the menu
  * close. To do this, ngMaterial exposes the `md-prevent-menu-close` attribute which
  * can be added to a button inside a menu to stop the menu from automatically closing.
- * You can then close the menu programatically by injecting `$mdMenu` and calling
- * `$mdMenu.hide()`.
+ * You can then close the menu either by using `$mdMenu.close()` in the template,
+ * or programatically by injecting `$mdMenu` and calling `$mdMenu.hide()`.
  *
  * <hljs lang="html">
- * <md-menu-item>
- *   <md-button ng-click="doSomething()" aria-label="Do something" md-prevent-menu-close="md-prevent-menu-close">
- *     <md-icon md-menu-align-target md-svg-icon="call:phone"></md-icon>
- *     Do Something
- *   </md-button>
- * </md-menu-item>
+ * <md-menu-content ng-mouseleave="$mdMenu.close()">
+ *   <md-menu-item>
+ *     <md-button ng-click="doSomething()" aria-label="Do something" md-prevent-menu-close="md-prevent-menu-close">
+ *       <md-icon md-menu-align-target md-svg-icon="call:phone"></md-icon>
+ *       Do Something
+ *     </md-button>
+ *   </md-menu-item>
+ * </md-menu-content>
  * </hljs>
  *
  * @usage
  * <hljs lang="html">
  * <md-menu>
- *  <md-button ng-click="$mdOpenMenu($event)" class="md-icon-button">
+ *  <md-button ng-click="$mdMenu.open($event)" class="md-icon-button">
  *    <md-icon md-svg-icon="call:phone"></md-icon>
  *  </md-button>
  *  <md-menu-content>
diff --git a/src/components/menu/menu.spec.js b/src/components/menu/menu.spec.js
@@ -66,25 +66,23 @@ describe('material.components.menu', function() {
     });
 
     it('opens on click without $event', function() {
-      var noEvent = true;
-      var menu = setup('ng-click', noEvent);
+      var menu = setup('ng-click="$mdMenu.open()"');
       openMenu(menu);
       expect(getOpenMenuContainer(menu).length).toBe(1);
       closeMenu(menu);
       expect(getOpenMenuContainer(menu).length).toBe(0);
     });
 
     it('opens on mouseEnter', function() {
-        var menu = setup('ng-mouseenter');
+        var menu = setup('ng-mouseenter="$mdMenu.open($event)"');
         openMenu(menu, 'mouseenter');
         expect(getOpenMenuContainer(menu).length).toBe(1);
         closeMenu(menu);
         expect(getOpenMenuContainer(menu).length).toBe(0);
       });
 
     it('opens on mouseEnter without $event', function() {
-        var noEvent = true;
-        var menu = setup('ng-mouseenter', noEvent);
+        var menu = setup('ng-mouseenter="$mdMenu.open()"');
         openMenu(menu, 'mouseenter');
         expect(getOpenMenuContainer(menu).length).toBe(1);
         closeMenu(menu);
@@ -116,7 +114,7 @@ describe('material.components.menu', function() {
 
     it('should remove the backdrop if the container scope got destroyed', inject(function($document, $rootScope) {
       var scope = $rootScope.$new();
-      var menu = setup(null, null, scope);
+      var menu = setup(null, scope);
 
       openMenu(menu);
       expect($document.find('md-backdrop').length).not.toBe(0);
@@ -203,7 +201,7 @@ describe('material.components.menu', function() {
       it('should focus a button with md-menu-focus-target', inject(function($compile, $rootScope, $document) {
         var menu = $compile(
           '<md-menu>' +
-            '<button ng-click="$mdOpenMenu($event)">Hello World</button>' +
+            '<button ng-click="$mdMenu.open($event)">Hello World</button>' +
             '<md-menu-content>' +
               '<md-menu-item>' +
                 '<button ng-click="doSomething($event)"></button>' +
@@ -225,7 +223,7 @@ describe('material.components.menu', function() {
       it('should focus a button with md-autofocus', inject(function($compile, $rootScope, $document) {
         var menu = $compile(
           '<md-menu>' +
-            '<button ng-click="$mdOpenMenu($event)">Hello World</button>' +
+            '<button ng-click="$mdMenu.open($event)">Hello World</button>' +
             '<md-menu-content>' +
               '<md-menu-item>' +
                 '<button ng-click="doSomething($event)"></button>' +
@@ -266,6 +264,18 @@ describe('material.components.menu', function() {
         expect(getOpenMenuContainer(menu).length).toBe(0);
       });
 
+      it('closes via the scope method', function() {
+        var menu = setup('ng-mouseenter="$mdMenu.open($event)" ng-mouseleave="$mdMenu.close()"');
+
+        expect(getOpenMenuContainer(menu).length).toBe(0);
+        openMenu(menu, 'mouseenter');
+        expect(getOpenMenuContainer(menu).length).toBe(1);
+
+        menu.find('button').triggerHandler('mouseleave');
+        waitForMenuClose();
+        expect(getOpenMenuContainer(menu).length).toBe(0);
+      });
+
       itClosesWithAttributes([
         'data-ng-click', 'x-ng-click',
         'ui-sref', 'data-ui-sref', 'x-ui-sref',
@@ -278,10 +288,10 @@ describe('material.components.menu', function() {
         }
 
         function testAttribute(attr) {
-          return inject(function($rootScope, $compile, $timeout, $browser) {
+          return inject(function($rootScope, $compile, $timeout) {
             var template = '' +
               '<md-menu>' +
-              ' <button ng-click="$mdOpenMenu($event)">Hello World</button>' +
+              ' <button ng-click="$mdMenu.open($event)">Hello World</button>' +
               ' <md-menu-content>' +
               '  <md-menu-item>' +
               '    <md-button ' + attr + '=""></md-button>' +
@@ -307,17 +317,17 @@ describe('material.components.menu', function() {
       }
     });
 
-    function setup(triggerType, noEvent, scope) {
+    function setup(buttonAttrs, scope) {
       var menu,
         template = $mdUtil.supplant('' +
           '<md-menu>' +
-          ' <button {0}="$mdOpenMenu({1})">Hello World</button>' +
+          ' <button {0}>Hello World</button>' +
           ' <md-menu-content>' +
           '  <md-menu-item>' +
           '    <md-button ng-click="doSomething($event)"></md-button>' +
           '  </md-menu-item>' +
           ' </md-menu-content>' +
-          '</md-menu>',[ triggerType || 'ng-click', noEvent ? '' : "$event" ]);
+          '</md-menu>', [ buttonAttrs || 'ng-click="$mdMenu.open($event)"' ]);
 
       inject(function($compile, $rootScope) {
         $rootScope.doSomething = function($event) {
@@ -357,7 +367,6 @@ describe('material.components.menu', function() {
 
   function closeMenu() {
     inject(function($document) {
-      $document.find('md-backdrop');
       $document.find('md-backdrop').triggerHandler('click');
       waitForMenuClose();
     });
diff --git a/src/components/menuBar/demoBasicUsage/index.html b/src/components/menuBar/demoBasicUsage/index.html
diff --git a/src/components/menuBar/js/menuBarDirective.js b/src/components/menuBar/js/menuBarDirective.js
