diff --git a/modules/angular2/docs/core/01_templates.md b/modules/angular2/docs/core/01_templates.md index a85506bb9a..eb9c752256 100644 --- a/modules/angular2/docs/core/01_templates.md +++ b/modules/angular2/docs/core/01_templates.md @@ -8,7 +8,7 @@ The design of template syntax has these properties: * All data-binding expressions are easily identifiable. (i.e. there is never an ambiguity wether the value should be interpreted as string literal or as an expression.) -* All events and their statments are easily identifiable. +* All events and their statements are easily identifiable. * All places of DOM instantiation are easily identifiable. * All places of variable declaration is esily identifiable. @@ -300,7 +300,7 @@ keeping `null` and `undefined` as empty strings. ## Inline Templates Data binding allows updating the DOM's properties, but it does not allow for changing of the DOM structure. To change -DOM structure we need the ability to define child templates, and than instantiat these templates into Views. The +DOM structure we need the ability to define child templates, and then instantiate these templates into Views. The Views can than be inserted and removed as needed to change the DOM structure. @@ -370,8 +370,8 @@ NOTE: Only Instantiator directives can be placed on the template element. (Decor ### Template Microsyntax -Often times it is necessary to encode a lot of different bindings into a template to controll how the instantiation -of the templates occures. One such example is foreach. +Often times it is necessary to encode a lot of different bindings into a template to control how the instantiation +of the templates occurs. One such example is foreach. ``` @@ -389,8 +389,8 @@ Where: * `#person` exports the implicit `foreach` item. * `#i=index` exports item index as `i`. -The above example is explicit but quite wordy, for this reason in most situatios a short hand version of the -syntax is prefferable. +The above example is explicit but quite wordy, for this reason in most situations a short hand version of the +syntax is preferable. ``` ``` -We can also optionaly use `var` instead of `#` and add `:` to `foreach` which creates the following recomended +We can also optionally use `var` instead of `#` and add `:` to `foreach` which creates the following recommended microsyntax for `foreach`. ``` @@ -432,18 +432,18 @@ microsyntax: ([[key|keyExpression|varExport][;|,]?)* Where * `expression` is an angular expression as defined in section: Expressions -* `local` is a local identifiar for local variables. +* `local` is a local identifier for local variables. * `internal` is an internal variable which the directive exports for binding. * `key` is an attribute name usually only used to trigger a specific directive. * `keyExpression` is an property name to which the epression will be bound to. -* `varExport` allows exporting of directive internal state as varibles for further binding. If no `internal` name +* `varExport` allows exporting of directive internal state as variables for further binding. If no `internal` name is specified than the exporting is to an implicit variable. * `microsyntax` allows you to build simple microsyntax which can still clearly identify which expressions bind to - which properties as well as which varibales are exported for binding. + which properties as well as which variables are exported for binding. NOTE: the `template` attribute must be present to make it clear to the user that a sub-template is being created. This -goes allong the philosophy that the developer should be able to reason about the template without understanding the +goes along the philosophy that the developer should be able to reason about the template without understanding the semantics of the instantiator directive. @@ -470,7 +470,7 @@ Where: dash-case is converted into camel-case `someEvent`. * `statement` is a valid statement (as defined in section below). -By default angular anly listens to the element on the event, and ignores events which bubble. To listen to bubbled +By default angular only listens to the element on the event, and ignores events which bubble. To listen to bubbled events (as in the case of clicking on any child) use the bubble option (`(^event)` or `on-bubble-event`) as shown bellow. @@ -511,7 +511,7 @@ bind to custom events of Custom Elements, whos event names are not known ahead o ## Expressions, Statements and Formatters -Angular templates contain expressions for binding to data and statments for binding to events. Expressions and statments +Angular templates contain expressions for binding to data and statements for binding to events. Expressions and statements have different semantics. @@ -527,15 +527,15 @@ Angular are:
...
``` -Expressions are simplified version of expression in the langugage in which you are writing your application. (i.e. -expressions fallow JS syntax and semantics in JS and Dart syntax and semantics in Dart). Unlike expressions in the -langugage, binding expressions behave differently in following ways: +Expressions are simplified version of expression in the language in which you are writing your application. (i.e. +expressions follow JS syntax and semantics in JS and Dart syntax and semantics in Dart). Unlike expressions in the +language, binding expressions behave differently in following ways: -* *Must be defined*: Anlike Angular v1, Angular v2 will throw an error on dereferencing fields which are not defined. +* *Must be defined*: Unlike Angular v1, Angular v2 will throw an error on dereferencing fields which are not defined. For example: `user.name` will throw an error if `user` is defined but it does not have `name` property. If the `name` property is not known, it must be declared and set to some value such as empty string, `null` (or `undefined` in JS). This is done to allow early detection of errors in the templates. -* *Safe dereference*: Expressions `user.name` where `user` is null will throw `NullPointerException` in the langugage. +* *Safe dereference*: Expressions `user.name` where `user` is null will throw `NullPointerException` in the language. In contrast Angular will silently ignore `null` on `user`. This is done because Views often have to wait for the data to arrive from the backend and many fields will be `null` until the data arrives. Safe dereference is so common in the Views, that we have made it the default. @@ -559,32 +559,32 @@ class Greeter { property is `null` or `undefined`. Example of: safe dereference. * `foo`: Will thrown on error because `foo` is not declared on the `Greeter` class. Example of: Must be defined * `name=1`: Not allowed because fo assignment. -* `name; name.length`: Not allowed because of multiple statments. +* `name; name.length`: Not allowed because of multiple statements. ### Statements Statements can be used to bind to events only. Statements represent actions to trigger as a response to an event. -Examples of where statments can be used in Angular are: +Examples of where statements can be used in Angular are: ``` -
...
-
...
+
...
+
...
``` -Statements are similar to statments in the langugage in which you are writing your application. (i.e. -statments follow JS syntax and semantics in JS and Dart syntax and semantics in Dart). Unlike statments in the -langugage, binding expressions behave differently in following ways: +Statements are similar to statements in the language in which you are writing your application. (i.e. +statements follow JS syntax and semantics in JS and Dart syntax and semantics in Dart). Unlike statements in the +language, binding expressions behave differently in following ways: * *Unsafe dereference*: Expressions `user.verify()` where `user` is `null` will throw `NullPointerException` in the - langugage as well as in statments. (In contrast to Safe dereference in Angular expressions.) While angular protects - you from null dereferencing in expressions due to lazy loading of data, no such protection is required for statments, + language as well as in statements. (In contrast to Safe dereference in Angular expressions.) While angular protects + you from null dereferencing in expressions due to lazy loading of data, no such protection is required for statements, and doing so would make it harder to detect typos in statements. -* *Multiple statements OK*: Statements can be composed from more than one statemnet. (i.e. no `doA(); doB()`) +* *Multiple statements OK*: Statements can be composed from more than one statement. (i.e. no `doA(); doB()`) * *Assignments OK*: Event bindings can have side effects and hence assignments are allowed. * *No keywords*: Statements can not contain keywords such as: `var`, `if`, and so on. -* *No Formatters*: Angular statements can not contain formatters. (Formatters are only usefull for data binding) +* *No Formatters*: Angular statements can not contain formatters. (Formatters are only useful for data binding) ## Further Reading -* [Template Syntax Constraints and Reasoning](https://docs.google.com/document/d/1HHy_zPLGqJj0bHMiWPzPCxn1pO5GlOYwmv-qGgl4f_s) \ No newline at end of file +* [Template Syntax Constraints and Reasoning](https://docs.google.com/document/d/1HHy_zPLGqJj0bHMiWPzPCxn1pO5GlOYwmv-qGgl4f_s)