diff --git a/packages/core/src/components/refresher-content/readme.md b/packages/core/src/components/refresher-content/readme.md index 073ad20d85..1260de5d04 100644 --- a/packages/core/src/components/refresher-content/readme.md +++ b/packages/core/src/components/refresher-content/readme.md @@ -1,6 +1,30 @@ # ion-refresher-content +By default, Ionic provides the pulling icon and refreshing spinner that looks +best for the platform the user is on. However, you can change the default icon +and spinner, along with adding text for each state by adding properties to the +child `ion-refresher-content` component. +```html + + + + + + + +``` + +The `ion-refresher` component holds the refresh logic. It requires a child +component in order to display the content. Ionic uses `ion-refresher-content` by +default. This component displays the refresher and changes the look depending on +the refresher's state. Separating these components allows developers to create +their own refresher content components. You could replace our default content +with custom SVG or CSS animations. @@ -11,21 +35,29 @@ string +A static icon to display when you begin to pull down + #### pullingText string +The text you want to display when you begin to pull down + #### refreshingSpinner string +An animated SVG spinner that shows when refreshing begins + #### refreshingText string +The text you want to display when performing a refresh + ## Attributes @@ -33,21 +65,29 @@ string string +A static icon to display when you begin to pull down + #### pullingText string +The text you want to display when you begin to pull down + #### refreshingSpinner string +An animated SVG spinner that shows when refreshing begins + #### refreshingText string +The text you want to display when performing a refresh + ---------------------------------------------- diff --git a/packages/core/src/components/refresher-content/refresher-content.tsx b/packages/core/src/components/refresher-content/refresher-content.tsx index df281549e8..451eca27e4 100644 --- a/packages/core/src/components/refresher-content/refresher-content.tsx +++ b/packages/core/src/components/refresher-content/refresher-content.tsx @@ -1,9 +1,6 @@ import { Component, Prop } from '@stencil/core'; import { Config } from '../../index'; -/** - * @hidden - */ @Component({ tag: 'ion-refresher-content' }) @@ -12,22 +9,22 @@ export class RefresherContent { @Prop({ context: 'config' }) config: Config; /** - * @input {string} a static icon to display when you begin to pull down + * A static icon to display when you begin to pull down */ @Prop({mutable: true}) pullingIcon: string; /** - * @input {string} the text you want to display when you begin to pull down + * The text you want to display when you begin to pull down */ @Prop() pullingText: string; /** - * @input {string} An animated SVG spinner that shows when refreshing begins + * An animated SVG spinner that shows when refreshing begins */ @Prop({mutable: true}) refreshingSpinner: string; /** - * @input {string} the text you want to display when performing a refresh + * The text you want to display when performing a refresh */ @Prop() refreshingText: string; diff --git a/packages/core/src/components/refresher/readme.md b/packages/core/src/components/refresher/readme.md index 55d8fb50b8..ed6fa40074 100644 --- a/packages/core/src/components/refresher/readme.md +++ b/packages/core/src/components/refresher/readme.md @@ -1,4 +1,12 @@ # ion-refresher-content +The Refresher provides pull-to-refresh functionality on a content component. +Place the `ion-refresher` as the first child of your `ion-content` element. + +Pages can then listen to the refresher's various output events. The `refresh` +output event is fired when the user has pulled down far enough to kick off the +refreshing process. Once the async operation has completed and the refreshing +should end, call `complete()`. + @@ -11,26 +19,39 @@ string +Time it takes to close the refresher. Default is `280ms`. + #### enabled boolean +If the refresher is enabled or not. This should be used in place of an `ngIf`. Default is `true`. + #### pullDelta number +The maximum distance of the pull until the refresher +will automatically go into the `refreshing` state. By default, the pull +maximum will be the result of `pullMin + 60`. + #### pullMin number +The min distance the user must pull down until the +refresher can go into the `refreshing` state. Default is `60`. + #### snapbackDuration string +Time it takes the refresher to to snap back to the `refreshing` state. Default is `280ms`. + ## Attributes @@ -38,37 +59,59 @@ string string +Time it takes to close the refresher. Default is `280ms`. + #### enabled boolean +If the refresher is enabled or not. This should be used in place of an `ngIf`. Default is `true`. + #### pullDelta number +The maximum distance of the pull until the refresher +will automatically go into the `refreshing` state. By default, the pull +maximum will be the result of `pullMin + 60`. + #### pullMin number +The min distance the user must pull down until the +refresher can go into the `refreshing` state. Default is `60`. + #### snapbackDuration string +Time it takes the refresher to to snap back to the `refreshing` state. Default is `280ms`. + ## Events #### ionPull +Emitted while the user is pulling down the content and exposing the refresher. + #### ionRefresh +Emitted when the user lets go and has pulled down +far enough, which would be farther than the `pullMin`, then your refresh hander if +fired and the state is updated to `refreshing`. From within your refresh handler, +you must call the `complete()` method when your async operation has completed. + #### ionStart +Emitted when the user begins to start pulling down. + ## Methods diff --git a/packages/core/src/components/refresher/refresher.tsx b/packages/core/src/components/refresher/refresher.tsx index 77be55d90b..372041ca51 100644 --- a/packages/core/src/components/refresher/refresher.tsx +++ b/packages/core/src/components/refresher/refresher.tsx @@ -12,86 +12,6 @@ const enum RefresherState { _BUSY_ = Refreshing | Cancelling | Completing, } -/** - * @name Refresher - * @description - * The Refresher provides pull-to-refresh functionality on a content component. - * Place the `ion-refresher` as the first child of your `ion-content` element. - * - * Pages can then listen to the refresher's various output events. The - * `refresh` output event is fired when the user has pulled down far - * enough to kick off the refreshing process. Once the async operation - * has completed and the refreshing should end, call `complete()`. - * - * Note: Do not wrap the `ion-refresher` in a `*ngIf`. It will not render - * properly this way. Please use the `enabled` property instead to - * display or hide the refresher. - * - * @usage - * ```html - * - * - * - * - * - * - * - * ``` - * - * ```ts - * @Component({...}) - * export class NewsFeedPage { - * - * doRefresh(refresher) { - * console.log('Begin async operation', refresher); - * - * setTimeout(() => { - * console.log('Async operation has ended'); - * refresher.complete(); - * }, 2000); - * } - * - * } - * ``` - * - * - * ## Refresher Content - * - * By default, Ionic provides the pulling icon and refreshing spinner that - * looks best for the platform the user is on. However, you can change the - * default icon and spinner, along with adding text for each state by - * adding properties to the child `ion-refresher-content` component. - * - * ```html - * - * - * - * - * - * - * - * - * ``` - * - * - * ## Further Customizing Refresher Content - * - * The `ion-refresher` component holds the refresh logic. - * It requires a child component in order to display the content. - * Ionic uses `ion-refresher-content` by default. This component - * displays the refresher and changes the look depending - * on the refresher's state. Separating these components - * allows developers to create their own refresher content - * components. You could replace our default content with - * custom SVG or CSS animations. - * - * @demo /docs/demos/src/refresher/ - * - */ @Component({ tag: 'ion-refresher', styleUrl: 'refresher.scss' @@ -123,13 +43,13 @@ export class Refresher { @Element() el: HTMLElement; /** - * @input {number} The min distance the user must pull down until the + * The min distance the user must pull down until the * refresher can go into the `refreshing` state. Default is `60`. */ @Prop() pullMin = 60; /** - * @input {number} The maximum distance of the pull until the refresher + * The maximum distance of the pull until the refresher * will automatically go into the `refreshing` state. By default, the pull * maximum will be the result of `pullMin + 60`. */ @@ -137,22 +57,22 @@ export class Refresher { // TODO: NEVER USED /** - * @input {number} Time it takes to close the refresher. Default is `280ms`. + * Time it takes to close the refresher. Default is `280ms`. */ @Prop() closeDuration = '280ms'; /** - * @input {string} Time it takes the refresher to to snap back to the `refreshing` state. Default is `280ms`. + * Time it takes the refresher to to snap back to the `refreshing` state. Default is `280ms`. */ @Prop() snapbackDuration = '280ms'; /** - * @input {boolean} If the refresher is enabled or not. This should be used in place of an `ngIf`. Default is `true`. + * If the refresher is enabled or not. This should be used in place of an `ngIf`. Default is `true`. */ @Prop() enabled = false; /** - * @output {event} Emitted when the user lets go and has pulled down + * Emitted when the user lets go and has pulled down * far enough, which would be farther than the `pullMin`, then your refresh hander if * fired and the state is updated to `refreshing`. From within your refresh handler, * you must call the `complete()` method when your async operation has completed. @@ -160,12 +80,12 @@ export class Refresher { @Event() ionRefresh: EventEmitter; /** - * @output {event} Emitted while the user is pulling down the content and exposing the refresher. + * Emitted while the user is pulling down the content and exposing the refresher. */ @Event() ionPull: EventEmitter; /** - * @output {event} Emitted when the user begins to start pulling down. + * Emitted when the user begins to start pulling down. */ @Event() ionStart: EventEmitter;