1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
---
title: Angular 2
order: 2
layout: page
---
[[vaadin-core-elements.angular2]]
= Angular 2 Integration
While Vaadin Elements are built using Polymer, you need the [literal]#https://github.com/vaadin/angular2-polymer[@vaadin/angular2-polymer]# directive to enable seamless usage within Angular 2 applications.
This page assumes that you already have an Angular 2 application setup ready.
If you need help with the project setup, you should follow the https://angular.io/docs/ts/latest/quickstart.html[Angular 2 Quickstart] guide.
== Installation
[NOTE]
Angular 2 support was introduced in `1.1.0-alpha1` versions of each element. +
For element versions `1.1.0-beta2` or newer, use Angular version `2.0.0-rc.0`. +
For element versions `1.1.0-alpha1 to 1.1.0-beta1`, use Angular version `2.0.0-beta.16/17`.
Use https://www.npmjs.com/[npm] to install the generic polymer directive that allows the usage of any Polymer element in Angular 2.
[subs="normal"]
----
[prompt]#$# [command]#npm# install @vaadin/angular2-polymer
----
Although Angular 2 dependecies are typically installed via npm, Vaadin Elements require installation with http://bower.io[Bower].
To install a Vaadin Core Element, first you should set up bower in your project, and then you need to run the following command in your project directory (replace the `[element-name]` part with the actual name of the element).
[subs="normal"]
----
[prompt]#$# [command]#bower# init
[prompt]#$# [command]#bower# install --save vaadin-[replaceable]##element-name#1.1.0-beta3##
----
After the Bower installation is completed, you need to add the Web Components polyfill to the [elementname]#head# section of your [filename]#index.html# file.
[source,html]
----
<script src="bower_components/webcomponentsjs/webcomponents-lite.min.js"></script>
----
The Web Components polyfill will enable usage of HTML imports in your application.
In order to have the newly installed Vaadin element available in your templates, you need to add an import for it.
[source,html]
----
<link rel="import" href="bower_components/vaadin-[element-name]/vaadin-[element-name].html">
----
Also the SystemJS configuration needs some modifications in order to load the modules correctly.
Add the following `map`and `packages` entries for `@vaadin/angular2-polymer` to your configuration.
[source,javascript]
----
System.config({
map: {
'@vaadin': 'node_modules/@vaadin'
},
packages: {
'@vaadin/angular2-polymer': {
main: 'index.js'
}
}
});
----
Before bootstrapping your application, you need to wait for the `WebComponentsReady` event.
The event is fired after the HTML imports are done and the custom elements are upgraded and ready to be used.
The following example demonstrates how to wrap your bootstrap code inside the event listener.
[source,javascript]
----
window.addEventListener('WebComponentsReady', function() {
System.import('app/main').then(null, console.error.bind(console));
});
----
[NOTE]
If you see errors about missing behaviors in the console, please visit the https://github.com/vaadin/vaadin-core-elements/issues/46[Vaadin Core Elements issue #46].
[NOTE]
If compilation fails due to implicitly declared vars in any dependency, set the property [propertyname]#noImplicitAny# to `false` in your [filename]#tsconfig.json# file.
Now you are all set to use the element inside your Angular 2 application.
== Importing
Import the Polymer directive as follows.
[source,javascript]
----
import { PolymerElement } from '@vaadin/angular2-polymer';
----
Your Angular 2 component also needs to declare the usage of the directive.
This can be done with the `directives` array of the `@Component` decorator.
After the directive is declared, the element is available to be used in the `template` of your component.
Te following example uses the directive with the [elementname]#vaadin-date-picker# element. Replace the path with the element you are importing.
[source, javascript]
----
@Component({
selector: 'my-component',
template: '<vaadin-date-picker [(value)]="birthDay"></vaadin-date-picker>',
directives: [PolymerElement('vaadin-date-picker')]
})
----
Notice that for Vaadin Charts, you also need to add the directive for the [vaadinelement]#data-series# element as follows.
[source, javascript]
----
import { PolymerElement } from '@vaadin/angular2-polymer';
@Component({
selector: 'my-component',
template: `
<vaadin-area-chart>
<title>Fibonacci</title>
<x-axis><title>Index</title></x-axis>
<y-axis><title>Value</title></y-axis>
<data-series>
<data>1, 1, 2, 3, 5, 8, 13, 21, 34</data>
</data-series>
</vaadin-area-chart>`,
directives: [PolymerElement('vaadin-charts'), PolymerElement('data-series')]
})
----
== Usage
For the most part, you can use the API provided by the element.
The API is described in the documentation of each individual element.
Most notable changes introduced by the directives are the support for data binding using the Angular 2 syntax and integration with the https://angular.io/docs/ts/latest/guide/forms.html[Angular forms].
=== Data Binding
You can use Angular 2 data-binding syntax with all the properties declared in the API documentation for each element.
Some properties also support two-way data-binding. These are marked with [propertyname]#notifies# in the API documentation.
[source]
----
<vaadin-combo-box
label="My ComboBox"
[(value)]="myValue"
[items]="myItems">
</vaadin-combo-box>
----
=== Form Controls
When using input-like elements ([elementname]#vaadin-combo-box#, [elementname]#vaadin-date-picker#, or [elementname]#vaadin-upload#) inside an Angular form, you should normally use the [propertyname]#ngControl# attribute to track the state and validity.
You can use two-way data-binding with [propertyname]#ngModel# as you would with other form fields.
Validation is supported with the simple [propertyname]#required# validator as well as with custom validators that you can define.
See the following example on how to use [elementname]#vaadin-combo-box# as a form control with data-bound [propertyname]#items# pro perty.
[source]
----
<vaadin-combo-box
label="My ComboBox"
[(ngModel)]="myValue"
[items]="myItems"
ngControl="myCombo"
required>
</vaadin-combo-box>
----
=== Styling
Due to the Shadow DOM encapsulation, applying normal CSS rules for a Vaadin Element is limited to the main element only.
Therefore, in order to fully customize the appearance of Vaadin Elements, you need to use https://www.polymer-project.org/1.0/docs/devguide/styling.html#xscope-styling-details[CSS properties] and https://www.polymer-project.org/1.0/docs/devguide/styling.html#custom-css-mixins[CSS mixins].
Unfortunately, these styles cannot be applied on the component level. Instead you need to provide styles on application level and also use the `is="custom-style"` attribute.
Changing the icon color of [vaadinelement]#vaadin-date-picker# to `red` can be done as in the following example:
[source]
----
<style is="custom-style">
vaadin-date-picker {
--vaadin-date-picker-calendar-icon: {
fill: red;
}
}
</style>
----
See the documentation of each element for a list of available properties and mixins.
=== Grid
The [elementname]#vaadin-grid# element uses a `table` child element to declaratively configure columns, headers, and footers.
In case you need to apply modifications to the declaratively configured [vaadinelement]#vaadin-grid# columns, you must wait for the component to be fully initialized first.
You can wait for it by using the native element as a Promise.
For example, let us assume that you have the following element defined:
[source]
----
<vaadin-grid #grid>
<table>
<colgroup>
<col>
</colgroup>
</table>
</vaadin-grid>
----
Now, you can wait for the initialization to complete with a promise as is done in the following:
[source, javascript]
----
@ViewChild('grid') grid: any;
ngAfterViewInit() {
this.grid.nativeElement.then(() => {
// Some code to configure the grid.
});
}
----
|
