vaadin-framework/documentation/book-preface.asciidoc

[[preface]]
[preface]
[]
== Preface

This book provides an overview of the Vaadin Framework and covers the most
important topics that you might encounter while developing applications with it.
A more detailed documentation of the individual classes, interfaces, and methods
is given in the Vaadin API Reference.

This edition mostly covers Vaadin Framework 7.5 released in 2015, as well as the
latest versions of Vaadin Pro Tools. In addition to updates in the core
framework, the Volume 1 includes a new chapter about the new Vaadin Designer
plugin for Eclipse. New add-ons, namely Vaadin Spreadsheet, Vaadin CDI, and
Vaadin Spring, which were released earlier this year, are documented in Volume
2.

Writing this manual is an ongoing work and it is rarely completely up-to-date
with the quick-evolving product. Some features may not be included in this book
yet. For the most current version, please see the on-line edition available at
http://vaadin.com/book. You can also find PDF and EPUB versions of the book
there. You may find the other versions more easily searchable than the printed
book. The index in the book is incomplete and will be expanded later. The web
edition also has some additional technical content, such as some example code
and additional sections that you may need when actually doing development. The
purpose of the slightly abridged print edition is more to be an introductionary
textbook to Vaadin, and still fit in your pocket.

Also, many Vaadin 7 features are showcased as mini-tutorials, which are
available in the Vaadin Wiki at https://vaadin.com/wiki/-/wiki/Main/Vaadin+7.

= Who is This Book For?

This book is intended for software developers who use, or are considering to
use, Vaadin to develop web applications.

The book assumes that you have some experience with programming in Java, but if
not, it is at least as easy to begin learning Java with Vaadin as with any other
UI framework. No knowledge of AJAX is needed as it is well hidden from the
developer.

You may have used some desktop-oriented user interface frameworks for Java, such
as AWT, Swing, or SWT, or a library such as Qt for C++. Such knowledge is useful
for understanding the scope of Vaadin, the event-driven programming model, and
other common concepts of UI frameworks, but not necessary.

If you do not have a web graphics designer at hand, knowing the basics of HTML
and CSS can help so that you can develop presentation themes for your
application. A brief introduction to CSS is provided. Knowledge of Google Web
Toolkit (GWT) may be useful if you develop or integrate new client-side
components.


= Organization of This Book

The Book of Vaadin gives an introduction to what Vaadin is and how you use it to
develop web applications.

Volume 1

<<dummy/../../../framework/introduction/introduction-overview.asciidoc#intro.overview,"Introduction">>:: The chapter gives an introduction to the application architecture supported by
Vaadin, the core design ideas behind the framework, and some historical
background.

<<dummy/../../../framework/getting-started/getting-started-overview.asciidoc#getting-started.overview,"Getting Started with Vaadin">>:: This chapter gives practical instructions for installing Vaadin and the
reference toolchain, including the Vaadin Plugin for Eclipse, how to run and
debug the demos, and how to create your own application project in the Eclipse
IDE.

<<dummy/../../../framework/architecture/architecture-overview.asciidoc#architecture.overview,"Architecture">>:: This chapter gives an introduction to the architecture of Vaadin and its major
technologies, including AJAX, Google Web Toolkit, and event-driven programming.

<<dummy/../../../framework/application/application-overview.asciidoc#application.overview,"Writing a Server-Side Web Application">>:: This chapter gives all the practical knowledge required for creating
applications with Vaadin, such as window management, application lifecycle,
deployment in a servlet container, and handling events, errors, and resources.

<<dummy/../../../framework/components/components-overview.asciidoc#components.overview,"User Interface Components">>:: This chapter gives the basic usage documentation for all the (non-layout) user
interface components in Vaadin and their most significant features. The
component sections include examples for using each component, as well as for
styling with CSS/Sass.

<<dummy/../../../framework/layout/layout-overview.asciidoc#layout.overview,"Managing Layout">>:: This chapter describes the layout components, which are used for managing the
layout of the user interface, just like in any desktop application frameworks.

<<dummy/../../../designer/designer-overview.asciidoc#designer.overview,"Vaadin Designer">>:: This chapter gives instructions for using Vaadin Designer, a visual tool for the
Eclipse IDE for creating composite designs, such as for UIs, views, or other
composites.



