Skip to content

Commit 3aac2fe

Browse files
tboschtbosch
committed
refactor(compiler): remove Viewport directives, use Decorator instead
BREAKING_CHANGE: - The special type of `Viewport` directives is removed in favor of a more general `Decorator` directive - `ViewContainerRef` now no more has a default `ProtoViewRef` but requires an explicit one when creating views. Closes angular#1536
1 parent fb67e37 commit 3aac2fe

35 files changed

Lines changed: 219 additions & 305 deletions

‎modules/angular2/docs/core/01_templates.md‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ projected to DOM as well as which DOM events should invoke which methods on the
55
syntax which is core to Angular and allows for data-binding, event-binding, template-instantiation.
66

77
The design of the template syntax has these properties:
8-
8+
99

1010
* All data-binding expressions are easily identifiable. (i.e. there is never an ambiguity whether the value should be
1111
interpreted as string literal or as an expression.)
@@ -372,8 +372,8 @@ Where:
372372
inserted. The template can be defined implicitly with `template` attribute, which turns the current element into
373373
a template, or explicitly with `<template>` element. Explicit declaration is longer, but it allows for having
374374
templates which have more than one root DOM node.
375-
* `viewport` is required for templates. The Viewport directive is responsible for deciding when
376-
and in which order should child views be inserted into this location. An Viewport directive usually has one or
375+
* `viewport` is required for templates. The directive is responsible for deciding when
376+
and in which order should child views be inserted into this location. Such a directive usually has one or
377377
more bindings and can be represented as either `viewport-directive-bindings` or
378378
`viewport-directive-microsyntax` on `template` element or attribute. See template microsyntax for more details.
379379

@@ -387,7 +387,7 @@ Hello {{user}}!
387387
</div>
388388
```
389389

390-
In the above example the `if` Viewport determines whether the child view (an instance of the child template) should be
390+
In the above example the `if` directive determines whether the child view (an instance of the child template) should be
391391
inserted into the root view. The `if` makes this decision based on if the `isAdministrator` binding is true.
392392

393393
The above example is in the short form, for better clarity let's rewrite it in the canonical form, which is functionally
@@ -402,8 +402,6 @@ Hello {{user}}!
402402
</template>
403403
```
404404

405-
NOTE: Only Viewport directives can be placed on the template element. (Decorators and Components are not allowed.)
406-
407405

408406
### Template Microsyntax
409407

@@ -514,7 +512,7 @@ Where:
514512
* `some-element` Any element which can generate DOM events (or has an angular directive which generates the event).
515513
* `some-event` (escaped with `()` or `on-`) is the name of the event `some-event`. In this case the
516514
dash-case is converted into camel-case `someEvent`.
517-
* `statement` is a valid statement (as defined in section below).
515+
* `statement` is a valid statement (as defined in section below).
518516
If the execution of the statement returns `false`, then `preventDefault`is applied on the DOM event.
519517

520518
By default, angular only listens to the element on the event, and ignores events which bubble. To listen to bubbled

