javascript/ionic-framework
1
0
Fork 0
mirror of https://github.com/ionic-team/ionic-framework.git synced 2025-08-22 05:21:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(select): update API docs to include the interface property

Browse Source 
Exposed some private properties to the docs. Changed the interface
errors to warnings.

closes driftyco/ionic-site#568
This commit is contained in:
Brandy Carney
2016-04-22 17:09:51 -04:00
parent a00fe76000
commit 9d4ded1d31
1 changed files with 43 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
ionic/components/select/select.ts
View File

@ -22,18 +22,25 @@ const SELECT_VALUE_ACCESSOR = new Provider(
* dialog will appear with all of the options in a large, easy to select list * dialog will appear with all of the options in a large, easy to select list
* for users. * for users.
* *
* Under-the-hood the `ion-select` actually uses the * The select component takes child `ion-option` components. If `ion-option` is not
* {@link ../../alert/Alert Alert API} to open up the overlay of options * given a `value` attribute then it will use its text as the value.
* which the user is presented with. Select can take numerous child *
* `ion-option` components. If `ion-option` is not given a `value` attribute * ### Interfaces
* then it will use its text as the value. *
* By default, the `ion-select` uses the {@link ../../alert/Alert Alert API} to
* open up the overlay of options in an alert. The interface can be changed to use the
* {@link ../../action-sheet/ActionSheet ActionSheet API} by passing `action-sheet` to
* the `interface` property. Read the other sections for the limitations of the
* action sheet interface.
* *
* ### Single Value: Radio Buttons * ### Single Value: Radio Buttons
* *
* The standard `ion-select` component allows the user to select only one * The standard `ion-select` component allows the user to select only one
* option. When selecting only one option the alert overlay presents users with * option. When selecting only one option the alert interface presents users with
* a radio button styled list of options. The `ion-select` component's value * a radio button styled list of options. The action sheet interface can only be
* receives the value of the selected option's value. * used with a single value select. If the number of options exceed 6, it will
* use the `alert` interface even if `action-sheet` is passed. The `ion-select`
* component's value receives the value of the selected option's value.
* *
* ```html * ```html
* <ion-item> * <ion-item>
@ -54,6 +61,8 @@ const SELECT_VALUE_ACCESSOR = new Provider(
* selected option values. In the example below, because each option is not given * selected option values. In the example below, because each option is not given
* a `value`, then it'll use its text as the value instead. * a `value`, then it'll use its text as the value instead.
* *
* Note: the action sheet interface will not work with a multi-value select.
*
* ```html * ```html
* <ion-item> * <ion-item>
* <ion-label>Toppings</ion-label> * <ion-label>Toppings</ion-label>
@ -68,8 +77,8 @@ const SELECT_VALUE_ACCESSOR = new Provider(
* </ion-item> * </ion-item>
* ``` * ```
* *
* ### Alert Buttons * ### Select Buttons
* By default, the two buttons read `Cancel` and `OK`. The each button's text * By default, the two buttons read `Cancel` and `OK`. Each button's text
* can be customized using the `cancelText` and `okText` attributes: * can be customized using the `cancelText` and `okText` attributes:
* *
* ```html * ```html
@ -78,12 +87,16 @@ const SELECT_VALUE_ACCESSOR = new Provider(
* </ion-select> * </ion-select>
* ``` * ```
* *
* The action sheet interface does not have an `OK` button, clicking
* on any of the options will automatically close the overlay and select
* that value.
*
* ### Alert Options * ### Alert Options
* *
* Remember how `ion-select` is really just a wrapper to `Alert`? By using * Since `ion-select` is a wrapper to `Alert`, by default, it can be
* the `alertOptions` property you can pass custom options to the alert * passed options in the `alertOptions` property. This can be used to
* overlay. This would be useful if there is a custom alert title, * pass a custom alert title, subtitle or message. See the {@link ../../alert/Alert Alert API docs}
* subtitle or message. {@link ../../alert/Alert Alert API} * for more properties.
* *
* ```html * ```html
* <ion-select [alertOptions]="alertOptions"> * <ion-select [alertOptions]="alertOptions">
@ -137,20 +150,18 @@ export class Select {
id: string; id: string;
/** /**
* @private * @input {string} The text to display on the cancel button. Default: `Cancel`.
* @input {string} The text of the cancel button. Defatuls to `Cancel`
*/ */
@Input() cancelText: string = 'Cancel'; @Input() cancelText: string = 'Cancel';
/** /**
* @private * @input {string} The text to display on the ok button. Default: `OK`.
* @input {string} The text of the ok button. Defatuls to `OK`
*/ */
@Input() okText: string = 'OK'; @Input() okText: string = 'OK';
/** /**
* @private * @input {any} Any addition options that the alert interface can take.
* @input {any} Any addition options that an alert can take. Title, Subtitle, etc. * See the [Alert API docs](../../alert/Alert) for the create options.
*/ */
@Input() alertOptions: any = {}; @Input() alertOptions: any = {};
@ -160,17 +171,17 @@ export class Select {
@Input() checked: any = false; @Input() checked: any = false;
/** /**
* @private * @input {string} The interface the select should use: `action-sheet` or `alert`. Default: `alert`.
*/ */
@Input() interface: string = ''; @Input() interface: string = '';
/** /**
* @output {any} Any expression you want to evaluate when the selection has changed * @output {any} Any expression you want to evaluate when the selection has changed.
*/ */
@Output() change: EventEmitter<any> = new EventEmitter(); @Output() change: EventEmitter<any> = new EventEmitter();
/** /**
* @output {any} Any expression you want to evaluate when the selection was cancelled * @output {any} Any expression you want to evaluate when the selection was cancelled.
*/ */
@Output() cancel: EventEmitter<any> = new EventEmitter(); @Output() cancel: EventEmitter<any> = new EventEmitter();
@ -239,14 +250,17 @@ export class Select {
let options = this._options.toArray(); let options = this._options.toArray();
if (this.interface === 'action-sheet' && options.length > 6) { if (this.interface === 'action-sheet' && options.length > 6) {
this.interface = null; console.warn('Interface cannot be "action-sheet" with more than 6 options. Using the "alert" interface.');
this.interface = 'alert';
}
if (this.interface === 'action-sheet' && this._multi) {
console.warn('Interface cannot be "action-sheet" with a multi-value select. Using the "alert" interface.');
this.interface = 'alert';
} }
let overlay; let overlay;
if (this.interface === 'action-sheet') { if (this.interface === 'action-sheet') {
if (this._multi) {
throw new Error('action-sheet interface cannot use multivalue selector');
}
alertOptions.buttons = alertOptions.buttons.concat(options.map(input => { alertOptions.buttons = alertOptions.buttons.concat(options.map(input => {
return { return {
@ -309,7 +323,7 @@ export class Select {
/** /**
* @input {boolean} Whether or not the select component can accept multipl selections * @input {boolean} Whether or not the select component can accept multiple values. Default: `false`.
*/ */
@Input() @Input()
get multiple(): any { get multiple(): any {
@ -367,7 +381,7 @@ export class Select {
} }
/** /**
* @input {boolean} Whether or not the select component is disabled or not * @input {boolean} Whether or not the select component is disabled. Default `false`.
*/ */
@Input() @Input()
get disabled() { get disabled() {