Volume 2:

<<dummy/../../../framework/themes/themes-overview.asciidoc#themes.overview,"Themes">>:: This chapter gives an introduction to Cascading Style Sheets (CSS) and Sass and
explains how you can use them to build custom visual themes for your
application.

<<dummy/../../../framework/datamodel/datamodel-overview.asciidoc#datamodel.overview,"Binding Components to Data">>:: This chapter gives an overview of the built-in data model of Vaadin, consisting
of properties, items, and containers.

<<dummy/../../../framework/sqlcontainer/sqlcontainer-overview.asciidoc#sqlcontainer.overview,"Vaadin SQLContainer">>:: This chapter gives documentation for the SQLContainer, which allows binding
Vaadin components to SQL queries.

<<dummy/../../../framework/advanced/advanced-overview.asciidoc#advanced.overview,"Advanced Web Application Topics">>:: This chapter provides many special topics that are commonly needed in
applications, such as opening new browser windows, embedding applications in
regular web pages, low-level management of resources, shortcut keys, debugging,
etc.

<<dummy/../../../framework/portal/portal-overview.asciidoc#portal.overview,"Portal Integration">>:: This chapter describes the development of Vaadin applications as portlets which
you can deploy to any portal supporting Java Portlet API 2.0 (JSR-286). The
chapter also describes the special support for Liferay and the Control Panel,
IPC, and WSRP add-ons.

<<dummy/../../../framework/clientside/clientside-overview.asciidoc#clientside.overview,"Client-Side Vaadin Development">>:: This chapter gives an introduction to creating and developing client-side
applications and widgets, including installation, compilation, and debugging.

<<dummy/../../../framework/clientsideapp/clientsideapp-overview.asciidoc#clientsideapp.overview,"Client-Side Applications">>:: This chapter describes how to develop client-side applications and how to
integrate them with a back-end service.

<<dummy/../../../framework/clientsidewidgets/clientsidewidgets-overview.asciidoc#clientsidewidgets.overview,"Client-Side Widgets">>:: This chapter describes the built-in widgets (client-side components) available
for client-side development. The built-in widgets include Google Web Toolkit
widgets as well as Vaadin widgets.

<<dummy/../../../framework/gwt/gwt-overview.asciidoc#gwt.overview,"Integrating with the Server-Side">>:: This chapter describes how to integrate client-side widgets with their
server-side counterparts for the purpose of creating new server-side components.
The chapter also covers integrating JavaScript components.



<<dummy/../../../framework/addons/addons-overview.asciidoc#addons.overview,"Using Vaadin Add-ons">>:: This chapter gives instructions for downloading and installing add-on components
from the Vaadin Directory.

<<dummy/../../../charts/charts-overview.asciidoc#charts.overview,"Vaadin Charts">>:: This chapter documents the use of the Vaadin Charts add-on component for
interactive charting with many diagram types. The add-on includes the Chart and
Timeline components.

<<dummy/../../../framework/jpacontainer/jpacontainer-overview.asciidoc#jpacontainer.overview,"Vaadin JPAContainer">>:: This chapter gives documentation of the JPAContainer add-on, which allows
binding Vaadin components directly to relational and other databases using Java
Persistence API (JPA).

<<dummy/../../../mobile/mobile-overview.asciidoc#mobile.overview,"Mobile Applications with TouchKit">>:: This chapter gives examples and reference documentation for using the Vaadin
TouchKit add-on for developing mobile applications.

<<dummy/../../../spreadsheet/spreadsheet-overview.asciidoc#spreadsheet.overview,"Vaadin Spreadsheet">>:: This chapter gives documentation of the Vaadin Spreadsheet add-on, which
provides a Microsoft Excel compatible spreadsheet component.

<<dummy/../../../testbench/testbench-overview.asciidoc#testbench.overview,"Vaadin TestBench">>:: This chapter gives the complete documentation of using the Vaadin TestBench tool
for recording and executing user interface regression tests of Vaadin
applications.




= Supplementary Material

The Vaadin websites offer plenty of material that can help you understand what
Vaadin is, what you can do with it, and how you can do it.

