feat(mdThemingProvider): add alwaysWatchTheme options, fix docs

docs/content/Theming/02_using_themes.md

@@ -68,9 +68,20 @@ Individual components can also override the inherited theme:
 
 <img src="https://cloud.githubusercontent.com/assets/210413/4825301/a45d735a-5f63-11e4-8597-60386f35fc68.png" alt="progress bars themed" style="max-width: 100%;">
 
+### Watching Themes
 To optimize performance, themable components do not watch a theme after it is
 set. This means, that if your theme is assigned dynamically, the component will
 not update to reflect it. If you have a dynamic attribute (ie.
 interpolated) for a theme, you will want to use the attribute `md-theme-watch="true"` on the
 relevant components so that it will watch the theme for changes. For an example
 of this see [this plunkr](http://plnkr.co/edit/0Ga0BSJgjGIiEMVXgWJd?p=preview).
+
+If you would like themable directives to *always* watch for theme changes by
+default, and are willing to take a performance hit for it, you may configure
+this default behavior by enabling it on `$mdThemingProvider`.
+
+<hljs lang="js">
+app.config(function($mdThemingProvider) {
+  $mdThemingProvider.alwaysWatchTheme(true);
+});
+</hljs>

src/services/theming/theming.js

@@ -1,7 +1,7 @@
 /*
  * @ngdoc module
  * @name material.services.theming
- * @description InterimElement
+ * @description Used to provide theming to angular-material directives
  */
 
 angular.module('material.services.theming', [
@@ -18,13 +18,33 @@ angular.module('material.services.theming', [
   Theming
 ]);
 
-/*
+/**
  * @ngdoc provider
+ * @name $mdThemingProvider
+ *
+ * @description Provider to configure the `$mdTheming` service.
+ */
+
+/**
+ * @ngdoc method
+ * @name $mdThemingProvider#setDefaultTheme
+ * @param {string} themeName Default theme name to be applied to elements. Default value is `default`.
+ */
+
+/**
+ * @ngdoc method
+ * @name $mdThemingProvider#alwaysWatchTheme
+ * @param {boolean} watch Whether or not to always watch themes for changes and re-apply
+ * classes when they change. Default is `false`. Enabling can reduce performance.
+ */
+
+/**
+ * @ngdoc service
  * @name $mdTheming
  *
  * @description
  *
- * Provider that makes an element apply theming related classes to itself.
+ * Service that makes an element apply theming related classes to itself.
  *
  * ```js
  * app.directive('myFancyDirective', function($mdTheming) {
@@ -37,25 +57,27 @@ angular.module('material.services.theming', [
  * });
  * ```
  * @param {el=} element to apply theming to
- *
- * @returns {$$interimElement.$service}
- *
  */
 
 function Theming($injector) {
   var defaultTheme = 'default';
+  var alwaysWatchTheme = false;
   return {
     setDefaultTheme: function(theme) {
       defaultTheme = theme;
     },
+    alwaysWatchTheme: function(alwaysWatch) {
+      alwaysWatchTheme = alwaysWatch;
+    },
     $get: ['$rootElement', '$rootScope', ThemingService]
   };
 
   function ThemingService($rootElement, $rootScope) {
     applyTheme.inherit = function(el, parent) {
       var ctrl = parent.controller('mdTheme');
 
-      if (angular.isDefined(el.attr('md-theme-watch'))) { 
+      var attrThemeValue = el.attr('md-theme-watch');
+      if ( (alwaysWatchTheme || angular.isDefined(attrThemeValue)) && attrThemeValue != 'false') { 
         var deregisterWatch = $rootScope.$watch(function() { 
           return ctrl && ctrl.$mdTheme || defaultTheme; 
         }, changeTheme);

src/services/theming/theming.spec.js

@@ -79,6 +79,11 @@ describe('md-theme directive', function() {
 describe('md-themable directive', function() {
   beforeEach(module('material.services.theming'));
 
+  var $mdThemingProvider;
+  beforeEach(module('material.services.theming', function(_$mdThemingProvider_) {
+    $mdThemingProvider = _$mdThemingProvider_;
+  }));
+
   it('should inherit parent theme', inject(function($compile, $rootScope) {
     var el = $compile('<div md-theme="a"><span md-themable></span></div>')($rootScope);
     $rootScope.$apply();
@@ -106,4 +111,17 @@ describe('md-themable directive', function() {
     expect(el.children().hasClass('md-blue-theme')).toBe(false);
     expect(el.children().hasClass('md-red-theme')).toBe(true);
   }));
+
+  it('should support watching parent theme by default', function() {
+    $mdThemingProvider.alwaysWatchTheme(true);
+    inject(function($rootScope, $compile, $mdTheming) {
+      $rootScope.themey = 'red';
+      var el = $compile('<div md-theme="{{themey}}"><span md-themable></span></div>')($rootScope);
+      $rootScope.$apply();
+      expect(el.children().hasClass('md-red-theme')).toBe(true);
+      $rootScope.$apply('themey = "blue"');
+      expect(el.children().hasClass('md-blue-theme')).toBe(false);
+      expect(el.children().hasClass('md-red-theme')).toBe(true);
+    });
+  });
 });