doc(camelCase Angular): migration guide

This commit is contained in:
Victor Berchet 2015-12-02 16:10:14 -08:00 committed by Igor Minar
parent 1e740581ee
commit b386d1134a
1 changed files with 162 additions and 0 deletions

View File

@ -0,0 +1,162 @@
Angular2 templates are now case sensitive.
## Overview
Where you used to write:
<my-cmp (some-event)="someAction()" [some-property]="expression" #some-var>
in order to:
- bind to the `someEvent` event,
- bind to the `someProperty` property,
- create a `someVar` local variable
You should now write:
<my-cmp (someEvent)="someAction()" [someProperty]="expression" #someVar>
Notes:
- while tag name are case sensitive, the best practice is to use dash case for component elements so that the browser
interpret them as custom elements,
- `(some-event)` would now bind to the `some-event` event (i.e. there is no implicit dash to camel case conversion),
- `(some-property)` would now bind to the `some-property` property (i.e. there is no implicit dash to camel case conversion),
- `#some-var` is not allowed any more ("-" can not be used in variable names).
## Migration
#### Templates
1. Directives selectors, property bindings, event bindings, template variables and template element attributes should be changed to camel case:
Examples:
- `<p *ng-if="cond">` should be changed to `<p *ngIf="cond">`,
- `<my-cmp [my-prop]="exp">` should be changed to `<my-cmp [myProp]="exp">`,
- `<my-cmp (my-event)="action()">` should be changed to `<my-cmp (myEvent)="action()">`,
- `<my-cmp [(my-prop)]="prop">` should be changed to `<my-cmp [(myProp)]="prop">`,
- `<input #my-input>` should be changed to `<input #myInput>`,
- `<template ng-for #my-item [ng-for-of]=items #my-index="index">` should be changed to `<template ngFor="#my-item" [ngForOf]=items #myIndex="index">`,
Note: while the tag names are now case sensitive the best practice is to keep them lower dash cased so that the browser
treat them as custom elements. This explains why the `<router-outlet>` component is left unchanged.
`on-`, `bindon-`, `bind-` and `var-` prefixes are still part of the canonical syntax and should remain unchanged (lower cased):
- `on-some-event` should be changed to `on-someEvent`,
- `bind-my-prop` should be changed to `bind-myProp`,
- `bindon-my-prop` should be changed to `bindon-myProp`,
- `var-my-var` should be changed to `var-myVar`.
2. Update variable binding
- `<p #var1="a-b" var-var2="c-d">` should be changed to `<p #var1="aB" var-var2="cD">`
3. The `template` attribute values should also be updated in the same way
`<p template="ng-for #my-item of items #my-index = index">` should be changed to `<p template="ngFor #myItem of items #myIndex = index">`.
Note that both angular directives and your own directives must be updated in the same way.
#### Directives and Components
Take the following steps to upgrade your directives and components:
1. Update the selector:
@Directive({selector: 'tag[attr][name=value]'})
@Component({selector: 'tag[attr][name=value]'})
Tag and attributes names are case sensitive:
- For tag names, the best practice is to keep them lower dash cased, do not update them,
- For attribute names, the best practice is to convert them from lower dash case to camel case.
Examples:
- `custom-tag` should stay `custom-tag` (do not update tag names),
- `[attr-name]` should be updated to `[attrName]`,
- `[attr-name=someValue]` should be updated to `[attrName=someValue]`,
- `custom-tag[attr-name=someValue]` should be updated to `custom-tag[attrName=someValue]`
Note: attribute values and classes are still matched case insensitive.
2. Update the inputs
@Directive({inputs: ['myProp', 'myOtherProp: my-attr-name']})
As attribute names are now case sensitive, they should be converted from dash to camel case where they are specified.
The previous decorator becomes:
@Directive({inputs: ['myProp', 'myOtherProp: myAttrName']})
Notes:
- only the long syntax (with ":") needs not be updated,
- `properties` is the legacy name for `inputs` and should be updated in the same way - it is a good idea to replace
`properties` with `inputs` at the same time as support for the former will be removed soon.
The same applies for the `@Input` decorator:
@Input() myProp;
@Input('my-attr-name') myProp;
That is they only need to be updated when the attribute name is specified:
@Input() myProp; // Nothing to update
@Input('myAttrName') myProp; // Convert the attribute name to camel case
3. Update the outputs
Update the outputs in the same way the inputs are updated:
@Directive({outputs: ['myEvent', 'myOtherEvent: my-event-name']})
should be updated to
@Directive({outputs: ['myEvent', 'myOtherEvent: myEventName']})
If you use `events` instead of `outputs` you should update in the same way and switch to `outputs` as `events` is deprecated.
@Output() myEvent;
@Output('my-event-name') myEvent;
should be changed to
@Output() myEvent;
@Output('myEventName') myEvent;
4. Update the host bindings
@Directive({
host: {
'[some-prop]': 'exp',
'[style.background-color]': 'exp',
'[class.some-class]': 'exp',
'(some-event)': 'action()',
'some-attr': 'value'
}
})
should be changed to:
@Directive({
host: {
'[someProp]': 'exp',
'[style.background-color]': 'exp',
'[class.some-class]': 'exp',
'(someEvent)': 'action()',
'some-attr': 'value'
}
})
The property bindings (`[...]`) and event bindings (`(...)`) must be updated in the same way as they are updated in a
template (reminder: `[attr.]`, `[class.]` and `[style.]` should not be converted to camel case).
5. Update export name
@Directive({
exportAs: 'some-name'
})
should be changed to
@Directive({
exportAs: 'someName'
})