diff options
Diffstat (limited to 'docs/angular2.adoc')
| -rw-r--r-- | docs/angular2.adoc | 222 |
1 files changed, 0 insertions, 222 deletions
diff --git a/docs/angular2.adoc b/docs/angular2.adoc deleted file mode 100644 index 5f13f71..0000000 --- a/docs/angular2.adoc +++ /dev/null @@ -1,222 +0,0 @@ ---- -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. - }); -} ----- |