Skip to content
This repository was archived by the owner on Sep 5, 2024. It is now read-only.

docs(mdThemingProvider): add missing documentation #11209

Merged
merged 1 commit into from
Apr 6, 2018
Merged

docs(mdThemingProvider): add missing documentation #11209

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
248 changes: 146 additions & 102 deletions src/core/services/theming/theming.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,42 +119,7 @@ function detectDisabledThemes($mdThemingProvider) {
*/

/**
* @ngdoc method
* @name $mdThemingProvider#registerStyles
* @param {string} styles The styles to be appended to AngularJS Material's built in theme css.
*/
/**
* @ngdoc method
* @name $mdThemingProvider#setNonce
* @param {string} nonceValue The nonce to be added as an attribute to the theme style tags.
* Setting a value allows the use of CSP policy without using the unsafe-inline directive.
*/

/**
* @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 method
* @name $mdThemingProvider#enableBrowserColor
* @param {Object=} options Options object for the browser color<br/>
* `theme` - A defined theme via `$mdThemeProvider` to use the palettes from. Default is `default` theme. <br/>
* `palette` - Can be any one of the basic material design palettes, extended defined palettes and 'primary',
* 'accent', 'background' and 'warn'. Default is `primary`. <br/>
* `hue` - The hue from the selected palette. Default is `800`<br/>
* @returns {Function} remove function of the browser color
*/

/* Some Example Valid Theming Expressions
* Some Example Valid Theming Expressions
* =======================================
*
* Intention group expansion: (valid for primary, accent, warn, background)
Expand All @@ -175,7 +140,6 @@ function detectDisabledThemes($mdThemingProvider) {
* {{foreground-2}} - used for secondary text/divider
* {{foreground-3}} - used for disabled text
* {{foreground-4}} - used for dividers
*
*/

// In memory generated CSS rules; registered by theme.name
Expand Down Expand Up @@ -279,7 +243,7 @@ function ThemingProvider($mdColorPalette, $$mdMetaProvider) {
/**
* Adds `theme-color` and `msapplication-navbutton-color` meta tags with the color parameter
* @param {string} color Hex value of the wanted browser color
* @returns {Function} Remove function of the meta tags
* @returns {function} Remove function of the meta tags
*/
var setBrowserColor = function (color) {
// Chrome, Firefox OS and Opera
Expand All @@ -294,20 +258,18 @@ function ThemingProvider($mdColorPalette, $$mdMetaProvider) {
};

/**
* Enables browser header coloring
* for more info please visit:
* https://developers.google.com/web/fundamentals/design-and-ui/browser-customization/theme-color
*
* The default color is `800` from `primary` palette of the `default` theme
*
* options are:
* `theme` - A defined theme via `$mdThemeProvider` to use the palettes from. Default is `default` theme
* `palette` - Can be any one of the basic material design palettes, extended defined palettes and 'primary',
* 'accent', 'background' and 'warn'. Default is `primary`
* `hue` - The hue from the selected palette. Default is `800`
*
* @param {Object=} options Options object for the browser color
* @returns {Function} remove function of the browser color
* @ngdoc method
* @name $mdThemingProvider#enableBrowserColor
* @description
* Enables browser header coloring. For more info please visit
* <a href="https://developers.google.com/web/fundamentals/design-and-ui/browser-customization/theme-color">
* Web Fundamentals</a>.
* @param {object=} options Options for the browser color, which include:<br/>
* - `theme` - `{string}`: A defined theme via `$mdThemeProvider` to use the palettes from. Default is `default` theme. <br/>
* - `palette` - `{string}`: Can be any one of the basic material design palettes, extended defined palettes, or `primary`,
* `accent`, `background`, and `warn`. Default is `primary`.<br/>
* - `hue` - `{string}`: The hue from the selected palette. Default is `800`.<br/>
* @returns {function} Function that removes the browser coloring when called.
*/
var enableBrowserColor = function (options) {
options = angular.isObject(options) ? options : {};
Expand Down Expand Up @@ -340,18 +302,33 @@ function ThemingProvider($mdColorPalette, $$mdMetaProvider) {
},

/**
* Easy way to disable theming without having to use
* `.constant("$MD_THEME_CSS","");` This disables
* all dynamic theme style sheet generations and injections...
* @ngdoc method
* @name $mdThemingProvider#disableTheming
* @description
* An easier way to disable theming without having to use `.constant("$MD_THEME_CSS","");`.
* This disables all dynamic theme style sheet generations and injections.
* @param {boolean=} isDisabled Disable all dynamic theme style sheet generations and injections
* if `true` or `undefined`.
*/
disableTheming: function(isDisabled) {
themeConfig.disableTheming = angular.isUndefined(isDisabled) || !!isDisabled;
},

/**
* @ngdoc method
* @name $mdThemingProvider#registerStyles
* @param {string} styles The styles to be appended to AngularJS Material's built in theme CSS.
*/
registerStyles: function(styles) {
themeConfig.registeredStyles.push(styles);
},

/**
* @ngdoc method
* @name $mdThemingProvider#setNonce
* @param {string} nonceValue The nonce to be added as an attribute to the theme style tags.
* Setting a value allows the use of CSP policy without using the unsafe-inline directive.
*/
setNonce: function(nonceValue) {
themeConfig.nonce = nonceValue;
},
Expand All @@ -360,10 +337,21 @@ function ThemingProvider($mdColorPalette, $$mdMetaProvider) {
themeConfig.generateOnDemand = onDemand;
},

/**
* @ngdoc method
* @name $mdThemingProvider#setDefaultTheme
* @param {string} theme Default theme name to be applied to elements. Default value is `default`.
*/
setDefaultTheme: function(theme) {
defaultTheme = theme;
},

/**
* @ngdoc method
* @name $mdThemingProvider#alwaysWatchTheme
* @param {boolean} alwaysWatch Whether or not to always watch themes for changes and re-apply
* classes when they change. Default is `false`. Enabling can reduce performance.
*/
alwaysWatchTheme: function(alwaysWatch) {
alwaysWatchTheme = alwaysWatch;
},
Expand All @@ -379,16 +367,71 @@ function ThemingProvider($mdColorPalette, $$mdMetaProvider) {
_rgba: rgba
};

// Example: $mdThemingProvider.definePalette('neonRed', { 50: '#f5fafa', ... });
/**
* @ngdoc method
* @name $mdThemingProvider#definePalette
* @description
* In the event that you need to define a custom color palette, you can use this function to
* make it available to your theme for use in its intention groups.<br>
* Note that you must specify all hues in the definition map.
* @param {string} name Name of palette being defined
* @param {object} map Palette definition that includes hue definitions and contrast colors:
* - `'50'` - `{string}`: HEX color
* - `'100'` - `{string}`: HEX color
* - `'200'` - `{string}`: HEX color
* - `'300'` - `{string}`: HEX color
* - `'400'` - `{string}`: HEX color
* - `'500'` - `{string}`: HEX color
* - `'600'` - `{string}`: HEX color
* - `'700'` - `{string}`: HEX color
* - `'800'` - `{string}`: HEX color
* - `'900'` - `{string}`: HEX color
* - `'A100'` - `{string}`: HEX color
* - `'A200'` - `{string}`: HEX color
* - `'A400'` - `{string}`: HEX color
* - `'A700'` - `{string}`: HEX color
* - `'contrastDefaultColor'` - `{string}`: `light` or `dark`
* - `'contrastDarkColors'` - `{string[]}`: Hues which should use dark contrast colors (i.e. raised button text).
* For example: `['50', '100', '200', '300', '400', 'A100']`.
* - `'contrastLightColors'` - `{string[]}`: Hues which should use light contrast colors (i.e. raised button text).
* For example: `['500', '600', '700', '800', '900', 'A200', 'A400', 'A700']`.
*/
function definePalette(name, map) {
map = map || {};
PALETTES[name] = checkPaletteValid(name, map);
return themingProvider;
}

// Returns an new object which is a copy of a given palette `name` with variables from
// `map` overwritten
// Example: var neonRedMap = $mdThemingProvider.extendPalette('red', { 50: '#f5fafafa' });
/**
* @ngdoc method
* @name $mdThemingProvider#extendPalette
* @description
* Sometimes it is easier to extend an existing color palette and then change a few properties,
* rather than defining a whole new palette.
* @param {string} name Name of palette being extended
* @param {object} map Palette definition that includes optional hue definitions and contrast colors:
* - `'50'` - `{string}`: HEX color
* - `'100'` - `{string}`: HEX color
* - `'200'` - `{string}`: HEX color
* - `'300'` - `{string}`: HEX color
* - `'400'` - `{string}`: HEX color
* - `'500'` - `{string}`: HEX color
* - `'600'` - `{string}`: HEX color
* - `'700'` - `{string}`: HEX color
* - `'800'` - `{string}`: HEX color
* - `'900'` - `{string}`: HEX color
* - `'A100'` - `{string}`: HEX color
* - `'A200'` - `{string}`: HEX color
* - `'A400'` - `{string}`: HEX color
* - `'A700'` - `{string}`: HEX color
* - `'contrastDefaultColor'` - `{string}`: `light` or `dark`
* - `'contrastDarkColors'` - `{string[]}`: Hues which should use dark contrast colors (i.e. raised button text).
* For example: `['50', '100', '200', '300', '400', 'A100']`.
* - `'contrastLightColors'` - `{string[]}`: Hues which should use light contrast colors (i.e. raised button text).
* For example: `['500', '600', '700', '800', '900', 'A200', 'A400', 'A700']`.
* @returns {object} A new object which is a copy of the given palette, `name`,
* with variables from `map` overwritten.
*/
function extendPalette(name, map) {
return checkPaletteValid(name, angular.extend({}, PALETTES[name] || {}, map) );
}
Expand All @@ -407,10 +450,16 @@ function ThemingProvider($mdColorPalette, $$mdMetaProvider) {
return map;
}

// Register a theme (which is a collection of color palettes to use with various states
// ie. warn, accent, primary )
// Optionally inherit from an existing theme
// $mdThemingProvider.theme('custom-theme').primaryPalette('red');
/**
* @ngdoc method
* @name $mdThemingProvider#theme
* @description
* Register a theme (which is a collection of color palettes); i.e. `warn`, `accent`,
* `background`, and `primary`.<br>
* Optionally inherit from an existing theme.
* @param {string} name Name of theme being registered
* @param {string=} inheritFrom Existing theme name to inherit from
*/
function registerTheme(name, inheritFrom) {
if (THEMES[name]) return THEMES[name];

Expand Down Expand Up @@ -522,44 +571,45 @@ function ThemingProvider($mdColorPalette, $$mdMetaProvider) {
* @ngdoc service
* @name $mdTheming
* @module material.core.theming
*
* @description
*
* Service that makes an element apply theming related <b>classes</b> to itself.
*
* <hljs lang="js">
* // Example component directive that we want to apply theming classes to.
* app.directive('myFancyDirective', function($mdTheming) {
* return {
* restrict: 'e',
* link: function(scope, el, attrs) {
* $mdTheming(el);
* restrict: 'AE',
* link: function(scope, element, attrs) {
* // Initialize the service using our directive's element
* $mdTheming(element);
*
* $mdTheming.defineTheme('myTheme', {
* primary: 'blue',
* accent: 'pink',
* dark: true
* })
* });
* // Your directive's custom code here.
* }
* };
* });
* </hljs>
* @param {element=} element to apply theming to
* @param {element=} element Element that will have theming classes applied to it.
*/

/**
* @ngdoc property
* @name $mdTheming#THEMES
* @description
* Property to get all the themes defined
* @returns {Object} All the themes defined with their properties
* @returns {object} All the themes defined with their properties.
*/

/**
* @ngdoc property
* @name $mdTheming#PALETTES
* @description
* Property to get all the palettes defined
* @returns {Object} All the palettes defined with their colors
* @returns {object} All the palettes defined with their colors.
*/

/**
Expand Down Expand Up @@ -596,48 +646,42 @@ function ThemingProvider($mdColorPalette, $$mdMetaProvider) {
* @ngdoc method
* @name $mdTheming#setBrowserColor
* @description
* Sets browser header coloring
* for more info please visit:
* https://developers.google.com/web/fundamentals/design-and-ui/browser-customization/theme-color
*
* The default color is `800` from `primary` palette of the `default` theme
*
* options are:<br/>
* `theme` - A defined theme via `$mdThemeProvider` to use the palettes from. Default is `default` theme.<br/>
* `palette` - Can be any one of the basic material design palettes, extended defined palettes and 'primary',
* 'accent', 'background' and 'warn'. Default is `primary`<br/>
* `hue` - The hue from the selected palette. Default is `800`
*
* @param {Object} options Options object for the browser color
* @returns {Function} remove function of the browser color
* Enables browser header coloring. For more info please visit
* <a href="https://developers.google.com/web/fundamentals/design-and-ui/browser-customization/theme-color">
* Web Fundamentals</a>.
* @param {object=} options Options for the browser color, which include:<br/>
* - `theme` - `{string}`: A defined theme via `$mdThemeProvider` to use the palettes from. Default is `default` theme. <br/>
* - `palette` - `{string}`: Can be any one of the basic material design palettes, extended defined palettes, or `primary`,
* `accent`, `background`, and `warn`. Default is `primary`.<br/>
* - `hue` - `{string}`: The hue from the selected palette. Default is `800`.<br/>
* @returns {function} Function that removes the browser coloring when called.
*/

/**
* @ngdoc method
* @name $mdTheming#defineTheme
* @description
* Dynamically define a theme by an options object
* Dynamically define a theme by using an options object that contains palette names.
*
* options are:<br/>
* `primary` - The primary palette of the theme.<br/>
* `accent` - The accent palette of the theme.<br/>
* `warn` - The warn palette of the theme.<br/>
* `background` - The background palette of the theme.<br/>
* `dark` - Indicates if it's a dark theme.<br/>
*
* @param {String} name Theme name to define
* @param {Object} options Theme definition options
* @returns {Promise<string>} A resolved promise with the theme name
* @param {string} name Theme name to define
* @param {object} options Theme definition options
* Options are:<br/>
* - `primary` - `{string}`: The name of the primary palette to use in the theme.<br/>
* - `accent` - `{string}`: The name of the accent palette to use in the theme.<br/>
* - `warn` - `{string}`: The name of the warn palette to use in the theme.<br/>
* - `background` - `{string}`: The name of the background palette to use in the theme.<br/>
* - `dark` - `{boolean}`: Indicates if it's a dark theme.<br/>
* @returns {Promise<string>} A resolved promise with the new theme name.
*/

/* @ngInject */
function ThemingService($rootScope, $mdUtil, $q, $log) {
// Allow us to be invoked via a linking function signature.
// Allow us to be invoked via a linking function signature.
var applyTheme = function (scope, el) {
if (el === undefined) { el = scope; scope = undefined; }
if (scope === undefined) { scope = $rootScope; }
applyTheme.inherit(el, el);
};
if (el === undefined) { el = scope; scope = undefined; }
if (scope === undefined) { scope = $rootScope; }
applyTheme.inherit(el, el);
};

Object.defineProperty(applyTheme, 'THEMES', {
get: function () {
Expand Down