‎modules/angular2/docs/core/02_directives.md‎

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@ There are three different kinds of directives (described in more detail in later
1010

1111
1. *Decorators*: can be placed on any DOM element and can be combined with other directives.
1212
2. *Components*: Components have an encapsulated view and can configure injectors.
13-
3. *Viewport*: is responsible for adding or removing child views in a parent view. (i.e. for, if)
1413

1514

1615

@@ -163,39 +162,39 @@ Example of usage:
163162

164163

165164

166-
## Viewport
165+
## Directives that use a ViewContainer
167166

168-
Viewport is a directive which can control instantiation of child views which are then inserted into the DOM. (Examples are `if` and `for`.)
167+
Directives that use a ViewContainer can control instantiation of child views which are then inserted into the DOM. (Examples are `if` and `for`.)
169168

170-
* Viewports can only be placed on `<template>` elements (or the short hand version which uses `<element template>` attribute.)
171-
* Only one viewport can be present per DOM template element.
172-
* The viewport is created over the `template` element. This is known as the `ViewContainerRef`.
173-
* Viewport can insert child views into the `ViewContainerRef`. The child views show up as siblings of the `Viewport` in the DOM.
169+
* Every `template` element creates a `ProtoView` which can be used to create Views via the ViewContainer.
170+
* The child views show up as siblings of the directive in the DOM.
174171

175172
>> TODO(misko): Relationship with Injection
176173
>> TODO(misko): Instantiator can not be injected into child Views
177174
178175

179176
```
180-
@Viewport({
177+
@Directive({
181178
selector: '[if]',
182179
properties: {
183180
'condition': 'if'
184181
}
185182
})
186183
export class If {
187184
viewContainer: ViewContainerRef;
185+
protoViewRef: ProtoViewRef;
188186
view: View;
189187
190-
constructor(viewContainer: ViewContainerRef) {
188+
constructor(viewContainer: ViewContainerRef, protoViewRef: ProtoViewRef) {
191189
this.viewContainer = viewContainer;
190+
this.protoViewRef = protoViewRef;
192191
this.view = null;
193192
}
194193
195194
set condition(value) {
196195
if (value) {
197196
if (this.view === null) {
198-
this.view = this.viewContainer.create();
197+
this.view = this.viewContainer.create(protoViewRef);
199198
}
200199
} else {
201200
if (this.view !== null) {
@@ -342,7 +341,7 @@ Shadow DOM provides an encapsulation for components, so as a general rule it doe
342341
})
343342
class Kid {
344343
constructor(
345-
@Parent() dad:Dad,
344+
@Parent() dad:Dad,
346345
@Optional() grandpa:Grandpa
347346
) {
348347
this.name = 'Billy';
@@ -365,7 +364,7 @@ class Dad {
365364
this.dad = dad.name;
366365
console.log(dad)
367366
}
368-
}
367+
}
369368
370369
@Component({
371370
selector: '[grandpa]',
@@ -379,17 +378,17 @@ class Grandpa {
379378
constructor() {
380379
this.name = 'Joe';
381380
}
382-
}
381+
}
383382
```
384383

385384
Assume the following DOM structure for `grandpa.html`: The Dad has access to the Grandpa.
386385
```
387-
Name: {{name}}: <br> Children: <div dad></div>
386+
Name: {{name}}: <br> Children: <div dad></div>
388387
```
389388

390389
Assume the following DOM structure for `dad.html`: Here the rendered Kid will also have access to Grandpa.
391390
```
392-
Name: {{name}}: <br> Dad: {{dad}} <br> Children: <div kid></div>
391+
Name: {{name}}: <br> Dad: {{dad}} <br> Children: <div kid></div>
393392
```
394393

395394
## Further Reading

‎modules/angular2/docs/core/10_view.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44

55
This document explains the concept of a View.
66
A View is a core primitive used by angular to render the DOM tree.
7-
A ViewPort is location in a View which can accept child Views.
8-
Every ViewPort has an associated ViewContainerRef than can contain any number of child Views.
7+
A ViewContainer is location in a View which can accept child Views.
8+
Every ViewContainer has an associated ViewContainerRef than can contain any number of child Views.
99
Views form a tree structure which mimics the DOM tree.
1010

1111
* View is a core rendering construct. A running application is just a collection of Views which are
@@ -15,7 +15,7 @@ Views form a tree structure which mimics the DOM tree.
1515
* Views represent a running instance of a DOM View. This implies that while elements in a View
1616
can change properties, they can not change structurally. (Structural changes such as, adding or
1717
removing elements requires adding or removing child Views into ViewContainers).
18-
* View can have zero or more ViewPorts. A ViewPort is a marker in the DOM which allows
18+
* View can have zero or more ViewContainers. A ViewContainer is a marker in the DOM which allows
1919
the insertion of child Views.
2020
* Views are created from a ProtoView. A ProtoView is a compiled DOM View which is efficient at
2121
creating Views.
@@ -88,7 +88,7 @@ Note:
8888
## Composed View
8989

9090
An important part of an application is to be able to change the DOM structure to render data for the
91-
user. In Angular this is done by inserting child views into the ViewPort.
91+
user. In Angular this is done by inserting child views into the ViewContainer.
9292

9393
Let's start with a View such as:
9494

@@ -108,7 +108,7 @@ and
108108

109109
```
110110
<ul> | protoViewA(someContext)
111-
<template></template> | protoViewA(someContext): new ProtoViewPort(protoViewB)
111+
<template></template> | protoViewA(someContext): protoViewB
112112
</ul> | protoViewA(someContext)
113113
```
114114

@@ -119,7 +119,7 @@ The next step is to compose these two ProtoViews into an actual view which is re
119119

120120
```
121121
<ul> | viewA(someContext)
122-
<template></template> | viewA(someContext): new Foreach(new ViewPort(protoViewB))
122+
<template></template> | viewA(someContext): new Foreach(new ViewContainer(protoViewB))
123123
</ul> | viewA(someContext)
124124
```
125125

@@ -128,11 +128,11 @@ has a reference to `protoViewA`).
128128

129129

130130
*Step3:* As the `Foreach` directive unrolls it asks the `ViewContainerRef` to instantiate `protoViewB` and insert
131-
it after the `ViewPort` anchor. This is repeated for each `person` in `people`. Notice that
131+
it after the `ViewContainer` anchor. This is repeated for each `person` in `people`. Notice that
132132

133133
```
134134
<ul> | viewA(someContext)
135-
<template></template> | viewA(someContext): new Foreach(new ViewPort(protoViewB))
135+
<template></template> | viewA(someContext): new Foreach(new ViewContainer(protoViewB))
136136
<li>{{person}}</li> | viewB0(locals0(someContext))
137137
<li>{{person}}</li> | viewB1(locals0(someContext))
138138
</ul> | viewA(someContext)
@@ -145,13 +145,13 @@ delegate any unknown references to the parent context.
145145

146146
```
147147
<ul> | viewA
148-
<template></template> | viewA: new Foreach(new ViewPort(protoViewB))
148+
<template></template> | viewA: new Foreach(new ViewContainer(protoViewB))
149149
<li>Alice</li> | viewB0
150150
<li>Bob</li> | viewB1
151151
</ul> | viewA
152152
```
153153

154-
Each View can have zero or more ViewPorts. By inserting and removing child Views to and from the
154+
Each View can have zero or more ViewContainers. By inserting and removing child Views to and from the
155155
ViewContainers, the application can mutate the DOM structure to any desirable state. A View may contain
156156
individual nodes or a complex DOM structure. The insertion points for the child Views, known as
157157
ViewContainers, contain a DOM element which acts as an anchor. The anchor is either a `template` or
@@ -161,7 +161,7 @@ inserted.
161161
## Component Views
162162

163163
A View can also contain Components. Components contain Shadow DOM for encapsulating their internal
164-
rendering state. Unlike ViewPorts which can contain zero or more Views, the Component always contains
164+
rendering state. Unlike ViewContainers which can contain zero or more Views, the Component always contains
165165
exactly one Shadow View.
166166

167167
```

0 commit comments

Comments
 (0)