docs(item): update item documentation and add usage

This commit is contained in:
Brandy Carney
2018-04-18 11:40:51 -06:00
parent 2aa2e6f3ca
commit 20a8eec992
5 changed files with 566 additions and 23 deletions

View File

@ -444,7 +444,7 @@ $input-highlight-color-valid: #32db64;
### Markup Changed ### Markup Changed
Item should now be written as an `<ion-item>` element. Ionic will determine when to render an anchor tag based on the presence of an `href` attribute, and a button tag based on the presence of an `onclick` or `tappable` attribute. Otherwise, it will render a div. Item should now be written as an `<ion-item>` element. Ionic will determine when to render an anchor tag based on the presence of an `href` attribute, and a button tag based on the presence of an `onclick` or `button` attribute. Otherwise, it will render a div.
**Old Usage Example:** **Old Usage Example:**
@ -466,15 +466,21 @@ Item should now be written as an `<ion-item>` element. Ionic will determine when
```html ```html
<ion-item> <ion-item>
<ion-label>
Default Item Default Item
</ion-label>
</ion-item> </ion-item>
<ion-item tappable (click)="doSomething()"> <ion-item button (click)="doSomething()">
<ion-label>
Button Item Button Item
</ion-label>
</ion-item> </ion-item>
<ion-item href="#"> <ion-item href="#">
<ion-label>
Anchor Item Anchor Item
</ion-label>
</ion-item> </ion-item>
``` ```
@ -484,7 +490,9 @@ Previously an `ion-label` would automatically get added to an `ion-item` if one
```html ```html
<ion-item> <ion-item>
<ion-label>Item Label</ion-label> <ion-label>
Item Label
</ion-label>
</ion-item> </ion-item>
``` ```
@ -545,7 +553,7 @@ The attributes to show/hide the detail arrows on items have been converted to a
**New Usage Example:** **New Usage Example:**
```html ```html
<ion-item tappable detail="false"> <ion-item button detail="false">
<ion-label>Item Label</ion-label> <ion-label>Item Label</ion-label>
</ion-item> </ion-item>

View File

