diff --git a/packages/core/src/components/loading-controller/readme.md b/packages/core/src/components/loading-controller/readme.md index 5cb50f4703..fc9f26af64 100644 --- a/packages/core/src/components/loading-controller/readme.md +++ b/packages/core/src/components/loading-controller/readme.md @@ -1,36 +1,21 @@ # ion-loading-controller -An overlay that can be used to indicate activity while blocking user -interaction. The loading indicator appears on top of the app's content, -and can be dismissed by the app to resume user interaction with -the app. It includes an optional backdrop, which can be disabled -by setting `showBackdrop: false` upon creation. +Loading controllers programmatically control the loading component. Loadings can be created and dismissed from the loading controller. View the [Loading](../../loading/Loading) documentation for a full list of options to pass upon creation. -### Creating -You can pass all of the loading options in the first argument of -the create method: `create(opts)`. The spinner name should be -passed in the `spinner` property, and any optional HTML can be passed -in the `content` property. If you do not pass a value to `spinner` -the loading indicator will use the spinner specified by the mode. To -set the spinner name across the app, set the value of `loadingSpinner` -in your app's config. To hide the spinner, set `loadingSpinner: 'hide'` -in the app's config or pass `spinner: 'hide'` in the loading -options. See the [create](#create) method below for all available options. -### Dismissing -The loading indicator can be dismissed automatically after a specific -amount of time by passing the number of milliseconds to display it in -the `duration` of the loading options. By default the loading indicator -will show even during page changes, but this can be disabled by setting -`dismissOnPageChange` to `true`. To dismiss the loading indicator after -creation, call the `dismiss()` method on the Loading instance. The -`onDidDismiss` function can be called to perform an action after the loading -indicator is dismissed. +```javascript +async function presentLoading() { + const loadingController = document.querySelector('ion-loading-controller'); + await loadingController.componentOnReady(); ->Note that after the component is dismissed, it will not be usable anymore -and another one must be created. This can be avoided by wrapping the -creation and presentation of the component in a reusable function as shown -in the `usage` section below. + const loadingElement = await loadingController.create({ + content: 'Please wait...', + spinner: 'crescent', + duration: 2000 + }); + return await loadingElement.present(); +} +``` diff --git a/packages/core/src/components/loading/loading.tsx b/packages/core/src/components/loading/loading.tsx index 9212fefeea..4277997c91 100644 --- a/packages/core/src/components/loading/loading.tsx +++ b/packages/core/src/components/loading/loading.tsx @@ -1,17 +1,8 @@ import { Component, Element, Event, EventEmitter, Listen, Method, Prop } from '@stencil/core'; -import { - Animation, - AnimationBuilder, - AnimationController, - Config, - DomController, - OverlayDismissEvent, - OverlayDismissEventDetail -} from '../../index'; +import { Animation, AnimationBuilder, AnimationController, Config, DomController, OverlayDismissEvent, OverlayDismissEventDetail } from '../../index'; import { domControllerAsync, playAnimationAsync } from '../../utils/helpers'; import { createThemedClasses, getClassMap } from '../../utils/theme'; - import iosEnterAnimation from './animations/ios.enter'; import iosLeaveAnimation from './animations/ios.leave'; import mdEnterAnimation from './animations/md.enter'; @@ -37,6 +28,67 @@ export class Loading { @Element() private el: HTMLElement; + @Prop({ connect: 'ion-animation-controller' }) animationCtrl: AnimationController; + @Prop({ context: 'config' }) config: Config; + @Prop({ context: 'dom' }) dom: DomController; + + /** + * Animation to use when the loading indicator is presented. + */ + @Prop() enterAnimation: AnimationBuilder; + + /** + * Animation to use when the loading indicator is dismissed. + */ + @Prop() leaveAnimation: AnimationBuilder; + + /** + * Optional text content to display in the loading indicator. + */ + @Prop() content: string; + + /** + * Additional classes to apply for custom CSS. If multiple classes are + * provided they should be separated by spaces. + */ + @Prop() cssClass: string; + + /** + * If true, the loading indicator will dismiss when the page changes. Defaults to `false`. + */ + @Prop() dismissOnPageChange = false; + + /** + * Number of milliseconds to wait before dismissing the loading indicator. + */ + @Prop() duration: number; + + /** + * If true, the loading indicator will be dismissed when the backdrop is clicked. Defaults to `false`. + */ + @Prop() enableBackdropDismiss = false; + + /** + * If true, a backdrop will be displayed behind the loading indicator. Defaults to `true`. + */ + @Prop() showBackdrop = true; + + /** + * The name of the spinner to display. Possible values are: `"lines"`, `"lines-sm"`, `"dots"`, + * `"bubbles"`, `"circles"`, `"crescent"`. + */ + @Prop() spinner: string; + + /** + * If true, the loading indicator will be translucent. Defaults to `false`. + */ + @Prop() translucent = false; + + /** + * If true, the loading indicator will animate. Defaults to `true`. + */ + @Prop() willAnimate = true; + /** * Emitted after the loading has loaded. */ @@ -67,59 +119,40 @@ export class Loading { */ @Event() ionLoadingDidUnload: EventEmitter; - @Prop() spinner: string; + componentDidLoad() { + if (!this.spinner) { + this.spinner = this.config.get('loadingSpinner', this.mode === 'ios' ? 'lines' : 'crescent'); + } + this.ionLoadingDidLoad.emit(); + } - @Prop({ connect: 'ion-animation-controller' }) animationCtrl: AnimationController; - @Prop({ context: 'config' }) config: Config; - @Prop({ context: 'dom' }) dom: DomController; + componentDidEnter() { + // blur the currently active element + const activeElement: any = document.activeElement; + activeElement && activeElement.blur && activeElement.blur(); + + // If there is a duration, dismiss after that amount of time + if (typeof this.duration === 'number' && this.duration > 10) { + this.durationTimeout = setTimeout(() => this.dismiss(), this.duration); + } + + this.ionLoadingDidPresent.emit(); + } + + componentDidUnload() { + this.ionLoadingDidUnload.emit(); + } + + @Listen('ionDismiss') + protected onDismiss(ev: UIEvent) { + ev.stopPropagation(); + ev.preventDefault(); + + this.dismiss(); + } /** - * Additional classes to apply for custom CSS - */ - @Prop() cssClass: string; - - /** - * Optional text content to display in the loading indicator - */ - @Prop() content: string; - - /** - * Dismiss the loading indicator if the page is changed - */ - @Prop() dismissOnPageChange = false; - - /** - * Number of milliseconds to wait before dismissing the loading indicator - */ - @Prop() duration: number; - - /** - * If true, the background will be translucent. Browser support for backdrop-filter is required for the full effect - */ - @Prop() translucent = false; - - /** - * Show the backdrop of not - */ - @Prop() showBackdrop = true; - - /** - * Animation to use when loading indicator is presented - */ - @Prop() enterAnimation: AnimationBuilder; - - /** - * Animation to use when a loading indicator is dismissed - */ - @Prop() leaveAnimation: AnimationBuilder; - - /** - * Toggles whether animation should occur or not - */ - @Prop() willAnimate = true; - - /** - * Present a loading overlay after it has been created + * Present the loading overlay after it has been created. */ @Method() present() { @@ -151,7 +184,7 @@ export class Loading { } /** - * Dismiss a loading indicator programatically + * Dismiss the loading overlay after it has been presented. */ @Method() dismiss(data?: any, role?: string) { @@ -190,36 +223,10 @@ export class Loading { }); } - componentDidLoad() { - if (!this.spinner) { - this.spinner = this.config.get('loadingSPinner', this.mode === 'ios' ? 'lines' : 'crescent'); + protected backdropClick() { + if (this.enableBackdropDismiss) { + this.dismiss(); } - this.ionLoadingDidLoad.emit(); - } - - componentDidEnter() { - // blur the currently active element - const activeElement: any = document.activeElement; - activeElement && activeElement.blur && activeElement.blur(); - - // If there is a duration, dismiss after that amount of time - if (typeof this.duration === 'number' && this.duration > 10) { - this.durationTimeout = setTimeout(() => this.dismiss(), this.duration); - } - - this.ionLoadingDidPresent.emit(); - } - - componentDidUnload() { - this.ionLoadingDidUnload.emit(); - } - - @Listen('ionDismiss') - protected onDismiss(ev: UIEvent) { - ev.stopPropagation(); - ev.preventDefault(); - - this.dismiss(); } hostData() { @@ -261,14 +268,12 @@ export class Loading { } return [ - , + }}>, diff --git a/packages/core/src/components/loading/readme.md b/packages/core/src/components/loading/readme.md index 1cb8fe193a..cee5f3aaa7 100644 --- a/packages/core/src/components/loading/readme.md +++ b/packages/core/src/components/loading/readme.md @@ -1,5 +1,33 @@ # ion-loading +An overlay that can be used to indicate activity while blocking user interaction. The loading indicator appears on top of the app's content, and can be dismissed by the app to resume user interaction with the app. It includes an optional backdrop, which can be disabled by setting `showBackdrop: false` upon creation. + +Loading indicators can be programmatically opened using a [Loading Controller](../../loading-controller/LoadingController). They can be customized by passing loading options in the first argument of the loading controller's create method. + + +### Creating + +You can pass all of the loading options in the first argument of the create method. The spinner name should be passed in the `spinner` property, and any optional HTML can be passed in the `content` property. If a value is not passed to `spinner` the loading indicator will use the spinner specified by the platform. + + +### Dismissing + +The loading indicator can be dismissed automatically after a specific amount of time by passing the number of milliseconds to display it in the `duration` of the loading options. By default the loading indicator will show even during page changes, but this can be disabled by setting `dismissOnPageChange` to `true`. To dismiss the loading indicator after creation, call the `dismiss()` method on the loading instance. The `onDidDismiss` function can be called to perform an action after the loading indicator is dismissed. + + +```javascript +async function presentLoading() { + const loadingController = document.querySelector('ion-loading-controller'); + await loadingController.componentOnReady(); + + const loadingElement = await loadingController.create({ + content: 'Please wait...', + spinner: 'crescent', + duration: 2000 + }); + return await loadingElement.present(); +} +``` @@ -11,68 +39,79 @@ string -Optional text content to display in the loading indicator +Optional text content to display in the loading indicator. #### cssClass string -Additional classes to apply for custom CSS +Additional classes to apply for custom CSS. If multiple classes are +provided they should be separated by spaces. #### dismissOnPageChange boolean -Dismiss the loading indicator if the page is changed +If true, the loading indicator will dismiss when the page changes. Defaults to `false`. #### duration number -Number of milliseconds to wait before dismissing the loading indicator +Number of milliseconds to wait before dismissing the loading indicator. + + +#### enableBackdropDismiss + +boolean + +If true, the loading indicator will be dismissed when the backdrop is clicked. Defaults to `false`. #### enterAnimation -Animation to use when loading indicator is presented +Animation to use when the loading indicator is presented. #### leaveAnimation -Animation to use when a loading indicator is dismissed +Animation to use when the loading indicator is dismissed. #### showBackdrop boolean -Show the backdrop of not +If true, a backdrop will be displayed behind the loading indicator. Defaults to `true`. #### spinner string +The name of the spinner to display. Possible values are: `"lines"`, `"lines-sm"`, `"dots"`, +`"bubbles"`, `"circles"`, `"crescent"`. + #### translucent boolean -If true, the background will be translucent. Browser support for backdrop-filter is required for the full effect +If true, the loading indicator will be translucent. Defaults to `false`. #### willAnimate boolean -Toggles whether animation should occur or not +If true, the loading indicator will animate. Defaults to `true`. ## Attributes @@ -81,68 +120,79 @@ Toggles whether animation should occur or not string -Optional text content to display in the loading indicator +Optional text content to display in the loading indicator. #### css-class string -Additional classes to apply for custom CSS +Additional classes to apply for custom CSS. If multiple classes are +provided they should be separated by spaces. #### dismiss-on-page-change boolean -Dismiss the loading indicator if the page is changed +If true, the loading indicator will dismiss when the page changes. Defaults to `false`. #### duration number -Number of milliseconds to wait before dismissing the loading indicator +Number of milliseconds to wait before dismissing the loading indicator. + + +#### enable-backdrop-dismiss + +boolean + +If true, the loading indicator will be dismissed when the backdrop is clicked. Defaults to `false`. #### enter-animation -Animation to use when loading indicator is presented +Animation to use when the loading indicator is presented. #### leave-animation -Animation to use when a loading indicator is dismissed +Animation to use when the loading indicator is dismissed. #### show-backdrop boolean -Show the backdrop of not +If true, a backdrop will be displayed behind the loading indicator. Defaults to `true`. #### spinner string +The name of the spinner to display. Possible values are: `"lines"`, `"lines-sm"`, `"dots"`, +`"bubbles"`, `"circles"`, `"crescent"`. + #### translucent boolean -If true, the background will be translucent. Browser support for backdrop-filter is required for the full effect +If true, the loading indicator will be translucent. Defaults to `false`. #### will-animate boolean -Toggles whether animation should occur or not +If true, the loading indicator will animate. Defaults to `true`. ## Events @@ -181,12 +231,12 @@ Emitted before the loading has presented. #### dismiss() -Dismiss a loading indicator programatically +Dismiss the loading overlay after it has been presented. #### present() -Present a loading overlay after it has been created +Present the loading overlay after it has been created. diff --git a/packages/core/src/components/loading/test/basic/e2e.js b/packages/core/src/components/loading/test/basic/e2e.js index 1ef562bdb9..dd4c2126d9 100644 --- a/packages/core/src/components/loading/test/basic/e2e.js +++ b/packages/core/src/components/loading/test/basic/e2e.js @@ -27,5 +27,10 @@ platforms.forEach(platform => { const page = new E2ETestPage(driver, platform); return page.present('basic'); }); + + register('should open default spinner', driver => { + const page = new E2ETestPage(driver, platform); + return page.present('default'); + }); }); }); diff --git a/packages/core/src/components/loading/test/basic/index.html b/packages/core/src/components/loading/test/basic/index.html index 0d1eed13bf..b79194a908 100644 --- a/packages/core/src/components/loading/test/basic/index.html +++ b/packages/core/src/components/loading/test/basic/index.html @@ -19,10 +19,12 @@ Show Loading + Show Default Loading Show Loading with long content - Show Loading with no spinner - Show Loading with translucent - Show Loading with cssClass + Show Loading with no spinner + Show Loading with translucent + Show Loading with cssClass + Show Backdrop Click Loading @@ -77,9 +79,10 @@