From 2e5a6d6120c6c4c2283bb9489467eecc8e68e5fe Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Wed, 4 Apr 2018 13:01:54 -0400 Subject: [PATCH] docs(select): update select readme and add usage docs --- core/src/components/select/readme.md | 69 +--- .../components/select/test/preview/index.html | 346 +++++------------- core/src/components/select/usage/angular.md | 135 +++++++ .../src/components/select/usage/javascript.md | 132 +++++++ 4 files changed, 381 insertions(+), 301 deletions(-) create mode 100644 core/src/components/select/usage/angular.md create mode 100644 core/src/components/select/usage/javascript.md diff --git a/core/src/components/select/readme.md b/core/src/components/select/readme.md index 3bb2c26090..aa855d8d47 100644 --- a/core/src/components/select/readme.md +++ b/core/src/components/select/readme.md @@ -1,80 +1,39 @@ # ion-select -The `` element is similar to a native `` element. When a user taps the select, a dialog appears with all of the options in a large, easy to select list. -It should be used with child `ion-select-option` elements. If the child option is not given a `value` attribute then it will use its text as the value. +A select should be used with child `` elements. If the child option is not given a `value` attribute then its text will be used as the value. + +If `value` is set on the ``, the selected option will be chosen based on that value. Otherwise, the `selected` attribute can be used on the ``. -If `value` is set on the `ion-select`, the selected option will be based on that value. Otherwise, the `selected` attribute can be used on the `ion-select-option` elements. ## Interfaces -By default, the `ion-select` uses the [AlertController API](../../alert/AlertController) to open up the overlay of options in an alert. The interface can be changed to use the [ActionSheetController API](../../action-sheet/ActionSheetController) or [PopoverController API](../../popover/PopoverController) by passing `action-sheet` or `popover`, respectively, to the `interface` property. Read on to the other sections for the limitations of the different interfaces. +By default, select uses the [AlertController API](../../alert/AlertController) to open up the overlay of options in an alert. The interface can be changed to use the [ActionSheetController API](../../action-sheet/ActionSheetController) or [PopoverController API](../../popover/PopoverController) by passing `action-sheet` or `popover`, respectively, to the `interface` property. Read on to the other sections for the limitations of the different interfaces. -## Single Value: Radio Buttons -The standard `ion-select` component allows the user to select only one option. When selecting only one option the alert interface presents users with a radio button styled list of options. The action sheet interface can only be used with a single value select. The `ion-select` component's value receives the value of the selected option's value. +## Single Selection -```html - - Gender - - Female - Male - - -``` +By default, the select allows the user to select only one option. The alert interface presents users with a radio button styled list of options. The action sheet interface can only be used with a single value select. The select component's value receives the value of the selected option's value. -### Multiple Value: Checkboxes -By adding the `multiple="true"` attribute to `ion-select`, users are able to select multiple options. When multiple options can be selected, the alert overlay presents users with a checkbox styled list of options. The `ion-select` component's value receives an array of all the selected option values. In the example below, because each option is not given a `value`, it will use the option's text as the value. +### Multiple Selection -Note: the `action-sheet` and `popover` interfaces will not work with a multiple-value select. +By adding the `multiple` attribute to select, users are able to select multiple options. When multiple options can be selected, the alert overlay presents users with a checkbox styled list of options. The select component's value receives an array of all of the selected option values. + +Note: the `action-sheet` and `popover` interfaces will not work with multiple selection. -```html - - Toppings - - Bacon - Black Olives - Extra Cheese - Mushrooms - Pepperoni - Sausage - - -``` ## Select Buttons -By default, the two buttons read `Cancel` and `OK`. Each button's text can be customized using the `cancelText` and `okText` attributes: - -```html - - ... - -``` +By default, the alert has two buttons: `Cancel` and `OK`. Each button's text can be customized using the `cancelText` and `okText` properties. The `action-sheet` and `popover` interfaces do not have an `OK` button, clicking on any of the options will automatically close the overlay and select that value. The `popover` interface does not have a `Cancel` button, clicking on the backdrop will close the overlay. + ## Interface Options -Since `ion-select` uses the `Alert`, `Action Sheet` and `Popover` interfaces, options can be passed to these components through the `interfaceOptions` property. This can be used to pass a custom title, subTitle, css class, and more. See the [AlertController API docs](../../alert/AlertController/#create), [ActionSheetController API docs](../../action-sheet/ActionSheetController/#create), and [PopoverController API docs](../../popover/PopoverController/#create) for the properties that each interface accepts. - -For example, to change the `title` and `subTitle` of the overlay, pass it into `interfaceOptions`. - -```html - - ... - -``` - -```javascript -var customSelect = document.getElementById('customSelect'); -customSelect.interfaceOptions = { - header: 'Pizza Toppings', - subHeader: 'Select your toppings' -}; -``` +Since select uses the alert, action sheet and popover interfaces, options can be passed to these components through the `interfaceOptions` property. This can be used to pass a custom header, subheader, css class, and more. See the [AlertController API docs](../../alert/AlertController/#create), [ActionSheetController API docs](../../action-sheet/ActionSheetController/#create), and [PopoverController API docs](../../popover/PopoverController/#create) for the properties that each interface accepts. diff --git a/core/src/components/select/test/preview/index.html b/core/src/components/select/test/preview/index.html index c0219cfe8b..d6dcbb7084 100644 --- a/core/src/components/select/test/preview/index.html +++ b/core/src/components/select/test/preview/index.html @@ -1,256 +1,121 @@ + Select + - - - Select - - + + + Select + + - - - Single Value Select + + + Single Selection - - Gender - - Female - Male - - + + Gender + + Female + Male + + - - Hair Color - - Brown - Blonde - Black - Red - - + + Hair Color + + Brown + Blonde + Black + Red + + - - Skittles - - Red - Purple - Yellow - Orange - Green - - + - + + Multiple Selection - - Select - Custom Interface Options + + Toppings + + Bacon + Black Olives + Extra Cheese + Green Peppers + Mushrooms + Onions + Pepperoni + Pineapple + Sausage + Spinach + + - - Alert - - Bacon - Black Olives - Extra Cheese - Green Peppers - Mushrooms - Onions - Pepperoni - Pineapple - Sausage - Spinach - - + + Pets + + Bird + Cat + Dog + Honey Badger + + + - - Popover - - Brown - Blonde - Black - Red - - + + Interface Options - - Action Sheet - - Red - Purple - Yellow - Orange - Green - - + + Alert + + Bacon + Black Olives + Extra Cheese + Green Peppers + Mushrooms + Onions + Pepperoni + Pineapple + Sausage + Spinach + + - + + Popover + + Brown + Blonde + Black + Red + + - - Popover Interface Select + + Action Sheet + + Red + Purple + Yellow + Orange + Green + + - - Gender - - Female - Male - - + - - Gaming - - NES - Nintendo64 - PlayStation - Sega Genesis - Sega Saturn - SNES - - - - - Date - - January - February - March - April - May - June - July - August - September - October - November - December - - - 1989 - 1990 - 1991 - 1992 - 1993 - 1994 - 1995 - 1996 - 1997 - 1998 - 1999 - - - - - - - - Action Sheet Interface Select - - - Mute Notifications - - For 15 Minutes - For 1 Hour - For 24 Hours - Until I turn it back on - - - - - Rating - - 1 Star - 2 Stars - 3 Stars - 4 Stars - 5 Stars - - - - - - - Multiple Value Select - - - Toppings - - Bacon - Black Olives - Extra Cheese - Green Peppers - Mushrooms - Onions - Pepperoni - Pineapple - Sausage - Spinach - - - - - Pets - - Bird - Cat - Dog - Honey Badger - - - - - Disabled - - Selected Text - - - - - Stacked - - Default - Other - N/A - - - - - Floating - - Default - Other - N/A - - - - - Floating - - Default - Other - N/A - - - - -
- - Toggle Disabled - -
- - + + - - - diff --git a/core/src/components/select/usage/angular.md b/core/src/components/select/usage/angular.md new file mode 100644 index 0000000000..214fe18b61 --- /dev/null +++ b/core/src/components/select/usage/angular.md @@ -0,0 +1,135 @@ +## Single Selection + +```html + + Single Selection + + + Gender + + Female + Male + + + + + Hair Color + + Brown + Blonde + Black + Red + + + + +``` + +## Multiple Selection + +```html + + Multiple Selection + + + Toppings + + Bacon + Black Olives + Extra Cheese + Green Peppers + Mushrooms + Onions + Pepperoni + Pineapple + Sausage + Spinach + + + + + Pets + + Bird + Cat + Dog + Honey Badger + + + +``` + +## Interface Options + +```html + + Interface Options + + + Alert + + Bacon + Black Olives + Extra Cheese + Green Peppers + Mushrooms + Onions + Pepperoni + Pineapple + Sausage + Spinach + + + + + Popover + + Brown + Blonde + Black + Red + + + + + Action Sheet + + Red + Purple + Yellow + Orange + Green + + + + +``` + +```javascript +import { Component } from '@angular/core'; + +@Component({ + selector: 'select-example', + templateUrl: 'select-example.html', + styleUrls: ['./select-example.css'], +}) +export class SelectExample { + customAlertOptions: any = { + header: 'Pizza Toppings', + subHeader: 'Select your toppings', + message: '$1.00 per topping', + translucent: true + }; + + customPopoverOptions: any = { + header: 'Hair Color', + subHeader: 'Select your hair color', + message: 'Only select your dominant hair color' + }; + + customActionSheetOptions: any = { + header: 'Colors', + subHeader: 'Select your favorite color' + }; +} +``` \ No newline at end of file diff --git a/core/src/components/select/usage/javascript.md b/core/src/components/select/usage/javascript.md new file mode 100644 index 0000000000..f429922df3 --- /dev/null +++ b/core/src/components/select/usage/javascript.md @@ -0,0 +1,132 @@ +## Single Selection + +```html + + Single Selection + + + Gender + + Female + Male + + + + + Hair Color + + Brown + Blonde + Black + Red + + + + +``` + +## Multiple Selection + +```html + + Multiple Selection + + + Toppings + + Bacon + Black Olives + Extra Cheese + Green Peppers + Mushrooms + Onions + Pepperoni + Pineapple + Sausage + Spinach + + + + + Pets + + Bird + Cat + Dog + Honey Badger + + + +``` + +## Interface Options + +```html + + Interface Options + + + Alert + + Bacon + Black Olives + Extra Cheese + Green Peppers + Mushrooms + Onions + Pepperoni + Pineapple + Sausage + Spinach + + + + + Popover + + Brown + Blonde + Black + Red + + + + + Action Sheet + + Red + Purple + Yellow + Orange + Green + + + + +``` + +```javascript +var customAlertSelect = document.getElementById('customAlertSelect'); +var customAlertOptions = { + header: 'Pizza Toppings', + subHeader: 'Select your toppings', + message: '$1.00 per topping', + translucent: true +}; +customAlertSelect.interfaceOptions = customAlertOptions; + +var customPopoverSelect = document.getElementById('customPopoverSelect'); +var customPopoverOptions = { + header: 'Hair Color', + subHeader: 'Select your hair color', + message: 'Only select your dominant hair color' +}; +customPopoverSelect.interfaceOptions = customPopoverOptions; + +var customActionSheetSelect = document.getElementById('customActionSheetSelect'); +var customActionSheetOptions = { + header: 'Colors', + subHeader: 'Select your favorite color' +}; +customActionSheetSelect.interfaceOptions = customActionSheetOptions; +``` \ No newline at end of file