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

Commit 0018fe9

Browse files
topherfangioThomasBurleson
topherfangio
authored and
ThomasBurleson
committed
docs($mdToast): Update docs with more info and better style.
It was not clear that the `$mdToast.simple()` method returned an object which also had all of the methods/options available from the `build()` and `show()` methods. * add a short comment to inform developers. * update styles to be more readable. Fixes #2420. Closes #5550.
1 parent d6d7b08 commit 0018fe9

File tree

1 file changed

+155
-144
lines changed

1 file changed

+155
-144
lines changed

‎src/components/toast/toast.js

Lines changed: 155 additions & 144 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
/**
2-
* @ngdoc module
3-
* @name material.components.toast
4-
* @description
5-
* Toast
6-
*/
2+
* @ngdoc module
3+
* @name material.components.toast
4+
* @description
5+
* Toast
6+
*/
77
angular.module('material.components.toast', [
88
'material.core',
99
'material.components.button'
@@ -26,159 +26,170 @@ function MdToastDirective($mdToast) {
2626
}
2727

2828
/**
29-
* @ngdoc service
30-
* @name $mdToast
31-
* @module material.components.toast
32-
*
33-
* @description
34-
* `$mdToast` is a service to build a toast notification on any position
35-
* on the screen with an optional duration, and provides a simple promise API.
36-
*
37-
*
38-
* ## Restrictions on custom toasts
39-
* - The toast's template must have an outer `<md-toast>` element.
40-
* - For a toast action, use element with class `md-action`.
41-
* - Add the class `md-capsule` for curved corners.
42-
*
43-
* @usage
44-
* <hljs lang="html">
45-
* <div ng-controller="MyController">
46-
* <md-button ng-click="openToast()">
47-
* Open a Toast!
48-
* </md-button>
49-
* </div>
50-
* </hljs>
51-
*
52-
* <hljs lang="js">
53-
* var app = angular.module('app', ['ngMaterial']);
54-
* app.controller('MyController', function($scope, $mdToast) {
55-
* $scope.openToast = function($event) {
56-
* $mdToast.show($mdToast.simple().content('Hello!'));
57-
* // Could also do $mdToast.showSimple('Hello');
58-
* };
59-
* });
60-
* </hljs>
61-
*/
29+
* @ngdoc service
30+
* @name $mdToast
31+
* @module material.components.toast
32+
*
33+
* @description
34+
* `$mdToast` is a service to build a toast notification on any position
35+
* on the screen with an optional duration, and provides a simple promise API.
36+
*
37+
*
38+
* ## Restrictions on custom toasts
39+
* - The toast's template must have an outer `<md-toast>` element.
40+
* - For a toast action, use element with class `md-action`.
41+
* - Add the class `md-capsule` for curved corners.
42+
*
43+
* @usage
44+
* <hljs lang="html">
45+
* <div ng-controller="MyController">
46+
* <md-button ng-click="openToast()">
47+
* Open a Toast!
48+
* </md-button>
49+
* </div>
50+
* </hljs>
51+
*
52+
* <hljs lang="js">
53+
* var app = angular.module('app', ['ngMaterial']);
54+
* app.controller('MyController', function($scope, $mdToast) {
55+
* $scope.openToast = function($event) {
56+
* $mdToast.show($mdToast.simple().content('Hello!'));
57+
* // Could also do $mdToast.showSimple('Hello');
58+
* };
59+
* });
60+
* </hljs>
61+
*/
6262

6363
/**
64-
* @ngdoc method
65-
* @name $mdToast#showSimple
66-
*
67-
* @description
68-
* Convenience method which builds and shows a simple toast.
69-
*
70-
* @returns {promise} A promise that can be resolved with `$mdToast.hide()` or
71-
* rejected with `$mdToast.cancel()`.
72-
*
73-
*/
64+
* @ngdoc method
65+
* @name $mdToast#showSimple
66+
*
67+
* @description
68+
* Convenience method which builds and shows a simple toast.
69+
*
70+
* @returns {promise} A promise that can be resolved with `$mdToast.hide()` or
71+
* rejected with `$mdToast.cancel()`.
72+
*
73+
*/
7474

7575
/**
76-
* @ngdoc method
77-
* @name $mdToast#simple
78-
*
79-
* @description
80-
* Builds a preconfigured toast.
81-
*
82-
* @returns {obj} a `$mdToastPreset` with the chainable configuration methods:
83-
*
84-
* - $mdToastPreset#content(string) - sets toast content to string
85-
* - $mdToastPreset#action(string) - adds an action button. If clicked the promise (returned from `show()`) will resolve
86-
* with value 'ok'; otherwise it promise is resolved with 'true' after a hideDelay timeout.
87-
* - $mdToastPreset#highlightAction(boolean) - sets action button to be highlighted
88-
* - $mdToastPreset#capsule(boolean) - adds 'md-capsule' class to the toast (curved corners)
89-
* - $mdToastPreset#theme(string) - sets the theme on the toast to theme (default is `$mdThemingProvider`'s default theme)
90-
*/
76+
* @ngdoc method
77+
* @name $mdToast#simple
78+
*
79+
* @description
80+
* Builds a preconfigured toast.
81+
*
82+
* @returns {obj} a `$mdToastPreset` with the following chainable configuration methods.
83+
*
84+
* _**Note:** These configuration methods are provided in addition to the methods provided by
85+
* the `build()` and `show()` methods below._
86+
*
87+
* - `.content(string)` - Sets the toast content to the specified string.
88+
*
89+
* - `.action(string)` - Adds an action button. If clicked, the promise (returned from `show()`)
90+
* will resolve with the value `'ok'`; otherwise, it is resolved with `true` after a `hideDelay`
91+
* timeout.
92+
*
93+
* - `.highlightAction(boolean)` - Whether or not the action button will have an additional
94+
* highlight class.
95+
*
96+
* - `.capsule(boolean)` - Whether or not to add the `md-capsule` class to the toast to provide
97+
* rounded corners.
98+
*
99+
* - `.theme(string)` - Sets the theme on the toast to the requested theme. Default is
100+
* `$mdThemingProvider`'s default.
101+
*/
91102

92103
/**
93-
* @ngdoc method
94-
* @name $mdToast#updateContent
95-
*
96-
* @description
97-
* Updates the content of an existing toast. Useful for updating things like counts, etc.
98-
*
99-
*/
104+
* @ngdoc method
105+
* @name $mdToast#updateContent
106+
*
107+
* @description
108+
* Updates the content of an existing toast. Useful for updating things like counts, etc.
109+
*
110+
*/
100111

101112
/**
102-
* @ngdoc method
103-
* @name $mdToast#build
104-
*
105-
* @description
106-
* Creates a custom `$mdToastPreset` that you can configure.
107-
*
108-
* @returns {obj} a `$mdToastPreset` with the chainable configuration methods for shows' options (see below).
109-
*/
113+
* @ngdoc method
114+
* @name $mdToast#build
115+
*
116+
* @description
117+
* Creates a custom `$mdToastPreset` that you can configure.
118+
*
119+
* @returns {obj} a `$mdToastPreset` with the chainable configuration methods for shows' options (see below).
120+
*/
110121

111122
/**
112-
* @ngdoc method
113-
* @name $mdToast#show
114-
*
115-
* @description Shows the toast.
116-
*
117-
* @param {object} optionsOrPreset Either provide an `$mdToastPreset` returned from `simple()`
118-
* and `build()`, or an options object with the following properties:
119-
*
120-
* - `templateUrl` - `{string=}`: The url of an html template file that will
121-
* be used as the content of the toast. Restrictions: the template must
122-
* have an outer `md-toast` element.
123-
* - `template` - `{string=}`: Same as templateUrl, except this is an actual
124-
* template string.
125-
* - `scope` - `{object=}`: the scope to link the template / controller to. If none is specified, it will create a new child scope.
126-
* This scope will be destroyed when the toast is removed unless `preserveScope` is set to true.
127-
* - `preserveScope` - `{boolean=}`: whether to preserve the scope when the element is removed. Default is false
128-
* - `hideDelay` - `{number=}`: How many milliseconds the toast should stay
129-
* active before automatically closing. Set to 0 or false to have the toast stay open until
130-
* closed manually. Default: 3000.
131-
* - `position` - `{string=}`: Where to place the toast. Available: any combination
132-
* of 'bottom', 'left', 'top', 'right', 'fit'. Default: 'bottom left'.
133-
* - `controller` - `{string=}`: The controller to associate with this toast.
134-
* The controller will be injected the local `$mdToast.hide( )`, which is a function
135-
* used to hide the toast.
136-
* - `locals` - `{string=}`: An object containing key/value pairs. The keys will
137-
* be used as names of values to inject into the controller. For example,
138-
* `locals: {three: 3}` would inject `three` into the controller with the value
139-
* of 3.
140-
* - `bindToController` - `bool`: bind the locals to the controller, instead of passing them in. These values will not be available until after initialization.
141-
* - `resolve` - `{object=}`: Similar to locals, except it takes promises as values
142-
* and the toast will not open until the promises resolve.
143-
* - `controllerAs` - `{string=}`: An alias to assign the controller to on the scope.
144-
* - `parent` - `{element=}`: The element to append the toast to. Defaults to appending
145-
* to the root element of the application.
146-
*
147-
* @returns {promise} A promise that can be resolved with `$mdToast.hide()` or
148-
* rejected with `$mdToast.cancel()`. `$mdToast.hide()` will resolve either with a Boolean
149-
* value == 'true' or the value passed as an argument to `$mdToast.hide()`.
150-
* And `$mdToast.cancel()` will resolve the promise with a Boolean value == 'false'
151-
*/
123+
* @ngdoc method
124+
* @name $mdToast#show
125+
*
126+
* @description Shows the toast.
127+
*
128+
* @param {object} optionsOrPreset Either provide an `$mdToastPreset` returned from `simple()`
129+
* and `build()`, or an options object with the following properties:
130+
*
131+
* - `templateUrl` - `{string=}`: The url of an html template file that will
132+
* be used as the content of the toast. Restrictions: the template must
133+
* have an outer `md-toast` element.
134+
* - `template` - `{string=}`: Same as templateUrl, except this is an actual
135+
* template string.
136+
* - `scope` - `{object=}`: the scope to link the template / controller to. If none is specified, it will create a new child scope.
137+
* This scope will be destroyed when the toast is removed unless `preserveScope` is set to true.
138+
* - `preserveScope` - `{boolean=}`: whether to preserve the scope when the element is removed. Default is false
139+
* - `hideDelay` - `{number=}`: How many milliseconds the toast should stay
140+
* active before automatically closing. Set to 0 or false to have the toast stay open until
141+
* closed manually. Default: 3000.
142+
* - `position` - `{string=}`: Where to place the toast. Available: any combination
143+
* of 'bottom', 'left', 'top', 'right', 'fit'. Default: 'bottom left'.
144+
* - `controller` - `{string=}`: The controller to associate with this toast.
145+
* The controller will be injected the local `$mdToast.hide( )`, which is a function
146+
* used to hide the toast.
147+
* - `locals` - `{string=}`: An object containing key/value pairs. The keys will
148+
* be used as names of values to inject into the controller. For example,
149+
* `locals: {three: 3}` would inject `three` into the controller with the value
150+
* of 3.
151+
* - `bindToController` - `bool`: bind the locals to the controller, instead of passing them in. These values will not be available until after initialization.
152+
* - `resolve` - `{object=}`: Similar to locals, except it takes promises as values
153+
* and the toast will not open until the promises resolve.
154+
* - `controllerAs` - `{string=}`: An alias to assign the controller to on the scope.
155+
* - `parent` - `{element=}`: The element to append the toast to. Defaults to appending
156+
* to the root element of the application.
157+
*
158+
* @returns {promise} A promise that can be resolved with `$mdToast.hide()` or
159+
* rejected with `$mdToast.cancel()`. `$mdToast.hide()` will resolve either with a Boolean
160+
* value == 'true' or the value passed as an argument to `$mdToast.hide()`.
161+
* And `$mdToast.cancel()` will resolve the promise with a Boolean value == 'false'
162+
*/
152163

153164
/**
154-
* @ngdoc method
155-
* @name $mdToast#hide
156-
*
157-
* @description
158-
* Hide an existing toast and resolve the promise returned from `$mdToast.show()`.
159-
*
160-
* @param {*=} response An argument for the resolved promise.
161-
*
162-
* @returns {promise} a promise that is called when the existing element is removed from the DOM.
163-
* The promise is resolved with either a Boolean value == 'true' or the value passed as the
164-
* argument to `.hide()`.
165-
*
166-
*/
165+
* @ngdoc method
166+
* @name $mdToast#hide
167+
*
168+
* @description
169+
* Hide an existing toast and resolve the promise returned from `$mdToast.show()`.
170+
*
171+
* @param {*=} response An argument for the resolved promise.
172+
*
173+
* @returns {promise} a promise that is called when the existing element is removed from the DOM.
174+
* The promise is resolved with either a Boolean value == 'true' or the value passed as the
175+
* argument to `.hide()`.
176+
*
177+
*/
167178

168179
/**
169-
* @ngdoc method
170-
* @name $mdToast#cancel
171-
*
172-
* @description
173-
* Hide the existing toast and reject the promise returned from
174-
* `$mdToast.show()`.
175-
*
176-
* @param {*=} response An argument for the rejected promise.
177-
*
178-
* @returns {promise} a promise that is called when the existing element is removed from the DOM
179-
* The promise is resolved with a Boolean value == 'false'.
180-
*
181-
*/
180+
* @ngdoc method
181+
* @name $mdToast#cancel
182+
*
183+
* @description
184+
* Hide the existing toast and reject the promise returned from
185+
* `$mdToast.show()`.
186+
*
187+
* @param {*=} response An argument for the rejected promise.
188+
*
189+
* @returns {promise} a promise that is called when the existing element is removed from the DOM
190+
* The promise is resolved with a Boolean value == 'false'.
191+
*
192+
*/
182193

183194
function MdToastProvider($$interimElementProvider) {
184195
// Differentiate promise resolves: hide timeout (value == true) and hide action clicks (value == ok).

0 commit comments

Comments
 (0)