Demo Applications:: The most important demo application for Vaadin is the Sampler, which
demonstrates the use of all basic components and features. You can run it
on-line at http://demo.vaadin.com/ or download it as a WAR from the
link:http://vaadin.com/download/[Vaadin download page].

+
Most of the code examples in this book and many others can be found online at
http://demo.vaadin.com/book-examples-vaadin7/book/.

Cheat Sheet:: The two-page cheat sheet illustrates the basic relationship hierarchy of the
user interface and data binding classes and interfaces. You can download it at
http://vaadin.com/book.

Refcard:: The six-page DZone Refcard gives an overview to application development with
Vaadin. It includes a diagram of the user interface and data binding classes and
interfaces. You can find more information about it at
https://vaadin.com/refcard.

Address Book Tutorial:: The Address Book is a sample application accompanied with a tutorial that gives
detailed step-by-step instructions for creating a real-life web application with
Vaadin. You can find the tutorial from the product website.

Developer's Website:: Vaadin Developer's Site at http://dev.vaadin.com/ provides various online
resources, such as the ticket system, a development wiki, source repositories,
activity timeline, development milestones, and so on.

+
The wiki provides instructions for developers, especially for those who wish to
check-out and compile Vaadin itself from the source repository. The technical
articles deal with integration of Vaadin applications with various systems, such
as JSP, Maven, Spring, Hibernate, and portals. The wiki also provides answers to
Frequently Asked Questions.

Online Documentation:: You can read this book online at http://vaadin.com/book. Lots of additional
material, including technical HOWTOs, answers to Frequently Asked Questions and
other documentation is also available on link:http://dev.vaadin.com/[Vaadin
web-site].




= Support

Stuck with a problem? No need to lose your hair over it, the Vaadin Framework
developer community and the Vaadin company offer support to all of your needs.

Community Support Forum:: You can find the user and developer community forum at http://vaadin.com/forum.
Please use the forum to discuss any problems you might encounter, wishes for
features, and so on. The answer to your problems may already lie in the forum
archives, so searching the discussions is always the best way to begin.

Report Bugs:: If you have found a possible bug in Vaadin, the demo applications, or the
documentation, please report it by filing a ticket at the Vaadin developer's
site at http://dev.vaadin.com/. You may want to check the existing tickets
before filing a new one. You can make a ticket to make a request for a new
feature as well, or to suggest modifications to an existing feature.

Commercial Support:: Vaadin offers full commercial support and training services for the Vaadin
Framework and related products. Read more about the commercial products at
http://vaadin.com/pro for details.




= About the Author

Marko Grönroos is a professional writer and software developer working at Vaadin
Ltd in Turku, Finland. He has been involved in web application development since
1994 and has worked on several application development frameworks in C, C++, and
Java. He has been active in many open source software projects and holds an
M.Sc. degree in Computer Science from the University of Turku.


= Acknowledgements

Much of the book is the result of close work within the development team at
Vaadin Ltd. Joonas Lehtinen, CEO of Vaadin Ltd, wrote the first outline of the
book, which became the basis for the first two chapters. Since then, Marko
Grönroos has become the primary author and editor. The development team has
contributed several passages, answered numerous technical questions, reviewed
the manual, and made many corrections.

The contributors are (in rough chronological order):

[options="compact"]
* Joonas Lehtinen
* Jani Laakso
* Marko Grönroos
* Jouni Koivuviita
* Matti Tahvonen
* Artur Signell
* Marc Englund
* Henri Sara
* Jonatan Kronqvist
* Mikael Grankvist (TestBench)
* Teppo Kurki (SQLContainer)
* Tomi Virtanen (Calendar)
* Risto Yrjänä (Calendar)
* John Ahlroos (Timeline)
* Petter Holmström (JPAContainer)
* Leif Åstrand
* Guillermo Alvarez (Charts)


= About Vaadin Ltd

Vaadin Ltd is a Finnish software company specializing in the design and
development of Rich Internet Applications. The company offers planning,
implementation, and support services for the software projects of its customers,
as well as sub-contract software development. Vaadin Framework, previously known
as IT Mill Toolkit, is the flagship open source product of the company, for
which it provides commercial development and support services.