Table Of Content

Book of Vaadin Vaadin 14 Edition Book of Vaadin Vaadin Team Vaadin Ltd Revision 1 Published: 2019-07-05 Vaadin 14.0 This book can be downloaded for free at: https://vaadin.com/book Published by: Vaadin Ltd. Ruukinkatu 2-4 20540 Turku, Finland Abstract Vaadin is a web application development framework that enables developers to build high-quality user interfaces with Java. It provides a set of ready-to-use user interface components and allows creating your own components. The focus is on ease-of-use, re-usability, extensibility, and meeting the requirements of large enterprise applications. Copyright © 2000-2019 Vaadin Ltd All rights reserved. This work is licensed under the Creative Commons CC-BY-ND License Version 2.0. Table of Contents Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Who is this Book for? 1 Book of Vaadin PDF Version 2 Supplementary Material 2 Getting Support 3 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.1. Core concepts 6 1.2. Why Vaadin? 7 2. Developing Vaadin Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.1. Development Toolchain 9 2.2. Starters and Maven Archetypes 13 2.3. Exploring the Project 15 2.4. Running and Debugging 17 3. Understanding Vaadin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 3.1. Vaadin Architecture 19 3.2. Building UIs with Components 21 3.3. Routing and Navigation 24 3.4. How Vaadin Components Work 25 4. Using Vaadin Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.1. Form Input Fields 29 4.2. Visualization and Interaction 41 4.3. Data Components 48 4.4. Layouts 52 4.5. Installing the Components 57 4.6. Vaadin Component Directory 58 5. Grid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 5.1. Binding to Data 59 5.2. Handling Selection Changes 60 5.3. Handling Item-click Events 65 5.4. Configuring Columns 66 5.5. Using Renderers in Columns 73 5.6. Enabling Expanding Rows 82 5.7. Column Sorting 83 5.8. Styling the Grid 89 6. Binding Data to Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 6.1. Binding Data to Forms 95 6.2. Validating and Converting User Input 98 6.3. Loading From and Saving To Business Objects 107 6.4. Binding Beans to Forms 112 6.5. Showing a List of Data with Data Providers 118 6.6. Creating a Component that Has a Value 137 7. Routing and Navigation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 7.1. Using the @Route Annotation 150 7.2. Navigation Lifecycle 151 7.3. Router Layouts and Nested Router Targets 158 7.4. Routing and URL Parameters 162 7.5. URL Generation 166 7.6. Navigating Between Routes 168 7.7. Preserving the State on Refresh 170 7.8. Router Exception Handling 173 7.9. Getting Registered Routes 179 7.10. Updating the Page Title During Navigation 180 7.11. Registering Routes Dynamically 182 8. Browser Features and Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 8.1. Browser Window Resize Events 192 8.2. Executing JavaScript in the Browser 192 9. Embedding Vaadin Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 9.1. Introduction to Embedding Applications 194 9.2. Embedded Application Properties 197 9.3. Theming Embedded Applications 204 9.4. Securing Embedded Applications 205 9.5. Creating an Embedded Vaadin Application Tutorial 209 9.6. Embedding Applications in Compatibility and Production Mode 218 9.7. Configuring Push in Embedded Applications 220 9.8. Embedded Application Limitations 221 10. Theming and styling applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 10.1. Application Theming Basics 224 10.2. Integrating a Custom Component Theme 227 ii 10.3. Theming Web Components 230 10.4. Theming Overview 236 10.5. Using Component Themes 237 10.6. Theming Overlay Components 245 10.7. Migrating Theming Files from Polymer 2 to Polymer 3 248 11. Spring integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 11.1. Using Vaadin with Spring Boot 251 11.2. Using Vaadin with Spring MVC 254 11.3. Using Routing with Spring 257 11.4. Vaadin Spring Scopes 260 11.5. Vaadin Spring Configuration 264 11.6. Getting Started with Spring and Vaadin 266 12. CDI integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 12.1. Using Vaadin with CDI 268 12.2. Getting Started with CDI and Vaadin Tutorial 270 12.3. Using CDI Beans in Instantiated Components 270 12.4. Vaadin CDI Contexts 273 12.5. Observable Vaadin Events 281 12.6. Vaadin Service Interfaces as CDI Beans 283 12.7. Getting Started with CDI and Vaadin 284 13. Progressive Web Applications (PWA). . . . . . . . . . . . . . . . . . . . . . . 286 13.1. Introduction 286 13.2. Creating PWAs with Vaadin 287 13.3. PWA Application Icons 288 13.4. PWA Web App Manifest 290 13.5. PWA Service Worker 292 13.6. PWA Offline Page 294 14. Manipulating DOM with Element API. . . . . . . . . . . . . . . . . . . . . . . 296 14.1. Element Properties and Attributes 296 14.2. Listening to User Events Using the Element API 300 14.3. Remote Procedure Calls 302 14.4. Retrieving User Input Using the Element API 306 14.5. Dynamic Styling Using the Element API 307 14.6. Using the Shadow Root in Server-side Elements 310 15. Creating Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 iii 15.1. Creating Components Overview 313 15.2. Creating a Simple Component Using the Element API 314 15.3. Creating a Component with Multiple Elements 316 15.4. Using API Helpers to Define Component Properties 318 15.5. Creating a Component Using Existing Components 321 15.6. Extending Components 323 15.7. Using Events with Components 331 15.8. Creating a Component Container 339 15.9. Using Component Lifecycle Callbacks 343 15.10. Using Vaadin Mixin Interfaces 346 16. Integrating Web Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 16.1. What are Web Components? 351 16.2. Integrating a Web Component 353 16.3. Creating Java API for a Web Component 357 16.4. Debugging a Web Component Integration 369 16.5. Creating Another type of Add-on 371 16.6. Creating an In-project Web Component 371 17. Packaging for Production. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 17.1. Taking your Application into Production 374 17.2. Advanced production mode topics 377 17.3. How to Run and Deploy a Flow Application on Jetty 380 18. OSGi Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 18.1. Vaadin OSGi Support 389 18.2. Create OSGi compatible components 400 19. Migrating from Vaadin 8 to Vaadin 10. . . . . . . . . . . . . . . . . . . . . . 405 19.1. Migrating from Vaadin 8 to Vaadin platform 405 19.2. Migration Strategies 408 19.3. Differences Between Vaadin 10+ and V8 Applications 411 19.4. Routing and Navigation 414 19.5. Components in Vaadin platform 416 19.6. Themes and Theming Applications 430 19.7. Add-ons, Integrations and Tools 434 19.8. Migration example - Bookstore Starter 438 20. Migrating from Vaadin 10-13 to Vaadin 14. . . . . . . . . . . . . . . . . 455 20.1. App Layout 2 Migration Guide 455 iv 20.2. Migration Tool for Polymer Templates 458 20.3. Vaadin 14 Migration Guide 460 21. Vaadin Designer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481 21.1. Installation 482 21.2. Using Vaadin Designer 505 21.3. Tutorials 517 22. Vaadin Charts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 22.1. Overview 536 22.2. Installing Vaadin Charts for Flow 537 22.3. Basic Use 538 22.4. Chart Types 545 22.5. Chart Configuration 583 22.6. Chart Data 596 22.7. CSS Styling 605 22.8. Breaking Changes in Version 6 610 22.9. Timeline 614 23. Vaadin Testbench. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618 23.1. Overview 618 23.2. Getting Started 620 23.3. Installing Web Drivers 625 23.4. Creating Tests 627 23.5. Creating Maintainable Tests using Page Objects 630 23.6. Low Level Element Interactions 637 23.7. Taking and Comparing Screenshots 639 23.8. Advanced Testing Concepts 647 23.9. Making Tests Reliable 653 23.10. Behavior-Driven Development 657 23.11. Running Tests with Maven 659 23.12. Running Tests on a CI Server 663 23.13. Running Tests on Multiple Browsers in a Grid 668 23.14. Setting up your Own Test Grid 674 23.15. Migrating to Vaadin 10 677 24. Vaadin Multiplatform Runtime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680 24.1. Step by step migration guide 680 24.2. Configuration and advanced topics 680 v 24.3. Step-by-step migration guide 681 24.4. Configuration and advanced topics 715 25. Advanced Topics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734 25.1. Application Lifecycle 734 25.2. I18N localization 742 25.3. Modifying the bootstrap page 748 25.4. Changing Flow behavior with runtime configuration. 757 25.5. The Loading Indicator 761 25.6. Server Push Configuration 768 25.7. Asynchronous Updates 770 25.8. Creating Collaborative Views 773 25.9. Modifying how dependencies are loaded with DependencyFilters 776 25.10. VaadinServiceInitListener 778 25.11. Dynamic Content 780 25.12. History API 784 25.13. StreamReceiver for receiving incoming data stream 787 25.14. UIInitListener 787 25.15. Making a component add-on OSGi-compatible 788 25.16. All Vaadin properties 792 vi Preface This book provides an overview of Vaadin 14 (released in mid- 2019). It covers the topics that you encounter while developing applications with Vaadin. The book is a compilation of the most important documentation available at https://vaadin.com/docs. Detailed documentation about the individual classes, interfaces, and methods is available in the Vaadin API Reference at https://vaadin.com/api. Downloadable versions of the book, in various formats, are available at https://vaadin.com. These are easier to search than the printed book. The web edition also has additional technical content, such as code examples and additional sections that you may need when developing applications. The slightly abridged print edition is intended to be an introductory textbook to Vaadin that fits in your pocket. Who is this Book for? This book is aimed at software developers who use, or are considering using, Vaadin to develop web applications. The book assumes that you have some experience with programming in Java, but this is not essential. It is as easy to learn Java with Vaadin as it is with any other UI framework. Knowledge of desktop-oriented user interface (UI) frameworks for Java, such as AWT, Swing, or SWT, or libraries such as Qt for C++, is also useful, but is not necessary, to understand the scope of Vaadin, the event-driven programming model, and other common concepts of UI frameworks. Basic HTML and CSS knowledge can help you when developing client-side components and presentation themes 1 for your application, but it is also not required to understand the concepts in this book. Book of Vaadin PDF Version This book is available as hard copy and PDF. You can download the PDF version for free at vaadin.com/book. The PDF version contains all the content in the hard copy version plus more advanced topics. Some of the additional topics covered in PDF version are: • Creating Vaadin Components • Manipulating DOM with Element API • Integrating Web Components • Packaging applications for production • OSGi Support • Migrating from Vaadin 8 to Vaadin 10 • Migrating from Vaadin 10-13 to Vaadin 14 • Vaadin Designer • Vaadin Charts • Vaadin TestBench • Vaadin Multiplatform Runtime • Advanced Topics Supplementary Material The Vaadin website offers plenty of material to help you understand what Vaadin is, what you can do with it, and how 2