diff --git a/src/components/toast/toast.js b/src/components/toast/toast.js index 9f742a47b34..60844298c18 100644 --- a/src/components/toast/toast.js +++ b/src/components/toast/toast.js @@ -1,9 +1,9 @@ /** - * @ngdoc module - * @name material.components.toast - * @description - * Toast - */ + * @ngdoc module + * @name material.components.toast + * @description + * Toast + */ angular.module('material.components.toast', [ 'material.core', 'material.components.button' @@ -26,159 +26,170 @@ function MdToastDirective($mdToast) { } /** - * @ngdoc service - * @name $mdToast - * @module material.components.toast - * - * @description - * `$mdToast` is a service to build a toast notification on any position - * on the screen with an optional duration, and provides a simple promise API. - * - * - * ## Restrictions on custom toasts - * - The toast's template must have an outer `` element. - * - For a toast action, use element with class `md-action`. - * - Add the class `md-capsule` for curved corners. - * - * @usage - * - *
- * - * Open a Toast! - * - *
- * - * - * - * var app = angular.module('app', ['ngMaterial']); - * app.controller('MyController', function($scope, $mdToast) { - * $scope.openToast = function($event) { - * $mdToast.show($mdToast.simple().content('Hello!')); - * // Could also do $mdToast.showSimple('Hello'); - * }; - * }); - * - */ + * @ngdoc service + * @name $mdToast + * @module material.components.toast + * + * @description + * `$mdToast` is a service to build a toast notification on any position + * on the screen with an optional duration, and provides a simple promise API. + * + * + * ## Restrictions on custom toasts + * - The toast's template must have an outer `` element. + * - For a toast action, use element with class `md-action`. + * - Add the class `md-capsule` for curved corners. + * + * @usage + * + *
+ * + * Open a Toast! + * + *
+ * + * + * + * var app = angular.module('app', ['ngMaterial']); + * app.controller('MyController', function($scope, $mdToast) { + * $scope.openToast = function($event) { + * $mdToast.show($mdToast.simple().content('Hello!')); + * // Could also do $mdToast.showSimple('Hello'); + * }; + * }); + * + */ /** - * @ngdoc method - * @name $mdToast#showSimple - * - * @description - * Convenience method which builds and shows a simple toast. - * - * @returns {promise} A promise that can be resolved with `$mdToast.hide()` or - * rejected with `$mdToast.cancel()`. - * - */ + * @ngdoc method + * @name $mdToast#showSimple + * + * @description + * Convenience method which builds and shows a simple toast. + * + * @returns {promise} A promise that can be resolved with `$mdToast.hide()` or + * rejected with `$mdToast.cancel()`. + * + */ /** - * @ngdoc method - * @name $mdToast#simple - * - * @description - * Builds a preconfigured toast. - * - * @returns {obj} a `$mdToastPreset` with the chainable configuration methods: - * - * - $mdToastPreset#content(string) - sets toast content to string - * - $mdToastPreset#action(string) - adds an action button. If clicked the promise (returned from `show()`) will resolve - * with value 'ok'; otherwise it promise is resolved with 'true' after a hideDelay timeout. - * - $mdToastPreset#highlightAction(boolean) - sets action button to be highlighted - * - $mdToastPreset#capsule(boolean) - adds 'md-capsule' class to the toast (curved corners) - * - $mdToastPreset#theme(string) - sets the theme on the toast to theme (default is `$mdThemingProvider`'s default theme) - */ + * @ngdoc method + * @name $mdToast#simple + * + * @description + * Builds a preconfigured toast. + * + * @returns {obj} a `$mdToastPreset` with the following chainable configuration methods. + * + * _**Note:** These configuration methods are provided in addition to the methods provided by + * the `build()` and `show()` methods below._ + * + * - `.content(string)` - Sets the toast content to the specified string. + * + * - `.action(string)` - Adds an action button. If clicked, the promise (returned from `show()`) + * will resolve with the value `'ok'`; otherwise, it is resolved with `true` after a `hideDelay` + * timeout. + * + * - `.highlightAction(boolean)` - Whether or not the action button will have an additional + * highlight class. + * + * - `.capsule(boolean)` - Whether or not to add the `md-capsule` class to the toast to provide + * rounded corners. + * + * - `.theme(string)` - Sets the theme on the toast to the requested theme. Default is + * `$mdThemingProvider`'s default. + */ /** - * @ngdoc method - * @name $mdToast#updateContent - * - * @description - * Updates the content of an existing toast. Useful for updating things like counts, etc. - * - */ + * @ngdoc method + * @name $mdToast#updateContent + * + * @description + * Updates the content of an existing toast. Useful for updating things like counts, etc. + * + */ /** - * @ngdoc method - * @name $mdToast#build - * - * @description - * Creates a custom `$mdToastPreset` that you can configure. - * - * @returns {obj} a `$mdToastPreset` with the chainable configuration methods for shows' options (see below). - */ + * @ngdoc method + * @name $mdToast#build + * + * @description + * Creates a custom `$mdToastPreset` that you can configure. + * + * @returns {obj} a `$mdToastPreset` with the chainable configuration methods for shows' options (see below). + */ /** - * @ngdoc method - * @name $mdToast#show - * - * @description Shows the toast. - * - * @param {object} optionsOrPreset Either provide an `$mdToastPreset` returned from `simple()` - * and `build()`, or an options object with the following properties: - * - * - `templateUrl` - `{string=}`: The url of an html template file that will - * be used as the content of the toast. Restrictions: the template must - * have an outer `md-toast` element. - * - `template` - `{string=}`: Same as templateUrl, except this is an actual - * template string. - * - `scope` - `{object=}`: the scope to link the template / controller to. If none is specified, it will create a new child scope. - * This scope will be destroyed when the toast is removed unless `preserveScope` is set to true. - * - `preserveScope` - `{boolean=}`: whether to preserve the scope when the element is removed. Default is false - * - `hideDelay` - `{number=}`: How many milliseconds the toast should stay - * active before automatically closing. Set to 0 or false to have the toast stay open until - * closed manually. Default: 3000. - * - `position` - `{string=}`: Where to place the toast. Available: any combination - * of 'bottom', 'left', 'top', 'right', 'fit'. Default: 'bottom left'. - * - `controller` - `{string=}`: The controller to associate with this toast. - * The controller will be injected the local `$mdToast.hide( )`, which is a function - * used to hide the toast. - * - `locals` - `{string=}`: An object containing key/value pairs. The keys will - * be used as names of values to inject into the controller. For example, - * `locals: {three: 3}` would inject `three` into the controller with the value - * of 3. - * - `bindToController` - `bool`: bind the locals to the controller, instead of passing them in. These values will not be available until after initialization. - * - `resolve` - `{object=}`: Similar to locals, except it takes promises as values - * and the toast will not open until the promises resolve. - * - `controllerAs` - `{string=}`: An alias to assign the controller to on the scope. - * - `parent` - `{element=}`: The element to append the toast to. Defaults to appending - * to the root element of the application. - * - * @returns {promise} A promise that can be resolved with `$mdToast.hide()` or - * rejected with `$mdToast.cancel()`. `$mdToast.hide()` will resolve either with a Boolean - * value == 'true' or the value passed as an argument to `$mdToast.hide()`. - * And `$mdToast.cancel()` will resolve the promise with a Boolean value == 'false' - */ + * @ngdoc method + * @name $mdToast#show + * + * @description Shows the toast. + * + * @param {object} optionsOrPreset Either provide an `$mdToastPreset` returned from `simple()` + * and `build()`, or an options object with the following properties: + * + * - `templateUrl` - `{string=}`: The url of an html template file that will + * be used as the content of the toast. Restrictions: the template must + * have an outer `md-toast` element. + * - `template` - `{string=}`: Same as templateUrl, except this is an actual + * template string. + * - `scope` - `{object=}`: the scope to link the template / controller to. If none is specified, it will create a new child scope. + * This scope will be destroyed when the toast is removed unless `preserveScope` is set to true. + * - `preserveScope` - `{boolean=}`: whether to preserve the scope when the element is removed. Default is false + * - `hideDelay` - `{number=}`: How many milliseconds the toast should stay + * active before automatically closing. Set to 0 or false to have the toast stay open until + * closed manually. Default: 3000. + * - `position` - `{string=}`: Where to place the toast. Available: any combination + * of 'bottom', 'left', 'top', 'right', 'fit'. Default: 'bottom left'. + * - `controller` - `{string=}`: The controller to associate with this toast. + * The controller will be injected the local `$mdToast.hide( )`, which is a function + * used to hide the toast. + * - `locals` - `{string=}`: An object containing key/value pairs. The keys will + * be used as names of values to inject into the controller. For example, + * `locals: {three: 3}` would inject `three` into the controller with the value + * of 3. + * - `bindToController` - `bool`: bind the locals to the controller, instead of passing them in. These values will not be available until after initialization. + * - `resolve` - `{object=}`: Similar to locals, except it takes promises as values + * and the toast will not open until the promises resolve. + * - `controllerAs` - `{string=}`: An alias to assign the controller to on the scope. + * - `parent` - `{element=}`: The element to append the toast to. Defaults to appending + * to the root element of the application. + * + * @returns {promise} A promise that can be resolved with `$mdToast.hide()` or + * rejected with `$mdToast.cancel()`. `$mdToast.hide()` will resolve either with a Boolean + * value == 'true' or the value passed as an argument to `$mdToast.hide()`. + * And `$mdToast.cancel()` will resolve the promise with a Boolean value == 'false' + */ /** - * @ngdoc method - * @name $mdToast#hide - * - * @description - * Hide an existing toast and resolve the promise returned from `$mdToast.show()`. - * - * @param {*=} response An argument for the resolved promise. - * - * @returns {promise} a promise that is called when the existing element is removed from the DOM. - * The promise is resolved with either a Boolean value == 'true' or the value passed as the - * argument to `.hide()`. - * - */ + * @ngdoc method + * @name $mdToast#hide + * + * @description + * Hide an existing toast and resolve the promise returned from `$mdToast.show()`. + * + * @param {*=} response An argument for the resolved promise. + * + * @returns {promise} a promise that is called when the existing element is removed from the DOM. + * The promise is resolved with either a Boolean value == 'true' or the value passed as the + * argument to `.hide()`. + * + */ /** - * @ngdoc method - * @name $mdToast#cancel - * - * @description - * Hide the existing toast and reject the promise returned from - * `$mdToast.show()`. - * - * @param {*=} response An argument for the rejected promise. - * - * @returns {promise} a promise that is called when the existing element is removed from the DOM - * The promise is resolved with a Boolean value == 'false'. - * - */ + * @ngdoc method + * @name $mdToast#cancel + * + * @description + * Hide the existing toast and reject the promise returned from + * `$mdToast.show()`. + * + * @param {*=} response An argument for the rejected promise. + * + * @returns {promise} a promise that is called when the existing element is removed from the DOM + * The promise is resolved with a Boolean value == 'false'. + * + */ function MdToastProvider($$interimElementProvider) { // Differentiate promise resolves: hide timeout (value == true) and hide action clicks (value == ok).