@ -30,6 +30,11 @@ export class Item {
*/ */
@Prop() mode: 'ios' | 'md'; @Prop() mode: 'ios' | 'md';
/**
* If true, a button tag will be rendered and the item will be tappable. Defaults to `false`.
*/
@Prop() button = false;
/** /**
* If true, a detail arrow will appear on the item. Defaults to `false` unless the `mode` * If true, a detail arrow will appear on the item. Defaults to `false` unless the `mode`
* is `ios` and an `href`, `onclick` or `button` property is present. * is `ios` and an `href`, `onclick` or `button` property is present.
@ -48,14 +53,8 @@ export class Item {
@Prop() href: string; @Prop() href: string;
/** /**
* Whether or not this item should be tappable. * When using a router, it specifies the transition direction when navigating to
* If true, a button tag will be rendered. Defaults to `false`. * another page using `href`.
*/
@Prop() button = false;
/**
* When using a router, it specifies the transition direction when navigating a
* another page usign `href`.
*/ */
@Prop() routerDirection: 'forward' | 'back'; @Prop() routerDirection: 'forward' | 'back';

View File

@ -1,5 +1,43 @@
# ion-item # ion-item
Items are elements that can contain text, icons, avatars, images, inputs, and any other native or custom elements. Generally they are placed in a list with other items. Items can be swiped, deleted, reordered, edited, and more.
## Detail Arrows
By default, clickable items will display a right arrow icon on `ios` mode. To hide the right arrow icon on clickable elements, set the `detail` property to `false`. To show the right arrow icon on an item that doesn't display it naturally, add the `detail` attribute to the item.
This feature is not enabled by default on clickable items for the `md` mode, but it can be enabled by setting the following Sass variable:
```scss
$item-md-detail-push-show: true;
```
It can also be turned off by default on clickable items for ios by setting the following Sass variable:
```scss
$item-ios-detail-push-show: false;
```
See the [theming documentation](http://ionicframework.com/docs/theming/overriding-ionic-variables/) for more information on overriding Sass variables.
## Item Placement
Item uses named [slots](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot) in order to position content. This logic makes it possible to write a complex item with simple, understandable markup without having to worry about styling and positioning the elements.
The below chart details the item slots and where it will place the element inside of the item:
| Slot | Description |
|---------|-----------------------------------------------------------------------------------|
| `start` | Placed to the left of all other content in LTR, and to the `right` in RTL. |
| `end` | Placed to the right of all other content in LTR, and to the `right` in RTL. |
| none | Placed inside of the input wrapper. |
### Text Alignment
Items left align text and add an ellipsis when the text is wider than the item. See the [Utility Attributes Documentation](../../../../theming/css-utilities/) for attributes that can be added to `<ion-item>` to transform the text.
<!-- Auto Generated Below --> <!-- Auto Generated Below -->
@ -11,8 +49,7 @@
boolean boolean
Whether or not this item should be tappable. If true, a button tag will be rendered and the item will be tappable. Defaults to `false`.
If true, a button tag will be rendered. Defaults to `false`.
#### color #### color
@ -60,8 +97,8 @@ For more information, see [Platform Styles](/docs/theming/platform-specific-styl
string string
When using a router, it specifies the transition direction when navigating a When using a router, it specifies the transition direction when navigating to
another page usign `href`. another page using `href`.
## Attributes ## Attributes
@ -70,8 +107,7 @@ another page usign `href`.
boolean boolean
Whether or not this item should be tappable. If true, a button tag will be rendered and the item will be tappable. Defaults to `false`.
If true, a button tag will be rendered. Defaults to `false`.
#### color #### color
@ -119,8 +155,8 @@ For more information, see [Platform Styles](/docs/theming/platform-specific-styl
string string
When using a router, it specifies the transition direction when navigating a When using a router, it specifies the transition direction when navigating to
another page usign `href`. another page using `href`.

View File

@ -0,0 +1,250 @@
Basic Usage
```html
<!-- Default Item -->
<ion-item>
<ion-label>
Item
</ion-label>
</ion-item>
<!-- Item as a Button -->
<ion-item (click)="buttonClick()">
<ion-label>
Button Item
</ion-label>
</ion-item>
<!-- Item as an Anchor -->
<ion-item href="https://www.ionicframework.com">
<ion-label>
Anchor Item
</ion-label>
</ion-item>
<ion-item color="secondary">
<ion-label>Secondary Color Item</ion-label>
</ion-item>
```
Detail Arrows
```html
<ion-item detail>
<ion-label>
Standard Item with Detail Arrow
</ion-label>
</ion-item>
<ion-item (click)="buttonClick()">
<ion-label>
Button Item with Detail Arrow
</ion-label>
</ion-item>
<ion-item detail="false" href="https://www.ionicframework.com">
<ion-label>
Anchor Item with no Detail Arrow
</ion-label>
</ion-item>
```
List Items
```html
<ion-list>
<ion-item>
Item
</ion-item>
<ion-item no-lines>
No Lines Item
</ion-item>
<ion-item text-wrap>
Multiline text that should wrap when it is too long
to fit on one line in the item.
</ion-item>
<ion-item text-wrap>
<ion-label>
<ion-text color="primary">
<h3>H3 Primary Title</h3>
</ion-text>
<p>Paragraph line 1</p>
<ion-text color="secondary">
<p>Paragraph line 2 secondary</p>
</ion-text>
</ion-label>
</ion-item>
</ion-list>
```
Media Items
```html
<ion-item (click)="testClick()">
<ion-avatar slot="start">
<img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAAAAACH5BAAAAAAALAAAAAABAAEAAAICTAEAOw==">
</ion-avatar>
<ion-label>
Avatar Start, Button Item
</ion-label>
</ion-item>
<ion-item href="#">
<ion-label>
Thumbnail End, Anchor Item
</ion-label>
<ion-thumbnail slot="end">
<img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAAAAACH5BAAAAAAALAAAAAABAAEAAAICTAEAOw==">
</ion-thumbnail>
</ion-item>
<ion-item>
<ion-thumbnail slot="start">
<img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAAAAACH5BAAAAAAALAAAAAABAAEAAAICTAEAOw==">
</ion-thumbnail>
<ion-label>
<h2>H2 Title Text</h2>
<p>Button on right</p>
</ion-label>
<ion-button fill="outline" slot="end">View</ion-button>
</ion-item>
<ion-item (click)="testClick()">
<ion-thumbnail slot="start">
<img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAAAAACH5BAAAAAAALAAAAAABAAEAAAICTAEAOw==">
</ion-thumbnail>
<ion-label>
<h3>H3 Title Text</h3>
<p>Icon on right</p>
</ion-label>
<ion-icon name="close-circle" slot="end"></ion-icon>
</ion-item>
```
Buttons in Items
```html
<ion-item>
<ion-button slot="start">
Start
</ion-button>
<ion-label>Button Start/End</ion-label>
<ion-button slot="end">
End
</ion-button>
</ion-item>
<ion-item>
<ion-button slot="start">
Start Icon
<ion-icon name="home" slot="end"></ion-icon>
</ion-button>
<ion-label>Buttons with Icons</ion-label>
<ion-button slot="end">
<ion-icon name="star" slot="end"></ion-icon>
End Icon
</ion-button>
</ion-item>
<ion-item>
<ion-button slot="start">
<ion-icon slot="icon-only" name="navigate"></ion-icon>
</ion-button>
<ion-label>Icon only Buttons</ion-label>
<ion-button slot="end">
<ion-icon slot="icon-only" name="star"></ion-icon>
</ion-button>
</ion-item>
```
Icons in Items
```html
<ion-item>
<ion-label>
Icon End
</ion-label>
<ion-icon name="information-circle" slot="end"></ion-icon>
</ion-item>
<ion-item>
<ion-label>
Large Icon End
</ion-label>
<ion-icon name="information-circle" size="large" slot="end"></ion-icon>
</ion-item>
<ion-item>
<ion-label>
Small Icon End
</ion-label>
<ion-icon name="information-circle" size="small" slot="end"></ion-icon>
</ion-item>
<ion-item>
<ion-icon name="star" slot="start"></ion-icon>
<ion-label>
Icon Start
</ion-label>
</ion-item>
<ion-item>
<ion-label>
Two Icons End
</ion-label>
<ion-icon name="checkmark-circle" slot="end"></ion-icon>
<ion-icon name="shuffle" slot="end"></ion-icon>
</ion-item>
```
Item Inputs
```html
<ion-item>
<ion-label position="floating">Datetime</ion-label>
<ion-datetime></ion-datetime>
</ion-item>
<ion-item>
<ion-label position="floating">Select</ion-label>
<ion-select>
<ion-select-option value="">No Game Console</ion-select-option>
<ion-select-option value="nes">NES</ion-select-option>
<ion-select-option value="n64" selected>Nintendo64</ion-select-option>
<ion-select-option value="ps">PlayStation</ion-select-option>
<ion-select-option value="genesis">Sega Genesis</ion-select-option>
<ion-select-option value="saturn">Sega Saturn</ion-select-option>
<ion-select-option value="snes">SNES</ion-select-option>
</ion-select>
</ion-item>
<ion-item>
<ion-label>Toggle</ion-label>
<ion-toggle slot="end"></ion-toggle>
</ion-item>
<ion-item>
<ion-label position="floating">Floating Input</ion-label>
<ion-input></ion-input>
</ion-item>
<ion-item>
<ion-label>Input (placeholder)</ion-label>
<ion-input placeholder="Placeholder"></ion-input>
</ion-item>
<ion-item>
<ion-label>Checkbox</ion-label>
<ion-checkbox slot="start"></ion-checkbox>
</ion-item>
<ion-item>
<ion-label>Range</ion-label>
<ion-range></ion-range>
</ion-item>
```

View File

@ -0,0 +1,250 @@
Basic Usage
```html
<!-- Default Item -->
<ion-item>
<ion-label>
Item
</ion-label>
</ion-item>
<!-- Item as a Button -->
<ion-item onclick="buttonClick()">
<ion-label>
Button Item
</ion-label>
</ion-item>
<!-- Item as an Anchor -->
<ion-item href="https://www.ionicframework.com">
<ion-label>
Anchor Item
</ion-label>
</ion-item>
<ion-item color="secondary">
<ion-label>Secondary Color Item</ion-label>
</ion-item>
```
Detail Arrows
```html
<ion-item detail>
<ion-label>
Standard Item with Detail Arrow
</ion-label>
</ion-item>
<ion-item onclick="buttonClick()">
<ion-label>
Button Item with Detail Arrow
</ion-label>
</ion-item>
<ion-item detail="false" href="https://www.ionicframework.com">
<ion-label>
Anchor Item with no Detail Arrow
</ion-label>
</ion-item>
```
List Items
```html
<ion-list>
<ion-item>
Item
</ion-item>
<ion-item no-lines>
No Lines Item
</ion-item>
<ion-item text-wrap>
Multiline text that should wrap when it is too long
to fit on one line in the item.
</ion-item>
<ion-item text-wrap>
<ion-label>
<ion-text color="primary">
<h3>H3 Primary Title</h3>
</ion-text>
<p>Paragraph line 1</p>
<ion-text color="secondary">
<p>Paragraph line 2 secondary</p>
</ion-text>
</ion-label>
</ion-item>
</ion-list>
```
Media Items
```html
<ion-item onclick="testClick()">
<ion-avatar slot="start">
<img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAAAAACH5BAAAAAAALAAAAAABAAEAAAICTAEAOw==">
</ion-avatar>
<ion-label>
Avatar Start, Button Item
</ion-label>
</ion-item>
<ion-item href="#">
<ion-label>
Thumbnail End, Anchor Item
</ion-label>
<ion-thumbnail slot="end">
<img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAAAAACH5BAAAAAAALAAAAAABAAEAAAICTAEAOw==">
</ion-thumbnail>
</ion-item>
<ion-item>
<ion-thumbnail slot="start">
<img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAAAAACH5BAAAAAAALAAAAAABAAEAAAICTAEAOw==">
</ion-thumbnail>
<ion-label>
<h2>H2 Title Text</h2>
<p>Button on right</p>
</ion-label>
<ion-button fill="outline" slot="end">View</ion-button>
</ion-item>
<ion-item onclick="testClick()">
<ion-thumbnail slot="start">
<img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAAAAACH5BAAAAAAALAAAAAABAAEAAAICTAEAOw==">
</ion-thumbnail>
<ion-label>
<h3>H3 Title Text</h3>
<p>Icon on right</p>
</ion-label>
<ion-icon name="close-circle" slot="end"></ion-icon>
</ion-item>
```
Buttons in Items
```html
<ion-item>
<ion-button slot="start">
Start
</ion-button>
<ion-label>Button Start/End</ion-label>
<ion-button slot="end">
End
</ion-button>
</ion-item>
<ion-item>
<ion-button slot="start">
Start Icon
<ion-icon name="home" slot="end"></ion-icon>
</ion-button>
<ion-label>Buttons with Icons</ion-label>
<ion-button slot="end">
<ion-icon name="star" slot="end"></ion-icon>
End Icon
</ion-button>
</ion-item>
<ion-item>
<ion-button slot="start">
<ion-icon slot="icon-only" name="navigate"></ion-icon>
</ion-button>
<ion-label>Icon only Buttons</ion-label>
<ion-button slot="end">
<ion-icon slot="icon-only" name="star"></ion-icon>
</ion-button>
</ion-item>
```
Icons in Items
```html
<ion-item>
<ion-label>
Icon End
</ion-label>
<ion-icon name="information-circle" slot="end"></ion-icon>
</ion-item>
<ion-item>
<ion-label>
Large Icon End
</ion-label>
<ion-icon name="information-circle" size="large" slot="end"></ion-icon>
</ion-item>
<ion-item>
<ion-label>
Small Icon End
</ion-label>
<ion-icon name="information-circle" size="small" slot="end"></ion-icon>
</ion-item>
<ion-item>
<ion-icon name="star" slot="start"></ion-icon>
<ion-label>
Icon Start
</ion-label>
</ion-item>
<ion-item>
<ion-label>
Two Icons End
</ion-label>
<ion-icon name="checkmark-circle" slot="end"></ion-icon>
<ion-icon name="shuffle" slot="end"></ion-icon>
</ion-item>
```
Item Inputs
```html
<ion-item>
<ion-label position="floating">Datetime</ion-label>
<ion-datetime></ion-datetime>
</ion-item>
<ion-item>
<ion-label position="floating">Select</ion-label>
<ion-select>
<ion-select-option value="">No Game Console</ion-select-option>
<ion-select-option value="nes">NES</ion-select-option>
<ion-select-option value="n64" selected>Nintendo64</ion-select-option>
<ion-select-option value="ps">PlayStation</ion-select-option>
<ion-select-option value="genesis">Sega Genesis</ion-select-option>
<ion-select-option value="saturn">Sega Saturn</ion-select-option>
<ion-select-option value="snes">SNES</ion-select-option>
</ion-select>
</ion-item>
<ion-item>
<ion-label>Toggle</ion-label>
<ion-toggle slot="end"></ion-toggle>
</ion-item>
<ion-item>
<ion-label position="floating">Floating Input</ion-label>
<ion-input></ion-input>
</ion-item>
<ion-item>
<ion-label>Input (placeholder)</ion-label>
<ion-input placeholder="Placeholder"></ion-input>
</ion-item>
<ion-item>
<ion-label>Checkbox</ion-label>
<ion-checkbox slot="start"></ion-checkbox>
</ion-item>
<ion-item>
<ion-label>Range</ion-label>
<ion-range></ion-range>
</ion-item>
```