From 9c6831bab067ccdb47c3063f2e77d3c0e7fe3440 Mon Sep 17 00:00:00 2001 From: Pekka Hyvönen Date: Mon, 2 Jan 2017 13:40:48 +0200 Subject: Update documentation, BoV chapters 1 - 5.3 (#8085) * Update documentation chapters 1 - 5.3 Images and diagrams have not been updated, but unnecessary images have been removed. * Sync application declarative and architecture sections source code. Screenshot image is updated to match the source code. * Old datamodel image is removed. * Ivy install image is removed. * Remove unnecessary linking / reference --- .../architecture/architecture-client-side.asciidoc | 2 +- .../architecture/architecture-events.asciidoc | 36 +- .../architecture/architecture-overview.asciidoc | 2 +- .../architecture/architecture-technology.asciidoc | 36 +- documentation/architecture/img/datamodel.png | Bin 302313 -> 0 bytes .../clientside-arch.svg.2012_10_09_18_20_24.0.svg | 2879 -------------------- .../clientside-arch.svg.2012_10_12_17_35_17.0.svg | 2735 ------------------- 7 files changed, 25 insertions(+), 5665 deletions(-) delete mode 100644 documentation/architecture/img/datamodel.png delete mode 100644 documentation/architecture/original-drawings/clientside-arch.svg.2012_10_09_18_20_24.0.svg delete mode 100644 documentation/architecture/original-drawings/clientside-arch.svg.2012_10_12_17_35_17.0.svg (limited to 'documentation/architecture') diff --git a/documentation/architecture/architecture-client-side.asciidoc b/documentation/architecture/architecture-client-side.asciidoc index fa2336a1fa..72a1287f39 100644 --- a/documentation/architecture/architecture-client-side.asciidoc +++ b/documentation/architecture/architecture-client-side.asciidoc @@ -12,7 +12,7 @@ Engine"))) The user interface of a server-side Vaadin application is rendered in the browser by the Vaadin Client-Side Engine. It is loaded in the browser when the page with the Vaadin UI is opened. The server-side UI components are rendered -using __widgets__ (as they are called in Google Web Toolkit) on the client-side. +using __widgets__ (as they are called in GWT) on the client-side. The client-side engine is illustrated in <>. [[figure.architecture.client-side]] diff --git a/documentation/architecture/architecture-events.asciidoc b/documentation/architecture/architecture-events.asciidoc index e497ce5e94..c3f7b51468 100644 --- a/documentation/architecture/architecture-events.asciidoc +++ b/documentation/architecture/architecture-events.asciidoc @@ -7,17 +7,17 @@ layout: page [[architecture.events]] = Events and Listeners -Vaadin offers an event-driven programming model for handling user interaction. +Vaadin Framework offers an event-driven programming model for handling user interaction. When a user does something in the user interface, such as clicks a button or selects an item, the application needs to know about it. Many Java-based user interface frameworks follow the __Event-Listener pattern__ (also known as the Observer design pattern) to communicate user input to the application logic. So -does Vaadin. The design pattern involves two kinds of elements: an object that +does Vaadin Framework. The design pattern involves two kinds of elements: an object that generates ("fires" or "emits") events and a number of listeners that listen for the events. When such an event occurs, the object sends a notification about it to all the listeners. In a typical case, there is only one listener. -Events can serve many kinds of purposes. In Vaadin, the usual purpose of events +Events can serve many kinds of purposes. In Vaadin Framework, the usual purpose of events is handling user interaction in a user interface. Session management can require special events, such as time-out, in which case the event would actually be the lack of user interaction. Time-out is a special case of timed or scheduled @@ -32,28 +32,23 @@ listener). Most components that have related events define their own event class and the corresponding listener class. For example, the [classname]#Button# has [classname]#Button.ClickEvent# events, which can be listened to through the -[classname]#Button.ClickListener# interface. +[classname]#Button.ClickListener# functional interface. -In the following, we handle button clicks with a listener implemented as an -anonymous class: +In the following, we assign a button click listener using a lambda expression. [source, java] ---- final Button button = new Button("Push it!"); -button.addClickListener(new Button.ClickListener() { - public void buttonClick(ClickEvent event) { - button.setCaption("You pushed it!"); - } -}); +button.addClickListener(event -> + button.setCaption("You pushed it!")); ---- <> illustrates the case where an application-specific class inherits the [classname]#Button.ClickListener# interface to be able to listen for button click events. The application must instantiate the listener class and register it with -[methodname]#addClickListener()#. It can be an anonymous class, such as the one -above. When an event occurs, an event object is instantiated, in this case a +[methodname]#addClickListener()#. When an event occurs, an event object is instantiated, in this case a [classname]#Button.ClickEvent#. The event object knows the related UI component, in this case the [classname]#Button#. @@ -61,19 +56,4 @@ in this case the [classname]#Button#. .Class Diagram of a Button Click Listener image::img/events-classdiagram-hi.png[width=80%, scaledwidth=100%] -In Java 8, you can implement such functional interfaces with a lambda expression: - -[source, java] ----- -Button button = new Button("Push it!"); - -button.addClickListener(event -> - button.setCaption("You pushed it!")); ----- - -In the ancient times of C programming, __callback functions__ filled largely the -same need as listeners do now. In object-oriented languages, we usually only -have classes and methods, not functions, so the application has to give a class -interface instead of a callback function pointer to the framework. - <> goes into details of handling events in practice. diff --git a/documentation/architecture/architecture-overview.asciidoc b/documentation/architecture/architecture-overview.asciidoc index c35235e7b1..f0c5b32d75 100644 --- a/documentation/architecture/architecture-overview.asciidoc +++ b/documentation/architecture/architecture-overview.asciidoc @@ -7,7 +7,7 @@ layout: page [[architecture.overview]] = Overview -Vaadin provides two development models for web applications: for the client-side +Vaadin Framework provides two development models for web applications: for the client-side (the browser) and for the server-side. The server-driven development model is the more powerful one, allowing application development solely on the server-side, by utilizing an AJAX-based Vaadin Client-Side Engine that renders diff --git a/documentation/architecture/architecture-technology.asciidoc b/documentation/architecture/architecture-technology.asciidoc index ff0e7b2ed5..55a5b86585 100644 --- a/documentation/architecture/architecture-technology.asciidoc +++ b/documentation/architecture/architecture-technology.asciidoc @@ -12,8 +12,8 @@ Toolkit"))) ((("Google Web Toolkit"))) This section provides an introduction to the various technologies and designs, -which Vaadin is based on. This knowledge is not necessary for using Vaadin, but -provides some background if you need to make low-level extensions to Vaadin. +which Vaadin Framework is based on. This knowledge is not necessary for using Vaadin Framework, but +provides some background if you need to make low-level extensions to the framework. [[architecture.technology.html]] == HTML and JavaScript @@ -24,7 +24,7 @@ The World Wide Web, with all its websites and most of the web applications, is based on the use of the Hypertext Markup Language (HTML). HTML defines the structure and formatting of web pages, and allows inclusion of graphics and other resources. It is based on a hierarchy of elements marked with start and -end tags, such as [literal]#++
...
++#. Vaadin uses HTML version 5, +end tags, such as [literal]#++
...
++#. Vaadin Framework uses HTML version 5, although conservatively, to the extent supported by the major browsers, and their currently most widely used versions. @@ -32,11 +32,11 @@ their currently most widely used versions. JavaScript, on the other hand, is a programming language for embedding programs in HTML pages. JavaScript programs can manipulate a HTML page through the Document Object Model (DOM) of the page. They can also handle user interaction -events. The Client-Side Engine of Vaadin and its client-side widgets do exactly +events. The Client-Side Engine of the framework and its client-side widgets do exactly this, although it is actually programmed in Java, which is compiled to JavaScript with the Vaadin Client Compiler. -Vaadin largely hides the use of HTML, allowing you to concentrate on the UI +Vaadin Framework largely hides the use of HTML, allowing you to concentrate on the UI component structure and logic. In server-side development, the UI is developed in Java using UI components and rendered by the client-side engine as HTML, but it is possible to use HTML templates for defining the layout, as well as HTML @@ -74,7 +74,7 @@ syntax, which is more concise. The Vaadin Sass compiler supports the SCSS syntax. ((("themes"))) -Vaadin handles styling with __themes__ defined with CSS or Sass, and associated +Vaadin Framework handles styling with __themes__ defined with CSS or Sass, and associated images, fonts, and other resources. Vaadin themes are specifically written in Sass. In development mode, Sass files are compiled automatically to CSS. For production use, you compile the Sass files to CSS with the included compiler. @@ -119,11 +119,11 @@ serialization of RPC calls between the widgets and the server-side components. [[architecture.technology.gwt]] -== Google Web Toolkit +== GWT ((("Google Web Toolkit"))) -The client-side framework of Vaadin is based on the Google Web Toolkit (GWT). +The client-side of Vaadin Framework is based on GWT. Its purpose is to make it possible to develop web user interfaces that run in the browser easily with Java instead of JavaScript. Client-side modules are developed with Java and compiled into JavaScript with the Vaadin Compiler, which @@ -133,10 +133,10 @@ of the HTML DOM manipulation and enables handling browser events in Java. GWT is essentially a client-side technology, normally used to develop user interface logic in the web browser. Pure client-side modules still need to communicate with a server using RPC calls and by serializing any data. The -server-driven development mode in Vaadin effectively hides all the client-server +server-driven development mode in the framework effectively hides all the client-server communications and allows handling user interaction logic in a server-side application. This makes the architecture of an AJAX-based web application much -simpler. Nevertheless, Vaadin also allows developing pure client-side +simpler. Nevertheless, Vaadin Framework also allows developing pure client-side applications, as described in <>. @@ -144,7 +144,7 @@ Applications">>. See <> for a description of how the client-side framework based on GWT is -used in the Client-Side Engine of Vaadin. +used in the Client-Side Engine of Vaadin Framework. <> provides information about the client-side development, and @@ -170,14 +170,8 @@ image::img/java-servlet-hi.png[width=80%, scaledwidth=100%] Web applications are usually packaged and deployed to a server as __WAR__ ( __Web application ARchive__) files, which are Java JAR packages, which in turn are ZIP compressed packages. The web application is defined in a -[filename]#WEB-INF/web.xml# deployment descriptor, which defines the servlet -classes and also the mappings from request URL paths to the servlets. This is -described in more detail in -<>. The class path for the servlets and their -dependencies includes the [filename]#WEB-INF/classes# and -[filename]#WEB-INF/lib# folders. The [filename]#WEB-INF# is a special hidden -folder that can not be accessed by its URL path. +deployment descriptor, which defines the servlet +classes and also the mappings from request URL paths to the servlets. The servlets are Java classes that handle HTTP requests passed to them by the server through the __Java Servlet API__. They can generate HTML or other content @@ -194,8 +188,8 @@ UIs are implemented as classes extending the [classname]#UI# class, as described in <>. The class is given as a parameter to the -Vaadin Servlet in the [filename]#web.xml# deployment descriptor. +Vaadin Servlet in the deployment descriptor. -The Vaadin Client-Side Engine as well as client-side Vaadin applications are loaded to the browser as static JavaScript files. +The Client-Side Engine of Vaadin Framework as well as any client-side extension are loaded to the browser as static JavaScript files. The client-side engine, or widget set in technical terms, needs to be located under the [filename]#VAADIN/widgetsets# path in the web application. It is normally automatically compiled to include the default widget set, as well as any installed add-ons and custom widgets. diff --git a/documentation/architecture/img/datamodel.png b/documentation/architecture/img/datamodel.png deleted file mode 100644 index a639fa4a32..0000000000 Binary files a/documentation/architecture/img/datamodel.png and /dev/null differ diff --git a/documentation/architecture/original-drawings/clientside-arch.svg.2012_10_09_18_20_24.0.svg b/documentation/architecture/original-drawings/clientside-arch.svg.2012_10_09_18_20_24.0.svg deleted file mode 100644 index f372a405fa..0000000000 --- a/documentation/architecture/original-drawings/clientside-arch.svg.2012_10_09_18_20_24.0.svg +++ /dev/null @@ -1,2879 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - Makes XMLHttpRequest - - - VariableOwner VariableOwner - Sizeable - Sizeable - VariableOwner - - AbstractComponent - - - - - Widget - - - - MyWidget - - - ... - - MyConnector - - - - Paintable - - - - ApplicationConnection - com.vaadin.terminal.gwt.client. - - - - 1 n - Client-Side Framework - - Client-Side Integration - - - CommunicationManager - com.vaadin.terminal.server. - - - - - - Paintable - com.vaadin.terminal. - - - - n - - - MyComponent - - - Server connection:UIDL / JSON / HTTP(S) - - - Component - com.vaadin.ui. - - - paint() - paintContent() - Must implementupdateFromUIDL()to deserialize statefrom server - - com.vaadin.terminal.gwt.client. - Server-Side Integration - Must implement changeVariables() fordeserialization andpaintContent() forserialization using thePaintTarget interface. - updateFromUIDL() - - - updateVariable() - Needs to callupdateVariable() toto serialize state toserver - 1 - - - - PaintTarget - com.vaadin.terminal. - - - addAttribute()addVariable() - ... An existing widgetor your own - - - - - VariableOwner - com.vaadin.terminal. - changeVariables() - - - - (Implements paint()) - - Sizeable - Sizeable - VariableOwner - - AbstractComponentConnector - - - «extends» - - Shared - - - - diff --git a/documentation/architecture/original-drawings/clientside-arch.svg.2012_10_12_17_35_17.0.svg b/documentation/architecture/original-drawings/clientside-arch.svg.2012_10_12_17_35_17.0.svg deleted file mode 100644 index 52f367722e..0000000000 --- a/documentation/architecture/original-drawings/clientside-arch.svg.2012_10_12_17_35_17.0.svg +++ /dev/null @@ -1,2735 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - VariableOwner VariableOwner 1 - - - Vaadin Client-Side Engine - - - ApplicationConnection - com.vaadin.client - - - - ...Connector - - - - ...Connector - - - - ...Connector - - - Built-inWidget - - - Add-onWidget - - - CustomWidget - - - JavaScriptLibrary - - - - JavaScriptConnector - - XMLHttpRequest - - Server connection - HTTP(S) / JSON - - - - - Server-Side - - - - - CommunicationManager - com.vaadin.server - - - - Built-inComponent - - - Add-onComponent - - - CustomComponent - - - Component - - - - - -- cgit v1.2.3