diff options
14 files changed, 194 insertions, 251 deletions
diff --git a/documentation/application/application-declarative.asciidoc b/documentation/application/application-declarative.asciidoc index 3e6fea7633..b741cf1cab 100644 --- a/documentation/application/application-declarative.asciidoc +++ b/documentation/application/application-declarative.asciidoc @@ -29,7 +29,6 @@ See the http://demo.vaadin.com/book-examples-vaadin7/book#layout.orderedlayout.b You could define it declaractively with the following equivalent design: - [source, html] ---- <vaadin-vertical-layout> @@ -38,7 +37,9 @@ You could define it declaractively with the following equivalent design: <vaadin-text-field caption="Postal code"/> </vaadin-vertical-layout> ---- +ifdef::web[] See the http://demo.vaadin.com/book-examples-vaadin7/book#layout.orderedlayout.basic[on-line example, window="_blank"]. +endif::web[] Declarative designs can be crafted by hand, but are most conveniently created with the Vaadin Designer. @@ -52,7 +53,7 @@ handling user interaction events. A design is an HTML document with custom elements for representing components and their configuration. A design has a single root component inside the HTML -body element. Enclosing [literal]#++<html>++#, [literal]#++<head>++#, +body element. Enclosing [literal]#++<html>++#, [literal]#++<head>++#, and [literal]#++<body>++# are optional, but necessary if you need to make namespace definitions for custom components. Other regular HTML elements may not be used in the file, except inside components that specifically accept HTML content. @@ -61,7 +62,6 @@ In a design, each nested element corresponds to a Vaadin component in a component tree. Components can have explicitly given IDs to enable binding them to variables in the Java code, as well as optional attributes. - [source, html] ---- <!DOCTYPE html> @@ -69,13 +69,14 @@ to variables in the Java code, as well as optional attributes. <body> <vaadin-vertical-layout size-full> <!-- Label with HTML content --> - <vaadin-label><b>Hello!</b> - How are you?</vaadin-label> + <vaadin-label><b>Hello!</b> - + How are you?</vaadin-label> <vaadin-horizontal-layout size-full :expand> - <vaadin-tree _id="mytree" caption="My Tree" - width-auto height-full/> - <vaadin-table _id="mytable" caption="My Table" - size-full :expand/> + <vaadin-tree _id="mytree" caption="My Tree" + width-auto height-full/> + <vaadin-table _id="mytable" caption="My Table" + size-full :expand/> </vaadin-horizontal-layout> </vaadin-vertical-layout> </body> @@ -95,15 +96,11 @@ Hierarchical UI">>. [[application.declarative.elements]] == Component Elements -HTML elements of the declarative syntax are directly mapped to Vaadin components -according to their Java class names. The tag of a component element has a -namespace prefix separated by a dash. Vaadin core components, which are defined -in the [package]#com.vaadin.ui# package, have [literal]#++vaadin-++# prefix. The rest -of an element tag is determined from the Java class name of the component, by -making it lower-case, while adding a dash ( [literal]#++-++#) before every -previously upper-case letter as a word separator. For example, -[classname]#ComboBox# component has declarative element tag -[literal]#++<vaadin-combo-box>++#. +HTML elements of the declarative syntax are directly mapped to Vaadin components according to their Java class names. +The tag of a component element has a namespace prefix separated by a dash. +Vaadin core components, which are defined in the [package]#com.vaadin.ui# package, have [literal]#++vaadin-++# prefix. +The rest of an element tag is determined from the Java class name of the component, by making it lower-case, while adding a dash (`-`) before every previously upper-case letter as a word separator. +For example, [classname]#ComboBox# component has declarative element tag [vaadinelement]#vaadin-combo-box#. [[application.declarative.elements.prefix]] === Component Prefix to Package Mapping @@ -113,15 +110,14 @@ composite components, and add-on components. To do so, you need to define a mapping from an element prefix to the Java package of the component. The prefix is used as a sort of a namespace. -The mappings are defined in [literal]#++<meta name="package-mapping" ...>++# +The mappings are defined in `<meta name="package-mapping" ...>` elements in the HTML head. A [parameter]#content# attribute defines a mapping, in notation with a prefix separated from the corresponding Java package name -with a colon, such as " [literal]#++my:com.example.myapp++#". +with a colon, such as `my:com.example.myapp`. For example, consider that you have the following composite class [classname]#com.example.myapp.ExampleComponent#: - [source, java] ---- package com.example.myapp; @@ -140,12 +136,14 @@ You would make the package prefix mapping and then use the component as follows: <!DOCTYPE html> <html> <head> - **<meta name="package-mapping" content="my:com.example.myapp" />** + **<meta name="package-mapping" + content="my:com.example.myapp" />** </head> <body> <vaadin-vertical-layout> - <vaadin-label><b>Hello!</b> - How are you?</vaadin-label> + <vaadin-label><b>Hello!</b> - + How are you?</vaadin-label> <!-- Use it here --> **<my-example-component/>** @@ -221,12 +219,9 @@ Some attribute names are given by a shorthand. For example, you would set with [methodname]#setAlternateText()#, is given as the [literal]#++alt++# attribute. -Boolean values must be either " [literal]#++true++#" or " [literal]#++false++#". -The value can be omitted, in which case [literal]#++true++# is assumed. For -example, the [literal]#++enabled++# attribute is boolean and has default value " -[literal]#++true++#", so [literal]#++enabled="true"++# and -[literal]#++enabled++# and equivalent. - +Boolean values must be either `true` or `false`. +The value can be omitted, in which case `true` is assumed. +For example, the [literal]#++enabled++# attribute is boolean and has default value "`true`", so `enabled="true"` and `enabled` and equivalent. [source, html] ---- @@ -317,7 +312,7 @@ For example, the following class could be used to bind the design given earlier. public class MyViewDesign extends VerticalLayout { Tree mytree; Table mytable; - + public MyViewDesign() { Design.read("MyDeclarativeUI.html", this); @@ -326,7 +321,7 @@ public class MyViewDesign extends VerticalLayout { TreeExample.createTreeContent()); mytable.setContainerDataSource( TableExample.generateContent()); - + // Some interaction mytree.addItemClickListener(event -> // Java 8 Notification.show("Selected " + @@ -391,8 +386,3 @@ navigator.addView(MAINVIEW, new MainView()); See <<dummy/../../../framework/advanced/advanced-navigator#advanced.navigator.urifragment,"Handling URI Fragment Path">> for a complete example. - - - - - diff --git a/documentation/application/application-environment.asciidoc b/documentation/application/application-environment.asciidoc index 8907222a24..0322c77e4a 100644 --- a/documentation/application/application-environment.asciidoc +++ b/documentation/application/application-environment.asciidoc @@ -25,9 +25,9 @@ that form an application. Such a Java web application is typically packaged as a WAR package for deployment. Server-side Vaadin UIs run as servlets within such a Java web application. There exists also other kinds of web applications. To avoid confusion with the general meaning of "web application", we often refer to -Java web applications with the slight misnomer "WAR" in this book.//TODO Vaadin -7: What is the relationship between servlet and -application? +Java web applications with the slight misnomer "WAR" in this book. + +// TODO Vaadin 7: What is the relationship between servlet and application? [[application.environment.war-eclipse]] == Creating Deployable WAR in Eclipse @@ -35,41 +35,34 @@ application? To deploy an application to a web server, you need to create a WAR package. Here we give the instructions for Eclipse. -. Select "File > Export" and then "Web > WAR File". Or, right-click the project in -the Project Explorer and select "Web > WAR File". +. Select "File > Export" and then "Web > WAR File". Or, right-click the project in the Project Explorer and select "Web > WAR File". -. Select the [guilabel]#Web project# to export. Enter [guilabel]#Destination# file -name ( [filename]#.war#). +. Select the [guilabel]#Web project# to export. Enter [guilabel]#Destination# file name ([filename]#.war#). . Make any other settings in the dialog, and click [guibutton]#Finish#. - - [[application.environment.war]] == Web Application Contents The following files are required in a web application in order to run it. -[filename]#WEB-INF/web.xml# (optional with Servlet 3.0):: This is the web application descriptor that defines how the application is -organized, that is, what servlets and such it has. You can refer to any Java -book about the contents of this file. It is not needed if you define the Vaadin -servlet with the [literal]#++@WebServlet++# annotation in Servlet API 3.0. - -[filename]#WEB-INF/lib/*.jar# :: These are the Vaadin libraries and their dependencies. They can be found in the -installation package or as loaded by a dependency management system such as -Maven or Ivy. - -Your UI classes:: You must include your UI classes either in a JAR file in [filename]#WEB-INF/lib# -or as classes in [filename]#WEB-INF/classes# - -Your own theme files (OPTIONAL):: If your application uses a special theme (look and feel), you must include it in -[filename]#VAADIN/themes/themename# directory. +[filename]#WEB-INF/web.xml# (optional with Servlet 3.0):: + his is the web application descriptor that defines how the application is rganized, that is, what servlets and such it has. +You can refer to any Java book about the contents of this file. +It is not needed if you define the Vaadin servlet with the [classname]#@WebServlet# annotation in Servlet API 3.0. -Widget sets (OPTIONAL):: If your application uses a project-specific widget set, it must be compiled in -the [filename]#VAADIN/widgetset/# directory. +[filename]#WEB-INF/lib/*.jar# :: +These are the Vaadin libraries and their dependencies. +They can be found in the installation package or as loaded by a dependency management system such as Maven or Ivy. +Your UI classes:: +You must include your UI classes either in a JAR file in [filename]#WEB-INF/lib# or as classes in [filename]#WEB-INF/classes# +Your own theme files (OPTIONAL):: +If your application uses a special theme (look and feel), you must include it in [filename]#VAADIN/themes/themename# directory. +Widget sets (OPTIONAL):: +If your application uses a project-specific widget set, it must be compiled in the [filename]#VAADIN/widgetset/# directory. [[application.environment.webservlet]] == Web Servlet Class diff --git a/documentation/architecture/architecture-overview.asciidoc b/documentation/architecture/architecture-overview.asciidoc index 4ff34c453c..9307b7b72c 100644 --- a/documentation/architecture/architecture-overview.asciidoc +++ b/documentation/architecture/architecture-overview.asciidoc @@ -63,7 +63,7 @@ User Interface Components/Widgets:: ((("component"))) ((("field"))) The user interface of a Vaadin application consists of components that are created and laid out by the application. Each server-side component has a -client-side counterpart, a " __widget__", by which it is rendered in the browser +client-side counterpart, a __widget__, by which it is rendered in the browser and with which the user interacts. The client-side widgets can also be used by client-side applications. The server-side components relay these events to the application logic. Field components that have a value, which the user can view @@ -155,8 +155,3 @@ run in the same servlet as the UI code, usually separated at least by a Java API, possibly as EJBs, or distributed to a remote back-end service. The data storage is usually distributed to a database management system, and is typically accessed through a persistence solution, such as JPA. - - - - - diff --git a/documentation/getting-started/getting-started-environment.asciidoc b/documentation/getting-started/getting-started-environment.asciidoc index 118742be38..457cf524ab 100644 --- a/documentation/getting-started/getting-started-environment.asciidoc +++ b/documentation/getting-started/getting-started-environment.asciidoc @@ -63,8 +63,6 @@ link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[http://w . Install the Java SDK by running the installer. The default options are fine. - - [[getting-started.environment.linux]] === Linux / UNIX @@ -83,12 +81,11 @@ link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[http://w . Decompress it under a suitable base directory, such as [filename]#/opt#. For example, for Java SDK, enter (either as root or with [command]#sudo# in Linux): - + [subs="normal"] ---- [prompt]#+++#+++# [command]#cd# [replaceable]#/opt# -[prompt]#+++#+++# [command]#sh# [replaceable]#(path-to-installation-package)/jdk-8u20-linux-x64.bin# +[prompt]#+++#+++# [command]#sh# [replaceable]##<path>##/jdk-[replaceable]##<version>##.bin ---- + and follow the instructions in the installer. @@ -99,10 +96,9 @@ installation directory. Also, include the [literal]#++$JAVA_HOME/bin++# in the Linux and using the Bash shell, you would add lines such as the following to the [filename]#.bashrc# or [filename]#.profile# script in your home directory: - + ---- -export JAVA_HOME=/opt/jdk1.8.0_20 +export JAVA_HOME=/opt/jdk1.8.0_31 export PATH=$PATH:$HOME/bin:$JAVA_HOME/bin ---- + @@ -117,8 +113,6 @@ window. Settings done in a [filename]#profile# file require that you log in into the system. You can, of course, also give the commands in the current shell. - - [[getting-started.environment.eclipse]] == Installing Eclipse IDE @@ -133,15 +127,15 @@ decompress the ZIP file by just double-clicking it and selecting "Extract all files" task from Windows compressed folder task. In our installation example, we use [filename]#C:\dev# as the target directory. - -Eclipse is now installed in [filename]#C:\dev\eclipse# and can be started from -there (by double clicking eclipse.exe). - +Eclipse is now installed in [filename]#C:\dev\eclipse#. +You can start it from there by double clicking [filename]#eclipse.exe#. === Linux / OS X / UNIX -We recommend that you install Eclipse manually in Linux and other UNIX variants -as follows. +We recommend that you install Eclipse manually in Linux and other UNIX variants. +They may have it available from a package repository, but using such an installation may cause problems with installing plug-ins. + +You can install Eclipse as follows: . Download Eclipse IDE for Java EE Developers from link:http://www.eclipse.org/downloads/[http://www.eclipse.org/downloads/] @@ -150,15 +144,14 @@ link:http://www.eclipse.org/downloads/[http://www.eclipse.org/downloads/] to make sure that there is no old Eclipse installation in the target directory. Installing a new version on top of an old one probably renders Eclipse unusable. -. Eclipse should normally be installed as a regular user, as this makes -installation of plugins easier. Eclipse also stores some user settings in the -installation directory. To install the package, enter: - - +. Eclipse should normally be installed as a regular user, which makes installation of plug-ins easier. +Eclipse also stores some user settings in the installation directory. ++ +To install the package, enter: + [subs="normal"] ---- -[prompt]#$# [command]#tar# zxf [replaceable]#(path-to-installation-package)/eclipse-jee-ganymede-SR2-linux-gtk.tar.gz# +[prompt]#$# [command]#tar# zxf [replaceable]##<path>##/eclipse-jee-[replaceable]##<version>##.tar.gz ---- + This will extract the package to a subdirectory with the name @@ -231,8 +224,3 @@ on an element and select [guilabel]#Inspect Element with Firebug# to inspect it. In addition to HTML tree, it also shows the CSS rules matching the element, which you can use for building themes. You can even edit the CSS styles live, to experiment with styling. - - - - - diff --git a/documentation/getting-started/getting-started-first-project.asciidoc b/documentation/getting-started/getting-started-first-project.asciidoc index cc8be595e1..8f2eff5a3c 100644 --- a/documentation/getting-started/getting-started-first-project.asciidoc +++ b/documentation/getting-started/getting-started-first-project.asciidoc @@ -164,7 +164,7 @@ project hierarchy shown in the Project Explorer is shown in [[figure.getting-started.first-project.exploring]] .A New Vaadin Project -image::img/myproject-ivy-created.png[] +image::img/myproject-ivy-created.png[scaledwidth=60%] The Vaadin libraries and other dependencies are managed by Ivy. Notice that the libraries are not stored under the project folder, even though they are listed @@ -361,7 +361,7 @@ server-side development. [[figure.getting-started.first-project.coding.import]] .Importing Classes Automatically -image::img/codingtips-automaticimports.png[] +image::img/codingtips-automaticimports.png[scaledwidth=80%] [[getting-started.first-project.server]] == Setting Up and Starting the Web Server @@ -377,22 +377,28 @@ directory. Follow the following steps: -. Switch to the Servers tab in the lower panel in Eclipse. List of servers should be empty after Eclipse is installed. Right-click on the empty area in the panel and select "New > Server". + +. Switch to the Servers tab in the lower panel in Eclipse. List of servers should be empty after Eclipse is installed. Right-click on the empty area in the panel and select "New > Server". ++ image::img/tomcat-startserver-1.png[] -. Select "Apache > Tomcat v8.0 Server" and set [guilabel]#Server's host name# as [literal]#++localhost++#, which should be the default. If you have only one Tomcat installed, [guilabel]#Server runtime# has only one choice. Click [guibutton]#Next#. + +. Select "Apache > Tomcat v7.0 Server" and set [guilabel]#Server's host name# as [literal]#++localhost++#, which should be the default. If you have only one Tomcat installed, [guilabel]#Server runtime# has only one choice. Click [guibutton]#Next#. ++ image::img/tomcat-startserver-2.png[] -. Add your project to the server by selecting it on the left and clicking [guibutton]#Add# to add it to the configured projects on the right. Click [guibutton]#Finish#. + +. Add your project to the server by selecting it on the left and clicking [guibutton]#Add# to add it to the configured projects on the right. Click [guibutton]#Finish#. ++ image::img/tomcat-startserver-3.png[] - -. The server and the project are now installed in Eclipse and are shown in the [guilabel]#Servers# tab. To start the server, right-click on the server and select Debug. To start the server in non-debug mode, select Start. + +. The server and the project are now installed in Eclipse and are shown in the [guilabel]#Servers# tab. +To start the server, right-click on the server and select [guilabel]#Debug#. +To start the server in non-debug mode, select [guilabel]#Start#. ++ image::img/tomcat-startserver-4.png[] -. The server starts and the WebContent directory of the project is published to the server on http://localhost:8080/myproject/. + +. The server starts and the WebContent directory of the project is published to the server on http://localhost:8080/myproject/. ++ image::img/tomcat-startserver-5.png[] [[getting-started.first-project.run]] @@ -410,13 +416,12 @@ margin bar of the source code window. For example, if you insert a breakpoint in the [methodname]#buttonClick()# method and click the [guibutton]#What is the time?# button, Eclipse will ask to switch to the Debug perspective. Debug perspective will show where the execution stopped at the breakpoint. You can -examine and change the state of the application. To continue execution, select -Resume from Run menu. +examine and change the state of the application. +To continue execution, select [guilabel]#Resume# from [guilabel]#Run# menu. .Debugging a Vaadin Application image::img/debuggingMyProject.png[] -Above, we described how to debug a server-side application. Debugging -client-side applications and widgets is described in -<<dummy/../../../framework/clientside/clientside-debugging#clientside.debugging,"Debugging -Client-Side Code">>. +Above, we described how to debug a server-side application. +Debugging client-side applications and widgets is described in +<<dummy/../../../framework/clientside/clientside-debugging#clientside.debugging,"Debugging Client-Side Code">>. diff --git a/documentation/getting-started/getting-started-idea.asciidoc b/documentation/getting-started/getting-started-idea.asciidoc index 4461d80656..c0961dc534 100644 --- a/documentation/getting-started/getting-started-idea.asciidoc +++ b/documentation/getting-started/getting-started-idea.asciidoc @@ -31,17 +31,14 @@ used application servers. In the following, we configure Apache Tomcat: . Download and extract Tomcat installation package to a local directory, as -instructed in -<<dummy/../../../framework/getting-started/getting-started-environment#getting-started.environment.tomcat,"Installing -Apache Tomcat">>. +instructed in <<dummy/../../../framework/getting-started/getting-started-environment#getting-started.environment.tomcat,"Installing Apache Tomcat">>. . Select "Configure > Settings". . Select "IDE Settings > Application Servers". -. Select "+ > Tomcat Server" to add a Tomcat server, or any of the other supported -servers. A WebSocket-enabled server, such as Glassfish or TomEE, is required for -server push. +. Click [guibutton]#+# and select [guilabel]#Tomcat Server# to add a Tomcat server, or any of the other supported servers. +A WebSocket-enabled server, such as Glassfish or TomEE, is required for server push. . In the Tomcat Server dialog, specify the home directory for the server. @@ -140,15 +137,16 @@ server using a run/debug configuration. . Select [menuchoice]#New Project# . In the [guilabel]#New Project# window, select [menuchoice]#Maven# - //<?dbfo-need height="8cm" ?> -. Enter a project name, location, and the Java SDK to be used for the project. -Vaadin requires at least Java 6. Click [guibutton]#Next#. +. Enter a project name, location, and the Java SDK to be used for the project. +Vaadin requires at least Java 6. + image::img/idea-maven-newproject-1.png[] - ++ +Click [guibutton]#Next#. //<?dbfo-need height="6cm" ?> + . Give a Maven [guilabel]#GroupID#, [guilabel]#ArtifactID#, and a [guilabel]#Version# for the project, or use the defaults. @@ -156,8 +154,8 @@ image::img/idea-maven-newproject-1.png[] image::img/idea-maven-newproject-2.png[] . Check [guilabel]#Create from archetype# - //<?dbfo-need height="6cm" ?> + . If the Vaadin archetype is not in the list, click [guibutton]#Add archetype#, enter [guilabel]#GroupId# [literal]#++com.vaadin++#, [guilabel]#ArtifactId# [literal]#++vaadin-archetype-application++#, and [guilabel]#Version# @@ -170,8 +168,8 @@ endif::web[] + Click [guibutton]#OK# in the dialog. - //<?dbfo-need height="8cm" ?> + . Select the [literal]#++com.vaadin:vaadin-archetype-application++#. ifdef::web[] @@ -181,17 +179,17 @@ endif::web[] + Click [guibutton]#Next#. - //<?dbfo-need height="8cm" ?> -. Review the general Maven settings and settings for the new project. You may need -to override the settings, especially if you are creating a Maven project for the -first time. Click [guibutton]#Finish#. + +. Review the general Maven settings and settings for the new project. +You may need to override the settings, especially if you are creating a Maven project for the first time. ifdef::web[] + image::img/idea-maven-newproject-5.png[] endif::web[] - ++ +Click [guibutton]#Finish#. Creating the Maven project takes some time as Maven fetches the dependencies. Once done, the project is created and the Maven POM is opened in the editor. @@ -226,11 +224,10 @@ launch a Vaadin Maven application on the light-weight Jetty web server. . Select "Run > Edit Configurations". -. Select "+ > Maven" to create a new Maven run/debug configuration. +. Click [guibutton]#+# and select menu:Maven[] to create a new Maven run/debug configuration. -. Enter a [guilabel]#Name# for the run configuration. For the [guilabel]#Command -line#, enter " [literal]#++package jetty:run++# to first compile and package the -project, and then launch Jetty to run it. +. Enter a [guilabel]#Name# for the run configuration. +For the [guilabel]#Command line#, enter "`package jetty:run`# to first compile and package the project, and then launch Jetty to run it. ifdef::web[] + @@ -253,8 +250,3 @@ Compiling the project takes some time on the first time, as it compiles the widget set and theme. Once the run console pane informs that Jetty Server has been started, you can open the browser at the default URL http://localhost:8080/. - - - - - diff --git a/documentation/getting-started/getting-started-maven.asciidoc b/documentation/getting-started/getting-started-maven.asciidoc index 3914e973aa..2845e92ab5 100644 --- a/documentation/getting-started/getting-started-maven.asciidoc +++ b/documentation/getting-started/getting-started-maven.asciidoc @@ -21,6 +21,10 @@ link:https://github.com/johndevs/gradle-vaadin-plugin[Gradle Vaadin Plugin]. Vaadin Plugin for Eclipse uses Ivy for resolving dependencies in Vaadin projects, and it should provide you with the basic Ivy configuration. +For an interactive guide, see the instructions at link:https://vaadin.com/maven[vaadin.com/maven]. +It automatically generates you the command to create a new project based on archetype selection. +It can also generate dependency declarations for Vaadin dependencies. + [[getting-started.maven.command-line]] == Working from Command-Line @@ -31,7 +35,7 @@ line): ---- [prompt]#$# [command]#mvn# archetype:generate \ -DarchetypeGroupId=com.vaadin \ - -DarchetypeArtifactId=[parameter]#vaadin-archetype-application# \ + -DarchetypeArtifactId=[replaceable]#vaadin-archetype-application# \ -DarchetypeVersion=[replaceable]#7.x.x# \ -DgroupId=[replaceable]#your.company# \ -DartifactId=[replaceable]#project-name# \ @@ -43,17 +47,32 @@ The parameters are as follows: [parameter]#archetypeGroupId#:: The group ID of the archetype is [literal]#++com.vaadin++# for Vaadin archetypes. -[parameter]#archetypeArtifactId#:: The archetype ID. Vaadin 7 currently supports -[literal]#++vaadin-archetype-application++# archetype for server-side -applications and [literal]#++vaadin-archetype-widget++# for client-side widget -development projects. - -+ -//TODO Vaadin 7: Not all these archetypes are supported -+ -//// -<itemizedlist> <listitem> <literal>vaadin-archetype-clean</literal> is a new project with a barebone skeleton for a regular Vaadin application. The <filename>pom.xml</filename> includes out-commented definitions for additional widgets. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-widget</literal> is a skeleton for a project with custom widgets. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-sample</literal> is also for a project with custom widgets, but the skeleton includes the Color Picker example used in <xref linkend="gwt"/>. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-addon</literal> is for Vaadin add-on projects. It packages the add-on so that it can be published in Vaadin Directory. The archetype is for server-side add-ons and does not include definitions needed for building a widget set. If your add-on includes or requires other than the widgets in the Vaadin core library, you need to copy the required definitions from a POM of a <literal>vaadin-archetype-clean</literal> project. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-touchkit</literal> is for projects using Vaadin TouchKit, described in <xref linkend="mobile"/>. Notice that this archetype uses the AGPL-licensed version of TouchKit, which requires that your project must also be licensed under the AGPL license. </listitem> </itemizedlist> -//// +[parameter]#archetypeArtifactId#:: The archetype ID. +Vaadin 7 currently supports the following archetypes: + +`vaadin-archetype-application`;; +A single-module project for simple applications. +Good for quick demos and trying out Vaadin. + +`vaadin-archetype-application-multimodule`;; +A complete Vaadin application development setup. +It features separate production and development profiles. + +`vaadin-archetype-application-example`;; +An example CRUD web application using multi-module project setup. + +`vaadin-archetype-widget`;; +A multi-module project for a new Vaadin add-on. +It has two modules: one for the add-on and another for a demo application. + +`vaadin-archetype-touchkit`;; +A mobile development starter project using Vaadin TouchKit. +See <<dummy/../../../touchkit/touchkit-overview#touchkit.overview,"Vaadin TouchKit">>. +Notice that this archetype uses the AGPL-licensed version of TouchKit, which requires that your project must also be licensed under the AGPL license. + +`vaadin-archetype-liferay-portlet`;; +A portlet development setup for the open-source Liferay portal. + [parameter]#archetypeVersion#:: Version of the archetype to use. This should be [literal]#++LATEST++# for normal Vaadin releases. For prerelease versions it should be the exact version number, such as [literal]#++7.5.3++#. @@ -82,7 +101,7 @@ created project structure is shown in [[figure.getting-started.maven.archetype.created]] .A New Vaadin Project with Maven -image::img/maven-project-created.png[] +image::img/maven-project-created.png[scaledwidth=60%] [[getting-started.maven.compiling]] @@ -129,5 +148,3 @@ Maven Project">>. (((range="endofrange", startref="term.maven.addons"))) (((range="endofrange", startref="term.maven.creating"))) - - diff --git a/documentation/getting-started/getting-started-package.asciidoc b/documentation/getting-started/getting-started-package.asciidoc index 4dbe735958..9dd7ec81be 100644 --- a/documentation/getting-started/getting-started-package.asciidoc +++ b/documentation/getting-started/getting-started-package.asciidoc @@ -7,9 +7,7 @@ layout: page [[getting-started.package]] = Vaadin Installation Package -While the recommended way to install Vaadin is to use the Eclipse plugin, one of -the other IDE plugins, or a dependency management system, such as Maven, Vaadin -is also available as a ZIP distribution package. +While the recommended way to create a Vaadin project and install the libraries is to use an IDE plugin or a dependency management system, such as Maven, Vaadin is also available as a ZIP distribution package. You can download the newest Vaadin installation package from the download page at http://vaadin.com/download/. Please use a ZIP decompression utility available @@ -18,23 +16,17 @@ in your operating system to extract the files from the ZIP package. [[getting-started.package.contents]] == Package Contents -[filename]#README.TXT#:: This Readme file gives simple instructions for installing Vaadin in your -project. +[filename]#README.TXT#:: This README file gives simple instructions for installing Vaadin in your project. -[filename]#release-notes.html#:: The Release Notes contain information about the new features in the particular -release, give upgrade instructions, describe compatibility, etc. Please open the -HTML file with a web browser. +[filename]#release-notes.html#:: The Release Notes contain information about the new features in the particular release, give upgrade instructions, describe compatibility, etc. +Please open the HTML file with a web browser. -[filename]#license.html#:: Apache License version 2.0. Please open the HTML file with a web browser. - -[filename]#lib#folder:: All dependency libraries required by Vaadin are contained within the -[filename]#lib# folder. - -[filename]#*.jar#:: Vaadin libraries, as described in -<<dummy/../../../framework/getting-started/getting-started-libraries#getting-started.libraries,"Overview -of Vaadin Libraries">>. +[filename]#license.html#:: Apache License version 2.0. +Please open the HTML file with a web browser. +[filename]#lib# folder:: All dependency libraries required by Vaadin are contained within the [filename]#lib# folder. +[filename]#*.jar#:: Vaadin libraries, as described in <<getting-started-libraries#getting-started.libraries,"Overview of Vaadin Libraries">>. [[getting-started.package.install]] @@ -58,8 +50,3 @@ organization, which depends on the development environment. * In Eclipse Dynamic Web Application projects: [filename]#WebContent/WEB-INF/lib#. * In Maven projects: [filename]#src/main/webapp/WEB-INF/lib#. - - - - - diff --git a/documentation/getting-started/img/myproject-created-annotated-hi.png b/documentation/getting-started/img/myproject-created-annotated-hi.png Binary files differindex c2d9a49221..6927b883ed 100644 --- a/documentation/getting-started/img/myproject-created-annotated-hi.png +++ b/documentation/getting-started/img/myproject-created-annotated-hi.png diff --git a/documentation/getting-started/original-drawings/myproject-created-annotated.svg b/documentation/getting-started/original-drawings/myproject-created-annotated.svg index b639c5f160..70fc378bdc 100644 --- a/documentation/getting-started/original-drawings/myproject-created-annotated.svg +++ b/documentation/getting-started/original-drawings/myproject-created-annotated.svg @@ -72,8 +72,8 @@ inkscape:pageopacity="0.0" inkscape:pageshadow="2" inkscape:zoom="1.4" - inkscape:cx="236.02753" - inkscape:cy="570.52264" + inkscape:cx="191.07987" + inkscape:cy="356.49384" inkscape:document-units="px" inkscape:current-layer="layer1" inkscape:window-width="1920" @@ -101,7 +101,7 @@ spacingy="5px" /> <sodipodi:guide orientation="1,0" - position="395,555" + position="385,100" id="guide11876" /> </sodipodi:namedview> <metadata @@ -122,10 +122,10 @@ id="layer1" transform="translate(0,-308.2677)"> <rect - style="color:#000000;fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:1.50000000000000000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" + style="color:#000000;fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:1.5;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" id="rect29725" - width="500" - height="460" + width="480" + height="455" x="95" y="164.09448" transform="translate(0,308.2677)" @@ -171,13 +171,13 @@ <text xml:space="preserve" style="font-size:14px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Helvetica LT Std;-inkscape-font-specification:Helvetica LT Std Light" - x="394.74399" + x="385" y="584.474" id="text13161" sodipodi:linespacing="125%"><tspan sodipodi:role="line" id="tspan13163" - x="394.74399" + x="385" y="584.474">The UI class skeleton</tspan></text> <g transform="translate(204.99999,-66.969547)" @@ -216,32 +216,32 @@ <path sodipodi:nodetypes="cccc" style="fill:none;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" - d="m 30,762.36218 10,-5 0,-20 10,-10" + d="m 25,762.36218 10,-5 0,-20 10,-10" id="path3804-2-3-46-9" inkscape:connector-curvature="0" /> <path sodipodi:nodetypes="cccc" style="fill:none;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" - d="m 30,692.36218 10,5 0,20 10,10" + d="m 25,692.36218 10,5 0,20 10,10" id="path3804-2-3-46" inkscape:connector-curvature="0" /> <path sodipodi:nodetypes="cc" style="fill:none;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" - d="m 50,419.09448 55,1e-5" + d="m 45,419.09448 60,1e-5" id="path3804-2-3" inkscape:connector-curvature="0" transform="translate(0,308.2677)" /> <path sodipodi:type="arc" - style="color:#000000;fill:#ffedd1;fill-opacity:1;stroke:#000000;stroke-width:2.74977946000000006;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" + style="color:#000000;fill:#ffedd1;fill-opacity:1;stroke:#000000;stroke-width:2.74977946;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" id="path3005-2-10-8" sodipodi:cx="25" sodipodi:cy="419.09448" sodipodi:rx="9.1659365" sodipodi:ry="9.1659365" - d="m 34.165936,419.09448 c 0,5.06221 -4.103729,9.16594 -9.165936,9.16594 -5.062207,0 -9.165936,-4.10373 -9.165936,-9.16594 0,-5.0622 4.103729,-9.16593 9.165936,-9.16593 5.062207,0 9.165936,4.10373 9.165936,9.16593 z" - transform="matrix(0.54549827,0,0,0.54549827,36.362543,498.74687)" /> + d="m 34.165936,419.09448 a 9.1659365,9.1659365 0 1 1 -18.331872,0 9.1659365,9.1659365 0 1 1 18.331872,0 z" + transform="matrix(0.54549827,0,0,0.54549827,31.362543,498.74687)" /> <path sodipodi:type="arc" style="color:#000000;fill:#ecf3ff;fill-opacity:1;stroke:#000000;stroke-width:2.74977946000000006;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" @@ -318,46 +318,46 @@ <text xml:space="preserve" style="font-size:14px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Helvetica LT Std;-inkscape-font-specification:Helvetica LT Std Light" - x="394.74399" + x="385" y="664.25208" id="text13161-0" sodipodi:linespacing="125%"><tspan sodipodi:role="line" id="tspan13163-0" - x="394.74399" + x="385" y="664.25208">The widget set</tspan></text> <text xml:space="preserve" style="font-size:14px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Helvetica LT Std;-inkscape-font-specification:Helvetica LT Std Light" - x="394.74399" + x="385" y="808.74548" id="text13161-0-4" sodipodi:linespacing="125%"><tspan sodipodi:role="line" id="tspan13163-0-8" - x="394.74399" + x="385" y="808.74548">The theme</tspan></text> <text xml:space="preserve" style="font-size:14px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Helvetica LT Std;-inkscape-font-specification:Helvetica LT Std Light" - x="393.75201" + x="385" y="901.34863" id="text13161-0-4-1" sodipodi:linespacing="125%"><tspan sodipodi:role="line" id="tspan13163-0-8-3" - x="393.75201" + x="385" y="901.34863">Maven project configuration</tspan></text> <text xml:space="preserve" style="font-size:14px;font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Helvetica LT Std;-inkscape-font-specification:Helvetica LT Std Light" - x="393.75201" + x="385" y="918.85156" id="text13161-0-4-4" sodipodi:linespacing="125%"><tspan sodipodi:role="line" id="tspan13163-0-8-2" - x="393.75201" + x="385" y="918.85156">Project README skeleton</tspan></text> </g> </svg> diff --git a/documentation/introduction/intro-eclipse.asciidoc b/documentation/introduction/intro-eclipse.asciidoc index b2fb127f7b..09a8c50570 100644 --- a/documentation/introduction/intro-eclipse.asciidoc +++ b/documentation/introduction/intro-eclipse.asciidoc @@ -9,32 +9,24 @@ layout: page While Vaadin is not bound to any specific IDE, and you can in fact easily use it without any IDE altogether, we provide special support for the Eclipse IDE, -which has become the most used environment for Java development. The support is -provided in the Vaadin Plugin for Eclipse, which helps you in: +which has become the most used environment for Java development. -* Creating new Vaadin projects +*_Vaadin Plug-in for Eclipse_* helps you in: -* Creating custom themes +* creating new Vaadin projects, -* Creating custom client-side widgets +* creating custom themes, -* Easily upgrading to a newer version of the Vaadin library +* creating custom client-side widgets, and +* easily upgrading to a newer version of the Vaadin library. -Using the Vaadin Plugin for Eclipse is the recommended way of installing Vaadin -for development. Downloading the installation package that contains the JARs or -defining Vaadin as a Maven dependency is also possible. - -Installing and updating the Eclipse plugin is covered in -<<dummy/../../../framework/getting-started/getting-started-eclipse#getting-started.eclipse,"Vaadin -Plugin for Eclipse">> and the creation of a new Vaadin project using the plugin -in -<<dummy/../../../framework/getting-started/getting-started-first-project#getting-started.first-project.creation,"Creating -the Project">>. See -<<dummy/../../../framework/themes/themes-eclipse#themes.eclipse,"Creating a -Theme in Eclipse">> and -<<dummy/../../../framework/gwt/gwt-eclipse#gwt.eclipse,"Starting It Simple With -Eclipse">> for instructions on using the different features of the plugin. - +Using the Vaadin plug-in for Eclipse is the recommended way of installing Vaadin for development. +Downloading the installation package that contains the JARs or defining Vaadin as a Maven dependency is also possible. +*_Vaadin Designer_* is a commercial Eclipse plug-in that enables visual editing of Vaadin UIs and composites. +See <<dummy/../../../designer/designer-overview#designer.overview, "Vaadin Designer">> for its complete reference. +Installation of the Eclipse plug-in is covered in <<dummy/../../../framework/getting-started/getting-started-eclipse#getting-started.eclipse,"Vaadin plug-in for Eclipse">>. +The creation of a new Vaadin project using the plug-in is covered in <<dummy/../../../framework/getting-started/getting-started-first-project#getting-started.first-project.creation,"Creating the Project">>. +See <<dummy/../../../framework/themes/themes-eclipse#themes.eclipse,"Creating a Theme in Eclipse">> and <<dummy/../../../framework/gwt/gwt-eclipse#gwt.eclipse,"Starting It Simple With Eclipse">> for instructions on using the different features of the plug-in. diff --git a/documentation/introduction/intro-goals.asciidoc b/documentation/introduction/intro-goals.asciidoc index 0972a998cf..e2173b0875 100644 --- a/documentation/introduction/intro-goals.asciidoc +++ b/documentation/introduction/intro-goals.asciidoc @@ -31,14 +31,13 @@ frameworks and ensuring that our implementation represents an ideal solution for its purpose without clutter or bloat. -== XML is not designed for programming - -The Web is inherently document-centered and very much bound to the declarative -presentation of user interfaces. While Vaadin allows for declarative designs of -views, layouts, and even entire UIs, the programmatic approach by building the -UIs from Java components frees the programmer from these limitations. To create -highly dynamic views, it is more natural to create them by programming. +== Choice between declarative and dynamic UIs +The Web is inherently document-centered and very much bound to the declarative presentation of user interfaces. +Vaadin allows for declarative designs of views, layouts, and even entire UIs. +Vaadin Designer enables creating such designs visually. +Nevertheless, the programmatic approach by building the UIs from Java components frees the programmer from its limitations. +To create highly dynamic views, it is more natural to create them by programming. == Tools should not limit your work @@ -47,7 +46,3 @@ some reason the user interface components do not support what you need to achieve, it must be easy to add new ones to your application. When you need to create new components, the role of the framework is critical: it makes it easy to create re-usable components that are easy to maintain. - - - - diff --git a/documentation/introduction/intro-walkthrough.asciidoc b/documentation/introduction/intro-walkthrough.asciidoc index 218e76b337..152817c0ed 100644 --- a/documentation/introduction/intro-walkthrough.asciidoc +++ b/documentation/introduction/intro-walkthrough.asciidoc @@ -8,8 +8,8 @@ layout: page = Example Application Walkthrough Let us follow the long tradition of first saying "Hello World!" when learning a -new programming framework. First, using the primary server-side API. - +new programming framework. +First, using the primary server-side API. [source, java] ---- @@ -29,7 +29,7 @@ public class HelloWorld extends UI { // Display the greeting content.addComponent(new Label("Hello World!")); - // Have a clickable button + // Have a clickable button content.addComponent(new Button("Push Me!", new ClickListener() { @Override @@ -77,7 +77,7 @@ The result of the Hello World application, when opened in a browser, is shown in [[figure.intro.walkthrough]] .Hello World Application -image::img/HelloWorld.png[] +image::img/HelloWorld.png[scaledwidth=70%] To run a program, you need to package it as a web application WAR package and deploy it to a server, as explained in @@ -106,6 +106,3 @@ to write client-side widgets, which you can then use from a server-side Vaadin application. For more information regarding client-side development, see <<dummy/../../../framework/clientside/clientside-overview.asciidoc#clientside.overview,"Client-Side Vaadin Development">>. - - - diff --git a/documentation/themes/themes-fonticon.asciidoc b/documentation/themes/themes-fonticon.asciidoc index 624220fa05..2335417daf 100644 --- a/documentation/themes/themes-fonticon.asciidoc +++ b/documentation/themes/themes-fonticon.asciidoc @@ -21,16 +21,14 @@ automatically enabled in the Valo theme. For other themes, you need to include it with the following line in your project theme, after importing the base theme: - ---- @include fonticons; ---- If you use other icon fonts, as described in <<themes.fonticon.custom>>, and the font is not loaded by a base theme, you need to load it with a -[literal]#++font++# mixin in Sass, as described in -<<dummy/../../../framework/themes/themes-fonts#themes.fonts.loading,"Loading -Local Fonts">>. +`font` mixin in Sass, as described in +<<themes-fonts#themes.fonts.loading,"Loading Local Fonts">>. [[themes.fonticon.using]] @@ -46,7 +44,7 @@ of all the icons included in the font. Most typically, you set a component icon as follows: - +[source, Java] ---- TextField name = new TextField("Name"); name.setIcon(FontAwesome.USER); @@ -73,7 +71,6 @@ As font icons are regular text, you can specify their color with the HTML elements that display icons in Vaadin have the [literal]#++v-icon++# style name. - ---- .v-icon { color: blue; @@ -84,14 +81,13 @@ If you use the font icon resources in other ways, such as in an [classname]#Image# component, the style name will be different. - [[themes.fonticon.html]] == Using Font icons in HTML You can use font icons in HTML code, such as in a [classname]#Label#, by generating the HTML to display the icon with the [methodname]#getHtml()# method. - +[source, Java] ---- Label label = new Label("I " + FontAwesome.HEART.getHtml() + " Vaadin", @@ -101,9 +97,9 @@ layout.addComponent(label); ---- See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.html[on-line example, window="_blank"]. -The HTML code has the [literal]#++v-icon++# style, which you can modify in CSS: - +The HTML code has the [stylename]#v-icon# style, which you can modify in CSS: +[source, css] ---- .redicon .v-icon { color: red; @@ -111,10 +107,11 @@ The HTML code has the [literal]#++v-icon++# style, which you can modify in CSS: ---- See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.html[on-line example, window="_blank"]. -The result is illustrated in <<figure.themes.fonticon.html>>, with the color +The result is illustrated in <<figure.themes.fonticon-html.label>>, with the color styling described next. -[[figure.themes.fonticon.html]] +// The ID may not end in ".html" +[[figure.themes.fonticon-html.label]] .Using Font Icons in Label image::img/fonticons-html.png[] @@ -126,7 +123,6 @@ to use the correct font family and then use the hex-formatted Unicode codepoint for the icon. See for example the implementation of the [methodname]#getHtml()# method in [classname]#FontAwesome#: - ---- @Override public String getHtml() { @@ -212,30 +208,30 @@ using a normal sans-serif font built-in in the browser. // Font icon definition with a single symbol public enum MyFontIcon implements FontIcon { EURO(0x20AC); - + private int codepoint; - + MyFontIcon(int codepoint) { this.codepoint = codepoint; } - + @Override public String getMIMEType() { throw new UnsupportedOperationException( FontIcon.class.getSimpleName() + " should not be used where a MIME type is needed."); } - + @Override public String getFontFamily() { return "sans-serif"; } - + @Override public int getCodepoint() { return codepoint; } - + @Override public String getHtml() { return "<span class=\"v-icon\" style=\"font-family: " + @@ -260,7 +256,3 @@ You could make the implementation a class as well, instead of an enumeration, to allow other ways to specify the icons. endif::web[] - - - - |
