From 99c7541d2b4fc3887ae98953f8c6357a247f835d Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Fri, 26 May 2017 17:44:15 -0400 Subject: [PATCH] docs(readme): update breaking changes in v4 readme --- README.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 156 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index b71a6df6f3..3dc79bac56 100644 --- a/README.md +++ b/README.md @@ -14,18 +14,168 @@ For the most part, `ionic-angular` will continue to work the same way, using the We will continue to develop and support ionic-angular v3 in the master branch. Ultimately the differences between v3 and v4 are internal, but on the surface it's the same `ionic-angular` as v3. :beers: -### Changes +### Breaking Changes -#### `ion-label` Required +#### Dynamic Mode -Previously an `ion-label` would automatically get added to `ion-item` if one wasn't provided. Now an `ion-label` must always be added if the item is used to display text. +Components are no longer able to have their mode changed dynamically. You can change the mode before the first render, but after that it will not style properly because only the initial mode's styles are included. +#### Button + +##### Markup Changed + +Button should now be written as an `` element. Ionic will determine when to render an anchor tag based on the presence of an `href` attribute. + +Old Usage Examples: + +```html + + + + Default Anchor + ``` - - Item's Text! - + +New Usage Examples: + +```html + + Default Button + + + + Default Anchor + ``` +##### Icon Attributes Renamed + +Previously to style icons inside of a button the following attributes were used: `icon-left`, `icon-right`, (and with the added support of RTL) `icon-start`, `icon-end`. + +These have been renamed to the following, and moved from the button element to the icon itself: + +| Old Property | New Property | Property Behavior | +|---------------------------|----------------|-----------------------------------------------------------------------| +| `icon-left`, `icon-start` | `slot="start"` | Positions to the left of the button in LTR, and to the right in RTL. | +| `icon-right`, `icon-end` | `slot="end"` | Positions to the right of the button in LTR, and to the left in RTL. | + + +Old Usage Examples: + +```html + + + Icon Left + + + + + Icon Left on LTR, Right on RTL + + + + Icon Right + + + + + Icon Right on LTR, Left on RTL + + +``` + +New Usage Examples: + +```html + + + Icon Left on LTR, Right on RTL + + + + Icon Right on LTR, Left on RTL + + +``` + + +#### Item + +##### Label Required + +Previously an `ion-label` would automatically get added to an `ion-item` if one wasn't provided. Now an `ion-label` should always be added if the item is used to display text. + +```html + + Item Label + +``` + +##### Attributes Renamed + +Previously to position elements inside of an `ion-item` the following attributes were used: `item-left`, `item-right`, (and with the added support of RTL) `item-start`, `item-end`. + +These have been renamed to the following: + +| Old Property | New Property | Property Behavior | +|---------------------------|----------------|---------------------------------------------------------------------| +| `item-left`, `item-start` | `slot="start"` | Positions to the left of the item in LTR, and to the right in RTL. | +| `item-right`, `item-end` | `slot="end"` | Positions to the right of the item in LTR, and to the left in RTL. | + + +Old Usage Examples: + +```html + +
Left
+ Item Label +
Right
+ + + +
Left on LTR, Right on RTL
+ Item Label +
Right on LTR, Left on RTL
+ +``` + +New Usage Example: + +```html + +
Left on LTR, Right on RTL
+ Item Label +
Right on LTR, Left on RTL
+ +``` + + +#### Toolbar + +##### Attributes Renamed + +Similar to item, the attributes to position an `ion-buttons` element inside of a toolbar have been renamed, as well as the behavior attached to the name. We noticed there was some confusion behind the behavior of the `start` and `end` attributes, and with the new support for RTL we wanted to make the behavior of these match RTL. In order to do this we had to rename the old `start`/`end` to something that makes more sense with their behavior. + +The names and behavior of each of the properties was previously: + +| Property | Description | +|----------|--------------------------------------------------------------------------------------------------------| +| `start` | Positions element to the left of the content in `ios` mode, and directly to the right in `md` and `wp` mode. | +| `end` | Positions element to the right of the content in `ios` mode, and to the far right in `md` and `wp` mode. | +| `left` | Positions element to the left of all other elements. | +| `right` | Positions element to the right of all other elements. | + +The properties have been renamed to the following: + +| Old Property | New Property | Property Behavior | +|--------------|---------------------|---------------------------------------------------------------------------------------| +| `start` | `slot="mode-start"` | Positions element to the `left` of the content in `ios` mode, and directly to the `right` in `md` and `wp` mode. | +| `end` | `slot="mode-end"` | Positions element to the `right` of the content in `ios` mode, and to the far right in `md` and `wp` mode. | +| `left` | `slot="start"` | Positions element to the `left` of all other elements in `LTR`, and to the `right` in `RTL`. | +| `right` | `slot="end"` | Positions element to the `right` of all other elements in `LTR`, and to the `left` in `RTL`. | + ### Testing