Change-Id: If9299da4415f3181d59b8384e5ac96f940bd5229tags/7.7.0.alpha1
@@ -20,11 +20,10 @@ attack] by injecting offensive JavaScript code in such components. See other | |||
sources for more information about cross-site scripting. | |||
Offensive code can easily be injected with [literal]#++<script>++# markup or in | |||
tag attributes as events, such as | |||
[parameter]#onLoad#.//// | |||
TODO Consider an example, Alice, Bob, | |||
etc. | |||
//// | |||
tag attributes as events, such as [parameter]#onLoad#. | |||
// TODO Consider an example, Alice, Bob, etc. | |||
Cross-site scripting vulnerabilities are browser dependent, depending on the | |||
situations in which different browsers execute scripting markup. | |||
@@ -50,7 +49,3 @@ and is not sanitized. As the entire purpose of the [classname]#RichTextArea# | |||
component is to allow input of formatted text, you can not just remove all HTML | |||
tags. Also many attributes, such as [parameter]#style#, should pass through the | |||
sanitization. | |||
@@ -209,7 +209,7 @@ The Ivy dependency is as follows: | |||
[subs="normal"] | |||
---- | |||
<dependency org="com.vaadin" name="vaadin-spring" | |||
rev="[replaceable]#latest.release#"/> | |||
rev="[replaceable]##latest.release##"/> | |||
---- | |||
The Maven dependency is as follows: | |||
@@ -218,17 +218,17 @@ The Maven dependency is as follows: | |||
<dependency> | |||
<groupId>com.vaadin</groupId> | |||
<artifactId>vaadin-spring</artifactId> | |||
<version>[replaceable]#LATEST#</version> | |||
<version>[replaceable]##LATEST##</version> | |||
</dependency> | |||
---- | |||
[[advanced.spring.peparing]] | |||
[[advanced.spring.preparing]] | |||
== Preparing Application for Spring | |||
A Vaadin application that uses Spring must have a file named | |||
[filename]#applicationContext.xml# in the [filename]#WEB-INF# directory. | |||
[subs="normal"] | |||
[subs="verbatim,replacements,quotes"] | |||
---- | |||
<?xml version="1.0" encoding="UTF-8"?> | |||
<beans xmlns="http://www.springframework.org/schema/beans" | |||
@@ -240,12 +240,10 @@ A Vaadin application that uses Spring must have a file named | |||
http://www.springframework.org/schema/context | |||
http://www.springframework.org/schema/context/spring-context-4.1.xsd"> | |||
//Configuration object | |||
<!-- Configuration object --> | |||
<bean class="[replaceable]#com.example.myapp.MySpringUI.MyConfiguration#" /> | |||
//Location for automatically scanned beans | |||
<!-- Location for automatically scanned beans --> | |||
<context:component-scan | |||
base-package="[replaceable]#com.example.myapp.domain#" /> | |||
</beans> | |||
@@ -395,7 +393,7 @@ navigator. | |||
public class MySpringUI extends UI { | |||
@Autowired | |||
SpringViewProvider viewProvider; | |||
@Override | |||
protected void init(VaadinRequest request) { | |||
Navigator navigator = new Navigator(this, this); | |||
@@ -498,25 +496,23 @@ If the list contains [parameter]#UI.class#, the view is available to all UIs. | |||
@SpringView(name="myview", uis={UI.class}) | |||
---- | |||
In the following, we have a login view that accesses a session-scoped user | |||
object. Here, we use a constant to define the view name, so that we can use the | |||
constant when navigating to it. | |||
[source, java] | |||
---- | |||
@SpringView(name=LoginView.NAME) | |||
public class LoginView extends CustomComponent | |||
implements View { | |||
public final static String NAME = ""; | |||
// Here we inject to the constructor and actually do | |||
// not store the injected object to use it later | |||
@Autowired | |||
public LoginView(User user) { | |||
VerticalLayout layout = new VerticalLayout(); | |||
// An input field for editing injected data | |||
BeanItem<User> item = new BeanItem<User>(user); | |||
TextField username = new TextField("User name", | |||
@@ -528,10 +524,10 @@ public class LoginView extends CustomComponent | |||
layout.addComponent(new Button("Login", e -> | |||
getUI().getNavigator(). | |||
navigateTo(MainView.VIEWNAME))); | |||
setCompositionRoot(layout); | |||
} | |||
@Override | |||
public void enter(ViewChangeEvent event) {} | |||
} | |||
@@ -539,13 +535,11 @@ public class LoginView extends CustomComponent | |||
You could now navigate to the view from any other view in the UI with: | |||
[source, java] | |||
---- | |||
getUI().getNavigator().navigateTo(LoginView.VIEWNAME); | |||
---- | |||
endif::web[] | |||
[[advanced.spring.accesscontrol]] | |||
@@ -664,7 +658,6 @@ default servlet as follows, and map the other servlets to other URL paths: | |||
---- | |||
<web-app> | |||
... | |||
<servlet> | |||
<servlet-name>Default</servlet-name> | |||
<servlet-class> | |||
@@ -674,23 +667,18 @@ default servlet as follows, and map the other servlets to other URL paths: | |||
<servlet-mapping> | |||
<servlet-name>Default</servlet-name> | |||
<url-pattern>[replaceable]#/myspringuis/*#</url-pattern> | |||
<url-pattern>[replaceable]##/myspringuis/*##</url-pattern> | |||
</servlet-mapping> | |||
<servlet-mapping> | |||
<servlet-name>Default</servlet-name> | |||
<url-pattern>/VAADIN/*</url-pattern> | |||
<url-pattern>/VAADIN/+++*+++</url-pattern> | |||
</servlet-mapping> | |||
</web-app> | |||
---- | |||
With such a setting, paths to Spring UIs would have base path | |||
[filename]#/myapp/myspringuis#, to which the (optional) UI path would be | |||
appended. The [filename]#/VAADIN/*# only needs to be mapped to the servlet if | |||
there are no other Vaadin servlets. | |||
With such a setting, paths to Spring UIs would have base path [filename]#/myapp/myspringuis#, to which the (optional) UI path would be appended. | |||
The [filename]#/VAADIN/*# only needs to be mapped to the servlet if there are no other Vaadin servlets. | |||
(((range="endofrange", startref="term.advanced.spring.springlong"))) | |||
(((range="endofrange", startref="term.advanced.spring.spring"))) | |||
@@ -35,7 +35,9 @@ a UI">>. | |||
Because of the special nature of AJAX applications, use of multiple windows uses | |||
require some | |||
caveats.//// | |||
caveats. | |||
//// | |||
TODO Re-enable We will go through them later in <xref | |||
linkend="advanced.windows.caveats"/>. | |||
//// | |||
@@ -71,7 +73,7 @@ public static class MyPopupUI extends UI { | |||
@Override | |||
protected void init(VaadinRequest request) { | |||
getPage().setTitle("Popup Window"); | |||
// Have some content for it | |||
VerticalLayout content = new VerticalLayout(); | |||
Label label = | |||
@@ -99,7 +101,7 @@ You can configure the features of the popup window with | |||
window features, as defined in the HTML specification. | |||
status=[parameter]#0|1#:: Whether the status bar at the bottom of the window should be enabled. | |||
[parameter]##:: | |||
[parameter]##:: | |||
scrollbars:: Enables scrollbars in the window if the document area is bigger than the view area of the window. | |||
resizable:: Allows the user to resize the browser window (no effect for tabs). | |||
menubar:: Enables the browser menu bar. | |||
@@ -174,7 +176,3 @@ public class MyPopup extends UI { | |||
} | |||
} | |||
---- | |||
@@ -120,37 +120,37 @@ Servlet 2.4 application. You simply specify the UI class with the | |||
[parameter]#UI# parameter for the [classname]#com.vaadin.server.VaadinServlet#. | |||
The servlet is then mapped to a URL path in a standard way for Java Servlets. | |||
[subs="normal"] | |||
[subs="verbatim,replacements,quotes"] | |||
---- | |||
<?xml version="1.0" encoding="UTF-8"?> | |||
<web-app | |||
id="WebApp_ID" version="2.4" | |||
xmlns="http://java.sun.com/xml/ns/j2ee" | |||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | |||
xmlns="http://java.sun.com/xml/ns/j2ee" | |||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | |||
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee | |||
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"> | |||
<servlet> | |||
<servlet-name>**myservlet**</servlet-name> | |||
<servlet-name>[replaceable]##myservlet##</servlet-name> | |||
<servlet-class> | |||
com.vaadin.server.VaadinServlet | |||
[replaceable]##com.vaadin.server.VaadinServlet## | |||
</servlet-class> | |||
<init-param> | |||
<param-name>UI</param-name> | |||
<param-value>**com.ex.myprj.MyUI**</param-value> | |||
<param-value>[replaceable]##com.ex.myprj.MyUI##</param-value> | |||
</init-param> | |||
<!-- If not using the default widget set--> | |||
<init-param> | |||
<param-name>widgetset</param-name> | |||
<param-value>**com.ex.myprj.MyWidgetSet**</param-value> | |||
<param-value>[replaceable]##com.ex.myprj.MyWidgetSet##</param-value> | |||
</init-param> | |||
</servlet> | |||
<servlet-mapping> | |||
<servlet-name>**myservlet**</servlet-name> | |||
<url-pattern>/*</url-pattern> | |||
<servlet-name>[replaceable]##myservlet##</servlet-name> | |||
<url-pattern>[replaceable]##/*##</url-pattern> | |||
</servlet-mapping> | |||
</web-app> | |||
---- | |||
@@ -170,8 +170,8 @@ such as Servlet 3.0, you should use: | |||
---- | |||
<web-app | |||
id="WebApp_ID" version="**3.0**" | |||
xmlns="http://java.sun.com/xml/ns/j2ee" | |||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | |||
xmlns="http://java.sun.com/xml/ns/j2ee" | |||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | |||
xsi:schemaLocation="**http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd**"> | |||
---- | |||
Servlet 3.0 support is useful for at least server push. | |||
@@ -496,7 +496,3 @@ You can also access other [classname]#HttpSession# and | |||
[classname]#PortletSession# session properties through the interface, such as | |||
set and read session attributes that are shared by all servlets belonging to a | |||
particular servlet or portlet session. | |||
@@ -29,7 +29,7 @@ The result is shown in <<figure.application.errors.error-indicator>>. | |||
[[figure.application.errors.error-indicator]] | |||
.Error Indicator Active | |||
image::img/errorindicator-example2.png[] | |||
image::img/errorindicator-example2.png[scaledwidth=40%] | |||
[[application.errors.reconnect]] | |||
== Connection Fault | |||
@@ -101,7 +101,7 @@ as follows: | |||
---- | |||
getService().setSystemMessagesProvider( | |||
new SystemMessagesProvider() { | |||
@Override | |||
@Override | |||
public SystemMessages getSystemMessages( | |||
SystemMessagesInfo systemMessagesInfo) { | |||
CustomizedSystemMessages messages = | |||
@@ -124,7 +124,7 @@ endif::web[] | |||
ifdef::web[] | |||
[[application.errors.unchecked-exceptions]] | |||
== Handling Uncaught Exceptions | |||
== Handling Uncaught Exceptions | |||
Handling events can result in exceptions either in the application logic or in | |||
the framework itself, but some of them may not be caught properly by the | |||
@@ -150,7 +150,7 @@ behavior of the default handler. | |||
[source, java] | |||
---- | |||
// Here's some code that produces an uncaught exception | |||
// Here's some code that produces an uncaught exception | |||
final VerticalLayout layout = new VerticalLayout(); | |||
final Button button = new Button("Click Me!", | |||
new Button.ClickListener() { | |||
@@ -170,13 +170,13 @@ UI.getCurrent().setErrorHandler(new DefaultErrorHandler() { | |||
t = t.getCause()) | |||
if (t.getCause() == null) // We're at final cause | |||
cause += t.getClass().getName() + "<br/>"; | |||
// Display the error message in a custom fashion | |||
layout.addComponent(new Label(cause, ContentMode.HTML)); | |||
// Do the default error handling (optional) | |||
doDefault(event); | |||
} | |||
} | |||
}); | |||
---- | |||
@@ -191,6 +191,3 @@ thrown. See the source code of the implementation for more details. You can call | |||
error. If the error is not associated with a component, it returns null. | |||
endif::web[] | |||
@@ -1,271 +0,0 @@ | |||
[[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. | |||
@@ -1,100 +0,0 @@ | |||
//====================================================================== | |||
//Copyright 2000-2012 Vaadin Ltd | |||
//All Rights Reserved | |||
//This work is licensed under a Creative Commons Attribution-NoDerivs | |||
//License (CC-BY-ND) Version 3.0. Full license text is available at: | |||
//http://creativecommons.org/licenses/by-nd/3.0/legalcode | |||
//====================================================================== | |||
//The Doctype definition must be exactly same for book-pocket.pdf | |||
:experimental: true | |||
:source-highlighter: coderay | |||
Book of VaadinVaadin 7 Edition - 6th Revision | |||
MarkoGrönroos | |||
Tracy | |||
Translator | |||
Translation | |||
This book can be downloaded for free at | |||
http://vaadin.com/book | |||
Vaadin Ltd | |||
Vaadin Ltd | |||
Ruukinkatu 2-4 | |||
20540 | |||
Turku | |||
Finland | |||
2012-02-29Vaadin Framework | |||
Vaadin Framework | |||
7.4 | |||
Vaadin 7 Edition - 6th Revision | |||
Bookwell Oy | |||
Juva | |||
Finland | |||
2000-2015Vaadin Ltd | |||
All rights reserved. This work is licensed under the Creative Commons CC-BY-ND | |||
License Version 2.0. | |||
Vaadin is an AJAX web application development framework that enables | |||
developers to build high-quality user interfaces with Java, both on the | |||
server- and client-side. It provides a set of libraries of ready-to-use user | |||
interface components and a clean framework for creating your own | |||
components. The focus is on ease-of-use, re-usability, extensibility, and | |||
meeting the requirements of large enterprise applications. | |||
include::book-preface.asciidoc[] | |||
include::introduction/chapter-introduction.asciidoc[] | |||
include::getting-started/chapter-getting-started.asciidoc[] | |||
include::architecture/chapter-architecture.asciidoc[] | |||
include::application/chapter-application.asciidoc[] | |||
include::components/chapter-components.asciidoc[] | |||
include::layout/chapter-layout.asciidoc[] | |||
include::designer/chapter-designer.asciidoc[] | |||
include::themes/chapter-themes.asciidoc[] | |||
include::datamodel/chapter-datamodel.asciidoc[] | |||
include::sqlcontainer/chapter-sqlcontainer.asciidoc[] | |||
include::advanced/chapter-advanced.asciidoc[] | |||
include::portal/chapter-portal.asciidoc[] | |||
include::clientside/chapter-clientside.asciidoc[] | |||
include::clientsideapp/chapter-clientsideapp.asciidoc[] | |||
include::clientsidewidgets/chapter-clientsidewidgets.asciidoc[] | |||
include::gwt/chapter-gwt.asciidoc[] | |||
include::addons/chapter-addons.asciidoc[] | |||
include::charts/chapter-charts.asciidoc[] | |||
include::jpacontainer/chapter-jpacontainer.asciidoc[] | |||
include::mobile/chapter-mobile.asciidoc[] | |||
include::spreadsheet/chapter-spreadsheet.asciidoc[] | |||
include::testbench/chapter-testbench.asciidoc[] | |||
include::index.asciidoc[]//// | |||
Keep this comment at the end of the file Local variables: mode: xml sgml-omittag:nil sgml-shorttag:nil sgml-namecase-general:nil sgml-general-insert-case:lower sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:4 sgml-indent-data:t sgml-parent-document:nil sgml-exposed-tags:nil sgml-local-catalogs:("/etc/sgml/catalog" "/usr/share/xemacs21/xemacs-packages/etc/psgml-dtds/CATALOG") sgml-local-ecat-files:("ECAT" "~/sgml/ECAT" "/usr/share/sgml/ECAT" "/usr/local/share/sgml/ECAT" "/usr/local/lib/sgml/ECAT") End: | |||
//// |
@@ -16,9 +16,9 @@ compiler. | |||
As most Vaadin add-ons include widgets, widget set compilation is usually needed | |||
when using add-ons. In that case, the widget sets from different add-ons are | |||
compiled into a __project widget set__, as described in | |||
<<dummy/../../../framework/addons/addons-overview.asciidoc#addons.overview,"Using | |||
Vaadin | |||
Add-ons">>.//// | |||
<<dummy/../../../framework/addons/addons-overview.asciidoc#addons.overview,"Using Vaadin Add-ons">>. | |||
//// | |||
TODO Provide a link to a proper add-on compilation section when one is | |||
available. | |||
//// | |||
@@ -76,6 +76,3 @@ follows: | |||
---- | |||
[prompt]#$# [command]#mvn# [parameter]#vaadin:compile# | |||
---- | |||
@@ -64,13 +64,10 @@ can be loaded to any web page, as described in | |||
<<dummy/../../../framework/clientsideapp/clientsideapp-loading#clientsideapp.loading,"Loading | |||
a Client-Side Application">>. | |||
// TODO What is this? What's an "UI Binder"? | |||
The client-side user interface can be built declaratively using the included | |||
__UI | |||
Binder__//// | |||
, as described in <xref | |||
linkend="clientsideapp.uibinder"/> | |||
//// | |||
. | |||
__UI Binder__. | |||
// , as described in <<clientsideapp.uibinder>>. | |||
The servlet for processing RPC calls from the client-side can be generated | |||
automatically using the included compiler. | |||
@@ -79,12 +76,9 @@ Even with regular server-side Vaadin applications, it may be useful to provide | |||
an off-line mode if the connection is closed. An off-line mode can persist data | |||
in a local store in the browser, thereby avoiding the need for server-side | |||
storage, and transmit the data to the server when the connection is again | |||
available. Such a pattern is commonly used with Vaadin | |||
TouchKit.//// | |||
Use of a client-side application to provide an off-line mode is described in | |||
<xref | |||
linkend="clientsideapp.offline"/>. | |||
//// | |||
available. Such a pattern is commonly used with Vaadin TouchKit. | |||
//// | |||
TODO It may be necessary to have such a section at some point. | |||
Use of a client-side application to provide an off-line mode is described in <<clientsideapp.offline>>. | |||
//// |
@@ -210,7 +210,7 @@ Calendar calendar = new Calendar("Bound Calendar"); | |||
// Use a container of built-in BasicEvents | |||
final BeanItemContainer<BasicEvent> container = | |||
new BeanItemContainer<BasicEvent>(BasicEvent.class); | |||
new BeanItemContainer<BasicEvent>(BasicEvent.class); | |||
// Create a meeting in the container | |||
container.addBean(new BasicEvent("The Event", "Single Event", | |||
@@ -308,7 +308,7 @@ ContainerEventProvider cep = | |||
// Set the container as the data source | |||
calendar.setEventProvider(cep); | |||
// Now we can add events to the database through the calendar | |||
BasicEvent event = new BasicEvent("The Event", "Single Event", | |||
new GregorianCalendar(2012,1,15,12,00).getTime(), | |||
@@ -414,7 +414,7 @@ public class BasicEvent | |||
EventChangeListener listener) { | |||
... | |||
} | |||
public void removeListener(EventChangeListener listener) { | |||
... | |||
} | |||
@@ -660,10 +660,10 @@ private Calendar createDDCalendar() { | |||
Calendar calendar = new Calendar(); | |||
calendar.setDropHandler(new DropHandler() { | |||
public void drop(DragAndDropEvent event) { | |||
CalendarTargetDetails details = | |||
CalendarTargetDetails details = | |||
(CalendarTargetDetails) event.getTargetDetails(); | |||
TableTransferable transferable = | |||
TableTransferable transferable = | |||
(TableTransferable) event.getTransferable(); | |||
createEvent(details, transferable); | |||
@@ -877,15 +877,12 @@ endif::web[] | |||
Vaadin Calendar has only limited built-in navigation support. The weekly view | |||
has navigation buttons in the top left and top right | |||
corners.//// | |||
TODO See the figure | |||
4. | |||
//// | |||
corners. | |||
// TODO See the figure 4. | |||
You can handle backward and forward navigation with a | |||
[interfacename]#BackwardListener# and [interfacename]#ForwardListener#. | |||
[source, java] | |||
---- | |||
cal.setHandler(new BasicBackwardHandler() { | |||
@@ -894,7 +891,7 @@ cal.setHandler(new BasicBackwardHandler() { | |||
java.util.Calendar calendar = event.getComponent() | |||
.getInternalCalendar(); | |||
if (isThisYear(calendar, end) | |||
if (isThisYear(calendar, end) | |||
&& isThisYear(calendar, start)) { | |||
super.setDates(event, start, end); | |||
} | |||
@@ -923,7 +920,7 @@ the week view clicking on a day switches to the day view. | |||
calendar.setHandler(new BasicDateClickHandler() { | |||
public void dateClick(DateClickEvent event) { | |||
Calendar cal = event.getComponent(); | |||
// Check if the current range is already one day long | |||
long currentCalDateRange = cal.getEndDate().getTime() - | |||
cal.getStartDate().getTime(); | |||
@@ -977,7 +974,7 @@ cal.setHandler(new BasicWeekClickHandler() { | |||
Date start, Date end) { | |||
java.util.Calendar calendar = event.getComponent() | |||
.getInternalCalendar(); | |||
if (isThisMonth(calendar, start) | |||
if (isThisMonth(calendar, start) | |||
&& isThisMonth(calendar, end)) { | |||
super.setDates(event, start, end); | |||
} | |||
@@ -1039,7 +1036,7 @@ cal.setHandler(new BasicEventMoveHandler() { | |||
javaCalendar = event.getComponent().getInternalCalendar(); | |||
super.eventMove(event); | |||
} | |||
protected void setDates(CalendarEventEditor event, | |||
Date start, Date end) { | |||
if (isThisMonth(javaCalendar, start) | |||
@@ -1082,7 +1079,7 @@ public static class MyEventProvider | |||
events.add(BasicEvent); | |||
} | |||
public List<CalendarEvent> getEvents(Date startDate, | |||
public List<CalendarEvent> getEvents(Date startDate, | |||
Date endDate) { | |||
return events; | |||
} | |||
@@ -1129,9 +1126,9 @@ cal.setHandler(new RangeSelectHandler() { | |||
final Window w = new Window(null, layout); | |||
... | |||
// Wrap the calendar event to a BeanItem | |||
// Wrap the calendar event to a BeanItem | |||
// and pass it to the form | |||
final BeanItem<CalendarEvent> item = | |||
final BeanItem<CalendarEvent> item = | |||
new BeanItem<CalendarEvent>(myEvent); | |||
final Form form = new Form(); | |||
@@ -1181,7 +1178,7 @@ resize will just be corrected by the server. | |||
cal.setHandler(new BasicEventResizeHandler() { | |||
private static final long twelveHoursInMs = 12*60*60*1000; | |||
protected void setDates(CalendarEventEditor event, | |||
protected void setDates(CalendarEventEditor event, | |||
Date start, Date end) { | |||
long eventLength = end.getTime() - start.getTime(); | |||
if (eventLength <= twelveHoursInMs) { | |||
@@ -1192,6 +1189,3 @@ cal.setHandler(new BasicEventResizeHandler() { | |||
---- | |||
endif::web[] | |||
@@ -168,7 +168,7 @@ Components are always enabled by default. You can disable a component with | |||
Button enabled = new Button("Enabled"); | |||
enabled.setEnabled(true); // The default | |||
layout.addComponent(enabled); | |||
Button disabled = new Button("Disabled"); | |||
disabled.setEnabled(false); | |||
layout.addComponent(disabled); | |||
@@ -242,7 +242,7 @@ image is provided as a resource, perhaps most typically a | |||
TextField name = new TextField("Name"); | |||
name.setIcon(new ThemeResource("icons/user.png")); | |||
layout.addComponent(name); | |||
// Component with an icon from another theme ('runo') | |||
Button ok = new Button("OK"); | |||
ok.setIcon(new ThemeResource("../runo/icons/16/ok.png")); | |||
@@ -297,11 +297,11 @@ You can set the locale of a component (or the application) with | |||
---- | |||
// Component for which the locale is meaningful | |||
InlineDateField date = new InlineDateField("Datum"); | |||
// German language specified with ISO 639-1 language | |||
// code and ISO 3166-1 alpha-2 country code. | |||
// code and ISO 3166-1 alpha-2 country code. | |||
date.setLocale(new Locale("de", "DE")); | |||
date.setResolution(Resolution.DAY); | |||
layout.addComponent(date); | |||
---- | |||
@@ -357,7 +357,7 @@ get the localized resource right when the component is created. | |||
ResourceBundle bundle = | |||
ResourceBundle.getBundle(MyAppCaptions.class.getName(), | |||
UI.getCurrent().getLocale()); | |||
// Get a localized resource from the bundle | |||
Button cancel = | |||
new Button(bundle.getString(MyAppCaptions.CancelKey)); | |||
@@ -381,10 +381,10 @@ in Java. | |||
// The locale in which we want to have the language | |||
// selection list | |||
Locale displayLocale = Locale.ENGLISH; | |||
// All known locales | |||
final Locale[] locales = Locale.getAvailableLocales(); | |||
// Allow selecting a language. We are in a constructor of a | |||
// CustomComponent, so preselecting the current | |||
// language of the application can not be done before | |||
@@ -401,7 +401,7 @@ for (int i=0; i<locales.length; i++) { | |||
select.addItem(locales[i]); | |||
select.setItemCaption(locales[i], | |||
locales[i].getDisplayName(displayLocale)); | |||
// Automatically select the current locale | |||
if (locales[i].equals(getLocale())) | |||
select.setValue(locales[i]); | |||
@@ -417,7 +417,7 @@ final InlineDateField date = | |||
new InlineDateField("Calendar in the selected language"); | |||
date.setResolution(Resolution.DAY); | |||
layout.addComponent(date); | |||
// Handle language selection | |||
select.addValueChangeListener(new Property.ValueChangeListener() { | |||
public void valueChange(ValueChangeEvent event) { | |||
@@ -457,7 +457,7 @@ TextField readwrite = new TextField("Read-Write"); | |||
readwrite.setValue("You can change this"); | |||
readwrite.setReadOnly(false); // The default | |||
layout.addComponent(readwrite); | |||
TextField readonly = new TextField("Read-Only"); | |||
readonly.setValue("You can't touch this!"); | |||
readonly.setReadOnly(true); | |||
@@ -497,10 +497,11 @@ read-only component can accept some other variable changes from the client-side | |||
and some of such changes could be acceptable, such as change in the scroll bar | |||
position of a [classname]#Table#. Custom widgets should check the read-only | |||
state for variables bound to business | |||
data.//// | |||
TODO: Note this also in the Advanced: Security section and possibly also in the | |||
GWT | |||
chapter. | |||
data. | |||
//// | |||
TODO: Note this also in the Advanced: Security section. | |||
Possibly also in the GWT chapter. | |||
//// | |||
=== CSS Style Rules | |||
@@ -750,8 +751,3 @@ For example, the following would make a text field blue when it has focus. | |||
background: lightblue; | |||
} | |||
---- | |||
@@ -323,10 +323,8 @@ kbd:[Enter]. You need to enable the mode with [methodname]#setNewItemsAllowed(tr | |||
Setting the component also in immediate mode may be necessary, as otherwise the | |||
item would not be added immediately when the user interacts with the component, | |||
but after some other component causes a server | |||
request.//// | |||
TODO This could be a | |||
bug | |||
//// | |||
request. | |||
// TODO This could be a bug | |||
[source, java] |
@@ -1 +0,0 @@ | |||
== Index |
@@ -3,10 +3,8 @@ | |||
((("JPAContainer", id="term.jpacontainer", range="startofrange"))) | |||
This chapter describes the use of the Vaadin JPAContainer add-on. | |||
include::jpacontainer-overview.asciidoc[leveloffset=+2] | |||
include::jpacontainer-installation.asciidoc[leveloffset=+2] |
@@ -26,20 +26,13 @@ The generated defaults are as follows: | |||
|=============== | |||
The field factory is recusive, so that you can edit a complex object tree with | |||
one form. | |||
The field factory is recursive, so that you can edit a complex object tree with one form. | |||
[[jpacontainer.fieldfactory.configuring]] | |||
== Configuring the Field Factory | |||
The [classname]#FieldFactory# is highly configurable with various configuration | |||
settings and by | |||
extending.//// | |||
You need to make the configuration | |||
before | |||
//// | |||
The [classname]#FieldFactory# is highly configurable with various configuration settings and by extending. | |||
// You need to make the configuration before ... | |||
The [methodname]#setMultiSelectType()# and [methodname]#setSingleSelectType()# | |||
allow you to specify a selection component that is used instead of the default | |||
@@ -93,7 +86,7 @@ countrySelect.addValueChangeListener(new ValueChangeListener(){ | |||
// Get the item to edit in the form | |||
Item countryItem = | |||
countries.getItem(event.getProperty().getValue()); | |||
// Use a JPAContainer field factory | |||
// - no configuration is needed here | |||
final FieldFactory fieldFactory = new FieldFactory(); | |||
@@ -102,7 +95,7 @@ countrySelect.addValueChangeListener(new ValueChangeListener(){ | |||
// Edit the item in the form | |||
countryForm.setItemDataSource(countryItem); | |||
countryForm.setEnabled(true); | |||
// Handle saves on the form | |||
final Button save = new Button("Save"); | |||
countryForm.getFooter().removeAllComponents(); | |||
@@ -156,7 +149,3 @@ automatically. As shown in the example in | |||
<<figure.jpacontainer.fieldfactory.using>>, the factory creates a | |||
[classname]#MasterDetailEditor# for all properties with a | |||
[literal]#++@OneToMany++# or an [literal]#++@ElementCollection++# annotation. | |||
@@ -1,6 +1,11 @@ | |||
[[layout]] | |||
== Managing Layout | |||
//// | |||
TODO The intro text below is now completely hidden, as this text is | |||
not visible in web edition and all the text is web-conditional. | |||
//// | |||
ifdef::web[] | |||
Ever since the ancient xeroxians invented graphical user interfaces, programmers | |||
have wanted to make GUI programming ever easier for themselves. Solutions | |||
@@ -43,16 +48,17 @@ presentations, such as books and most web pages. Real applications, however, | |||
need to have more control. They need to be able to change the state of user | |||
interface components and even their layout on the run. This creates a need to | |||
separate the presentation from content on exactly the right | |||
level.//// | |||
level. | |||
//// | |||
Vaadin provides a solution for this, using themes and CSS, but let us first look | |||
at what Java did for UI | |||
programming. | |||
at what Java did for UI programming. | |||
//// | |||
//// | |||
Changing the layout steps right on the feet of the graphics designers, so we | |||
have a conflict. We will discuss this conflict later, but let us first look at | |||
what Java did for UI | |||
programming. | |||
what Java did for UI programming. | |||
//// | |||
endif::web[] | |||
@@ -29,7 +29,7 @@ component: | |||
[source, java] | |||
---- | |||
CssLayout layout = new CssLayout(); | |||
// Component with a layout-managed caption and icon | |||
TextField tf = new TextField("A TextField"); | |||
tf.setIcon(new ThemeResource("icons/user.png")); | |||
@@ -39,7 +39,7 @@ layout.addComponent(tf); | |||
Label label = new Label("A Label"); | |||
label.setWidth(Sizeable.SIZE_UNDEFINED, 0); | |||
layout.addComponent(label); | |||
layout.addComponent(new Button("A Button")); | |||
---- | |||
@@ -120,19 +120,14 @@ logic behind the other layout components is there to give nice default behaviour | |||
and to handle the differences in different browsers. Some browsers, no need to | |||
say which, are notoriously incompatible with the CSS standards, so they require | |||
a lot of custom CSS. You may need to make use of the browser-specific style | |||
classes in the root element of the | |||
application.//// | |||
TODO: described in <xref | |||
linkend="advanced.browserinfo"/> | |||
//// | |||
classes in the root element of the application. | |||
// TODO: ... described in <<advanced.browserinfo>> | |||
Some features in the other layouts are not even solvable in pure CSS, at least | |||
in all browsers. | |||
[[layout.csslayout.css]] | |||
== Styling with CSS | |||
[source, css] | |||
---- | |||
.v-csslayout {} | |||
@@ -148,7 +143,6 @@ enabled. The components are contained in an element with | |||
For example, we could style the basic [classname]#CssLayout# example shown | |||
earlier as follows: | |||
[source, css] | |||
---- | |||
/* Have the caption right of the text box, bottom-aligned */ | |||
@@ -178,7 +172,3 @@ at the same level as the actual component elements. This may cause problems with | |||
wrapping in [literal]#++inline-block++# mode, as wrapping can occur between the | |||
caption and its corresponding component element just as well as between | |||
components. Such use case is therefore not feasible. | |||
@@ -20,7 +20,6 @@ changes to the UI itself, but only the following: | |||
[options="compact"] | |||
* Application packaged as a WAR | |||
[options="compact"] | |||
** [filename]#WEB-INF/portlet.xml# descriptor | |||
** [filename]#WEB-INF/liferay-portlet.xml# descriptor for Liferay | |||
@@ -29,23 +28,17 @@ changes to the UI itself, but only the following: | |||
** [filename]#WEB-INF/liferay-plugin-package.properties# for Liferay | |||
* Widget set installed to portal (optional) | |||
* Themes installed to portal (optional) | |||
* Vaadin libraries installed to portal (optional) | |||
* Portal configuration settings (optional) | |||
The Vaadin Plugin for Eclipse creates these files for you, when you create a | |||
portlet project as described in | |||
<<dummy/../../../framework/portal/portal-eclipse#portal.eclipse,"Creating a | |||
Generic Portlet in Eclipse">>. | |||
Installing the widget set and themes to the portal is required for running two | |||
or more Vaadin portlets simultaneously in a single portal page. As this | |||
situation occurs quite easily, we recommend installing them in any case. | |||
Instructions for Liferay are given in | |||
<<dummy/../../../framework/portal/portal-liferay#portal.liferay,"Developing | |||
Vaadin Portlets for Liferay">> and the procedure is similar for other portals. | |||
portlet project as described in <<portal-eclipse#portal.eclipse,"Creating a Generic Portlet in Eclipse">>. | |||
Installing the widget set and themes to the portal is required for running two or more Vaadin portlets simultaneously in a single portal page. | |||
As this situation occurs quite easily, we recommend installing them in any case. | |||
Instructions for Liferay are given in <<portal-liferay#portal.liferay,"Developing Vaadin Portlets for Liferay">> and the procedure is similar for other portals. | |||
In addition to the Vaadin libraries, you will need to have the | |||
[filename]#portlet.jar# in your project classpath. However, notice that you must | |||
@@ -59,13 +52,11 @@ javax.portlet.Portlet++#". | |||
[[portal.deployment.descriptor]] | |||
== Portlet Deployment Descriptor | |||
The portlet WAR must include a portlet descriptor located at | |||
[filename]#WEB-INF/portlet.xml#. A portlet definition includes the portlet name, | |||
mapping to a servlet, modes supported by the portlet, and other configuration. | |||
Below is an example of a simple portlet definition in [filename]#portlet.xml# | |||
descriptor. | |||
The portlet WAR must include a portlet descriptor located at [filename]#WEB-INF/portlet.xml#. | |||
A portlet definition includes the portlet name, mapping to a servlet, modes supported by the portlet, and other configuration. | |||
Below is an example of a simple portlet definition in [filename]#portlet.xml# descriptor. | |||
[subs="normal"] | |||
[subs="verbatim,replacements,quotes"] | |||
---- | |||
<?xml version="1.0" encoding="UTF-8" standalone="no"?> | |||
<portlet-app | |||
@@ -77,8 +68,8 @@ descriptor. | |||
http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"> | |||
<portlet> | |||
<portlet-name>**Portlet Example portlet**</portlet-name> | |||
<display-name>**Vaadin Portlet Example**</display-name> | |||
<portlet-name>[replaceable]##Portlet Example portlet##</portlet-name> | |||
<display-name>[replaceable]##Vaadin Portlet Example##</display-name> | |||
<!-- Map portlet to a servlet. --> | |||
<portlet-class> | |||
@@ -88,7 +79,7 @@ descriptor. | |||
<name>UI</name> | |||
<!-- The application class with package name. --> | |||
<value>**com.example.myportlet.MyportletUI**</value> | |||
<value>[replaceable]##com.example.myportlet.MyportletUI##</value> | |||
</init-param> | |||
<!-- Supported portlet modes and content types. --> | |||
@@ -101,23 +92,21 @@ descriptor. | |||
<!-- Not always required but Liferay requires these. --> | |||
<portlet-info> | |||
<title>**Vaadin Portlet Example**</title> | |||
<short-title>**Portlet Example**</short-title> | |||
<title>[replaceable]##Vaadin Portlet Example##</title> | |||
<short-title>[replaceable]##Portlet Example##</short-title> | |||
</portlet-info> | |||
</portlet> | |||
</portlet-app> | |||
---- | |||
Listing supported portlet modes in [filename]#portlet.xml# enables the | |||
corresponding portlet controls in the portal user interface that allow changing | |||
the mode, as described later. | |||
The mode definitions enable the corresponding portlet controls in the portal. | |||
The portlet controls allow changing the mode of the portlet, as described later. | |||
[[portal.deployment.liferay]] | |||
== Liferay Portlet Descriptor | |||
((("Liferay", "portlet descriptor", id="term.portal.liferay.descriptor.liferay-portlet.liferay", range="startofrange"))) | |||
Liferay requires a special [filename]#liferay-portlet.xml# descriptor file that | |||
defines Liferay-specific parameters. Especially, Vaadin portlets must be defined | |||
as " __instanceable__", but not " __ajaxable__". | |||
@@ -135,7 +124,7 @@ Below is an example descriptor for the earlier portlet example: | |||
<portlet> | |||
<!-- Matches definition in portlet.xml. --> | |||
<!-- Note: Must not be the same as servlet name. --> | |||
<portlet-name>**Portlet Example portlet**</portlet-name> | |||
<portlet-name>[replaceable]##Portlet Example portlet##</portlet-name> | |||
<instanceable>true</instanceable> | |||
<ajaxable>false</ajaxable> | |||
@@ -181,7 +170,7 @@ Vaadin portlets under the "Vaadin" category, as shown in | |||
[[figure.portal.liferay.descriptor.display]] | |||
.Portlet Categories in Add Application Window | |||
image::img/liferay-display-hi.png[] | |||
image::img/liferay-display-hi.png[width=60%] | |||
See Liferay documentation for further details on how to configure the categories | |||
in the [filename]#liferay-display.xml# deployment descriptor. | |||
@@ -203,16 +192,16 @@ settings for the portlet, most importantly the Vaadin JAR to be used. | |||
[subs="normal"] | |||
---- | |||
name=**Portlet Example portlet** | |||
short-description=**myportlet** | |||
module-group-id=**Vaadin** | |||
name=[replaceable]##Portlet Example portlet## | |||
short-description=[replaceable]##myportlet## | |||
module-group-id=[replaceable]##Vaadin## | |||
module-incremental-version=1 | |||
#change-log= | |||
#page-uri= | |||
#author= | |||
license=Proprietary | |||
portal-dependency-jars=\ | |||
**vaadin.jar** | |||
[replaceable]##vaadin.jar## | |||
---- | |||
[parameter]#name#:: The plugin name must match the portlet name. | |||
@@ -299,7 +288,3 @@ installation directory. The deployment depends on the application server under | |||
which Liferay runs; for example, if you use Liferay bundled with Tomcat, you | |||
will find the extracted package in the [filename]#webapps# directory under the | |||
Tomcat installation directory included in Liferay. | |||
@@ -10,8 +10,7 @@ layout: page | |||
Custom themes are placed in the [filename]#VAADIN/themes# folder of the web | |||
application, in an Eclipse project under the [filename]#WebContent# folder or | |||
[filename]#src/main/webapp# in Maven projects, as was illustrated in | |||
<<dummy/../../../framework/themes/themes-overview#figure.themes.theme-contents,"Contents | |||
of a Theme">>. This location is fixed. You need to have a theme folder for each | |||
<<themes-overview#figure.themes.theme-contents,"Contents of a Theme">>. This location is fixed. You need to have a theme folder for each | |||
theme you use in your application, although applications rarely need more than a | |||
single theme. | |||
@@ -21,8 +20,7 @@ single theme. | |||
You can use Sass themes in Vaadin in two ways, either by compiling them to CSS | |||
by yourself or by letting the Vaadin servlet compile them for you on-the-fly | |||
when the theme CSS is requested by the browser, as described in | |||
<<dummy/../../../framework/themes/themes-compiling#themes.compiling,"Compiling | |||
Sass Themes">>. | |||
<<themes-compiling#themes.compiling,"Compiling Sass Themes">>. | |||
To define a Sass theme with the name mytheme, you must place a file with name | |||
[filename]#styles.scss# in the theme folder [filename]#VAADIN/themes/mytheme#. | |||
@@ -152,13 +150,11 @@ returns only the custom stylenames, not the built-in stylenames for the | |||
component. | |||
Please see the section on each component for a description of its styles. Most | |||
of the stylenames are determined in the client-side widget of each component. | |||
of the style names are determined in the client-side widget of each component. | |||
The easiest way to find out the styles of the elements is to use a HTML | |||
inspector such as | |||
FireBug.//// | |||
TODO reference to a Firebug section when | |||
available | |||
//// | |||
inspector such as FireBug. | |||
//TODO add reference to a Firebug section when available | |||
Some client-side components or component styles can be shared by different | |||
server-side components. For example, [literal]#++v-textfield++# style is used | |||
@@ -194,10 +190,10 @@ style names for specific components. | |||
public class MyUI extends UI { | |||
@Override | |||
protected void init(VaadinRequest request) { | |||
... | |||
... | |||
Panel panel = new Panel("Regular Panel in the Runo Theme"); | |||
panel.addComponent(new Button("Regular Runo Button")); | |||
// A button with the "small" style | |||
Button smallButton = new Button("Small Runo Button"); | |||
smallButton.addStyleName(Runo.BUTTON_SMALL); | |||
@@ -277,7 +273,3 @@ add-ons contain a theme for the components they provide. | |||
The add-on themes need to be included in the project theme. Vaadin Plugin for | |||
Eclipse and Maven automatically include them in the [filename]#addons.scss# file | |||
in the project theme folder. It should be included by the project theme. | |||
@@ -9,7 +9,6 @@ layout: page | |||
((("CSS", "introduction", id="term.themes.css", range="startofrange"))) | |||
Cascading Style Sheets or CSS is the basic technique to separate the appearance | |||
of a web page from the content represented in HTML. In this section, we give an | |||
introduction to CSS and look how they are relevant to software development with | |||
@@ -58,8 +57,8 @@ even though they use somewhat different elements to draw the user interface. | |||
The HTML elements that will be styled later by matching CSS rules are emphasized | |||
above. | |||
The [literal]#++<link>++# element in the HTML header defines the used CSS | |||
stylesheet. The definition is automatically generated by Vaadin in the HTML page | |||
The [elementname]#link# element in the HTML header defines the CSS stylesheet. | |||
The definition is automatically generated by Vaadin in the HTML page | |||
that loads the UI of the application. A stylesheet can also be embedded in the | |||
HTML document itself, as is done when optimizing their loading in Vaadin | |||
TouchKit, for example. | |||
@@ -77,25 +76,23 @@ value, separated with a colon. A property statement ends with a semicolon. | |||
Let us look at an example that matches certain elements in the simple HTML | |||
document given in the previous section: | |||
[source, css] | |||
---- | |||
p, td { | |||
p, td { | |||
color: blue; | |||
} | |||
td { | |||
td { | |||
background: yellow; | |||
font-weight: bold; | |||
} | |||
---- | |||
The [literal]#++p++# and [literal]#++td++# are element type selectors that match | |||
with [literal]#++<p>++# and [literal]#++<td>++# elements in HTML, respectively. | |||
with [elementname]#p# and [elementname]#td# elements in HTML, respectively. | |||
The first rule matches with both elements, while the second matches only with | |||
[literal]#++<td>++# elements. Let us assume that you have saved the above style | |||
sheet with the name [filename]#mystylesheet.css# and consider the following HTML | |||
file located in the same folder. | |||
[elementname]#td# elements. | |||
Let us assume that you have saved the above style sheet with the name [filename]#mystylesheet.css# and consider the following HTML file located in the same folder. | |||
[[figure.themes.basic.1]] | |||
.Simple Styling by Element Type | |||
@@ -108,7 +105,6 @@ CSS has __inheritance__ where contained elements inherit the properties of their | |||
parent elements. For example, let us change the above example and define it | |||
instead as follows: | |||
[source, css] | |||
---- | |||
table { | |||
@@ -117,27 +113,25 @@ table { | |||
} | |||
---- | |||
All elements contained in the [literal]#++<table>++# element would have the same | |||
properties. For example, the text in the contained [literal]#++<td>++# elements | |||
would be in blue color. | |||
All elements contained in the [elementname]#table# element would have the same properties. | |||
For example, the text in the contained [elementname]#td# elements would be in blue color. | |||
[[themes.css.basics.element-types]] | |||
=== HTML Element Types | |||
HTML has a number of element types, each of which accepts a specific set of | |||
properties. The [literal]#++<div>++# elements are generic elements that can be | |||
properties. The [elementname]#div# elements are generic elements that can be | |||
used to create almost any layout and formatting that can be created with a | |||
specific HTML element type. Vaadin uses [literal]#++<div>++# elements | |||
specific HTML element type. Vaadin uses [elementname]#div# elements | |||
extensively to draw the UI, especially in layout components. | |||
((("Google Web Toolkit", | |||
"themeing"))) | |||
((("Google Web Toolkit", "themeing"))) | |||
Matching elements by their type as shown above is, however, rarely if ever used | |||
in style sheets for Vaadin applications. We used it above, because it is the | |||
normal way in regular HTML documents that use the various HTML elements for | |||
formatting text, but it is not applicable in Vaadin UIs that consist mostly of | |||
[literal]#++<div>++# elements. Instead, you need to match by element class, as | |||
[elementname]#div# elements. Instead, you need to match by element class, as | |||
described next. | |||
@@ -169,6 +163,7 @@ follows: | |||
</body> | |||
</html> | |||
---- | |||
The class attributes of HTML elements can be matched in CSS rules with a | |||
selector notation where the class name is written after a period following the | |||
element name. This gives us full control of matching elements by their type and | |||
@@ -217,11 +212,9 @@ image::img/themes-css-match-class-3.png[] | |||
To ensure future compatibility, we recommend that you use only matching based on | |||
the classes and __do not__ match for specific HTML element types in CSS rules, | |||
because Vaadin may change the exact HTML implementation how components are drawn | |||
in the future. For example, Vaadin earlier used [literal]#++<div>++# element to | |||
draw [classname]#Button# components, but later it was changed to use the | |||
special-purpose [literal]#++<button>++# element in HTML. Because of using the | |||
[literal]#++v-button++# style class in the CSS rules for the button, styling it | |||
has changed only very little. | |||
in the future. | |||
For example, Vaadin earlier used [elementname]#div# element to draw [classname]#Button# components, but later it was changed to use the special-purpose [elementname]#button# element in HTML. | |||
Because of using the [literal]#++v-button++# style class in the CSS rules for the button, styling it has changed only very little. | |||
[[themes.css.matching-by-descendants]] | |||
@@ -243,10 +236,8 @@ consider the following HTML fragment: | |||
</table> | |||
</body> | |||
---- | |||
Matching by the class name [literal]#++.mytext++# alone would match both the | |||
[literal]#++<p>++# and [literal]#++<td>++# elements. If we want to match only | |||
the table cell, we could use the following selector: | |||
Matching by the class name [literal]#++.mytext++# alone would match both the [elementname]#p# and [elementname]#td# elements. | |||
If we want to match only the table cell, we could use the following selector: | |||
[source, css] | |||
---- | |||
@@ -375,7 +366,7 @@ public class HelloWorld extends UI { | |||
// Label has v-label style | |||
content.addComponent(new Label("Hello World!")); | |||
// Button has v-button style | |||
content.addComponent(new Button("Push Me!", | |||
new Button.ClickListener() { | |||
@@ -444,7 +435,7 @@ elements. The theme is actually a Sass theme. | |||
.v-ui { | |||
background: white; | |||
} | |||
/* All labels have white text on black background */ | |||
.v-label { | |||
background: black; | |||
@@ -502,5 +493,3 @@ Compatibility issues are detailed in various CSS handbooks. | |||
(((range="endofrange", startref="term.themes.css"))) | |||