From b28fab587cc6ffce7b576cb1b4514df32ff0e922 Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Mon, 19 Feb 2018 18:23:31 -0500 Subject: [PATCH] docs(action-sheet): copy editing, add usage and fix style --- .../action-sheet-controller.tsx | 43 +++++++----- .../action-sheet-controller/readme.md | 65 +++++++++++++------ .../src/components/action-sheet/readme.md | 10 +-- 3 files changed, 71 insertions(+), 47 deletions(-) diff --git a/packages/core/src/components/action-sheet-controller/action-sheet-controller.tsx b/packages/core/src/components/action-sheet-controller/action-sheet-controller.tsx index 57ce36caae..6ebbfed3c5 100644 --- a/packages/core/src/components/action-sheet-controller/action-sheet-controller.tsx +++ b/packages/core/src/components/action-sheet-controller/action-sheet-controller.tsx @@ -9,6 +9,26 @@ const actionSheets = new Map(); }) export class ActionSheetController implements OverlayController { + @Listen('body:ionActionSheetWillPresent') + protected actionSheetWillPresent(ev: ActionSheetEvent) { + actionSheets.set(ev.target.actionSheetId, ev.target); + } + + + @Listen('body:ionActionSheetWillDismiss, body:ionActionSheetDidUnload') + protected actionSheetWillDismiss(ev: ActionSheetEvent) { + actionSheets.delete(ev.target.actionSheetId); + } + + + @Listen('body:keyup.escape') + protected escapeKeyUp() { + removeLastActionSheet(); + } + + /* + * Create an action sheet overlay with action sheet options. + */ @Method() create(opts?: ActionSheetOptions): Promise { // create ionic's wrapping ion-actionSheet component @@ -28,6 +48,9 @@ export class ActionSheetController implements OverlayController { return actionSheetElement.componentOnReady(); } + /* + * Dismiss the open action sheet overlay. + */ @Method() dismiss(data?: any, role?: any, actionSheetId = -1) { actionSheetId = actionSheetId >= 0 ? actionSheetId : getHighestId(); @@ -38,27 +61,13 @@ export class ActionSheetController implements OverlayController { return actionSheet.dismiss(data, role); } + /* + * Get the most recently opened action sheet overlay. + */ @Method() getTop() { return actionSheets.get(getHighestId()); } - - @Listen('body:ionActionSheetWillPresent') - protected actionSheetWillPresent(ev: ActionSheetEvent) { - actionSheets.set(ev.target.actionSheetId, ev.target); - } - - - @Listen('body:ionActionSheetWillDismiss, body:ionActionSheetDidUnload') - protected actionSheetWillDismiss(ev: ActionSheetEvent) { - actionSheets.delete(ev.target.actionSheetId); - } - - - @Listen('body:keyup.escape') - protected escapeKeyUp() { - removeLastActionSheet(); - } } function getHighestId() { diff --git a/packages/core/src/components/action-sheet-controller/readme.md b/packages/core/src/components/action-sheet-controller/readme.md index 498445413f..a31a78d45f 100644 --- a/packages/core/src/components/action-sheet-controller/readme.md +++ b/packages/core/src/components/action-sheet-controller/readme.md @@ -1,28 +1,51 @@ # ion-action-sheet-controller - An Action Sheet is a dialog that lets the user choose from a set of - options. It appears on top of the app's content, and must be manually - dismissed by the user before they can resume interaction with the app. - Dangerous (destructive) options are made obvious in `ios` mode. There are easy - ways to cancel the action sheet, such as tapping the backdrop or - hitting the escape key on desktop. +Action Sheet controllers programmatically control the action sheet component. Action Sheets can be created and dismissed from the action sheet controller. View the [Action Sheet](../../action-sheet/ActionSheet) documentation for a full list of options to pass upon creation. - An action sheet is created from an array of `buttons`, with each button - including properties for its `text`, and optionally a `handler` and `role`. - If a handler returns `false` then the action sheet will not be dismissed. An - action sheet can also optionally have a `title`, `subTitle` and an `icon`. +```javascript +async function presentBasic() { + const actionSheetController = document.querySelector('ion-action-sheet-controller'); + await actionSheetController.componentOnReady(); - A button's `role` property can either be `destructive` or `cancel`. Buttons - without a role property will have the default look for the platform. Buttons - with the `cancel` role will always load as the bottom button, no matter where - they are in the array. All other buttons will be displayed in the order they - have been added to the `buttons` array. Note: We recommend that `destructive` - buttons are always the first button in the array, making them the top button. - Additionally, if the action sheet is dismissed by tapping the backdrop, then - it will call the handler from the button with the cancel role. - - You can pass all of the action sheet's options in the first argument of - the create method: `ActionSheet.create(opts)`. + const actionSheetElement = await actionSheetController.create({ + title: "Albums", + buttons: [{ + text: 'Delete', + role: 'destructive', + icon: 'trash', + handler: () => { + console.log('Delete clicked'); + } + }, { + text: 'Share', + icon: 'share', + handler: () => { + console.log('Share clicked'); + } + }, { + text: 'Play (open modal)', + icon: 'arrow-dropright-circle', + handler: () => { + console.log('Play clicked'); + } + }, { + text: 'Favorite', + icon: 'heart', + handler: () => { + console.log('Favorite clicked'); + } + }, { + text: 'Cancel', + icon: 'close', + role: 'cancel', + handler: () => { + console.log('Cancel clicked'); + } + }] + }); + await actionSheetElement.present(); +} +``` diff --git a/packages/core/src/components/action-sheet/readme.md b/packages/core/src/components/action-sheet/readme.md index b3ed4ce673..07107d7636 100644 --- a/packages/core/src/components/action-sheet/readme.md +++ b/packages/core/src/components/action-sheet/readme.md @@ -2,18 +2,10 @@ An Action Sheet is a dialog that displays a set of options. It appears on top of the app's content, and must be manually dismissed by the user before they can resume interaction with the app. Destructive options are made obvious in `ios` mode. There are multiple ways to dismiss the action sheet, including tapping the backdrop or hitting the escape key on desktop. -An action sheet is created from an array of `buttons`, with each button including properties for its `text`, and optionally a `handler` and `role`. If a handler returns `false` then the action sheet will not be dismissed. An action sheet can also optionally have a `title`, `subTitle` and an `icon`. +An action sheet can be created by the [Action Sheet Controller](../../action-sheet-controller/ActionSheetController) from an array of `buttons`, with each button including properties for its `text`, and optionally a `handler` and `role`. If a handler returns `false` then the action sheet will not be dismissed. An action sheet can also optionally have a `title`, `subTitle` and an `icon`. A button's `role` property can either be `destructive` or `cancel`. Buttons without a role property will have the default look for the platform. Buttons with the `cancel` role will always load as the bottom button, no matter where they are in the array. All other buttons will be displayed in the order they have been added to the `buttons` array. Note: We recommend that `destructive` buttons are always the first button in the array, making them the top button. Additionally, if the action sheet is dismissed by tapping the backdrop, then it will fire the handler from the button with the cancel role. -You can pass all of the action sheet's options in the first argument of the create method. - -```html - - Present Action Sheet - -``` - ```javascript async function presentBasic() { const actionSheetController = document.querySelector('ion-action-sheet-controller');