diff options
Diffstat (limited to 'documentation/clientside')
7 files changed, 0 insertions, 465 deletions
diff --git a/documentation/clientside/chapter-clientside.asciidoc b/documentation/clientside/chapter-clientside.asciidoc deleted file mode 100644 index 6effe8475a..0000000000 --- a/documentation/clientside/chapter-clientside.asciidoc +++ /dev/null @@ -1,18 +0,0 @@ -[[clientside]] -== Client-Side Vaadin Development - -This chapter gives an overview of the Vaadin client-side framework, its -architecture, and development tools. - - -include::clientside-overview.asciidoc[leveloffset=+2] - -include::clientside-installing.asciidoc[leveloffset=+2] - -include::clientside-module.asciidoc[leveloffset=+2] - -include::clientside-compiling.asciidoc[leveloffset=+2] - -include::clientside-widget.asciidoc[leveloffset=+2] - -include::clientside-debugging.asciidoc[leveloffset=+2] diff --git a/documentation/clientside/clientside-compiling.asciidoc b/documentation/clientside/clientside-compiling.asciidoc deleted file mode 100644 index 18afb2c6ac..0000000000 --- a/documentation/clientside/clientside-compiling.asciidoc +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Compiling a Client-Side Module -order: 4 -layout: page ---- - -[[clientside.compiling]] -= Compiling a Client-Side Module - -A client-side module, either a widget set or a pure client-side module, needs to -be compiled to JavaScript using the Vaadin Client Compiler. During development, -the Development Mode makes the compilation automatically when you reload the -page, provided that the module has been initially compiled once with the -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">>.//// -TODO Provide a link to a proper add-on compilation section when one is -available. -//// - -[[clientside.compiling.overview]] -== Vaadin Compiler Overview - -The Vaadin Client Compiler compiles Java to JavaScript. It is provided as the -[filename]#vaadin-client-compiler# JAR, which you can execute with the -[literal]#++-jar++# parameter for the Java runtime. It requires the -[filename]#vaadin-client# JAR, which contains the Vaadin client-side framework. - -The compiler compiles a __client module__, which can be either a pure -client-side module or a Vaadin widget set, that is, the Vaadin Client-Side -Engine that includes the widgets used in the application. The client module is -defined with a module descriptor, which was described in -<<dummy/../../../framework/clientside/clientside-module#clientside.module,"Client-Side -Module Descriptor">>. - -The compiler writes the compilation result to a target folder that will include -the compiled JavaScript with any static resources included in the module. - - -[[clientside.compiling.eclipse]] -== Compiling in Eclipse - -When the Vaadin Plugin is installed in Eclipse, you can simply click the -[guibutton]#Compile Vaadin widgets# button in the toolbar. It will compile the -widget set it finds from the project. If the project has multiple widget sets, -such as one for custom widgets and another one for the project, you need to -select the module descriptor of the widget set to compile before clicking the -button. - -The compilation with Vaadin Plugin for Eclipse currently requires that the -module descriptor has suffix [filename]#Widgetset.gwt.xml#, although you can use -it to compile also other client-side modules than widget sets. The result is -written under [filename]#WebContent/VAADIN/widgetsets# folder. - - -[[clientside.compiling.ant]] -== Compiling with Ant - -You can find a script template for compiling widget sets with Ant and Ivy at the -link:http://vaadin.com/download/[Vaadin download page]. You can copy the build -script to your project and, once configured, run it with Ant. - - -[[clientside.compiling.maven]] -== Compiling with Maven - -You can compile the widget set with the [literal]#++vaadin:compile++# goal as -follows: - -[subs="normal"] ----- -[prompt]#$# [command]#mvn# [parameter]#vaadin:compile# ----- - - - diff --git a/documentation/clientside/clientside-debugging.asciidoc b/documentation/clientside/clientside-debugging.asciidoc deleted file mode 100644 index efbe24a8ec..0000000000 --- a/documentation/clientside/clientside-debugging.asciidoc +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Debugging Client-Side Code -order: 6 -layout: page ---- - -[[clientside.debugging]] -= Debugging Client-Side Code - -Vaadin currently includes SuperDevMode for debugging client-side code right in -the browser. - -The predecessor of SuperDevMode, the GWT Development Mode, no longer works in -recent versions of Firefox and Chrome, because of certain API changes in the -browsers. There exists workarounds on some platforms, but for the sake of -simplicity, we recommend using the SuperDevMode. - -ifdef::web[] -[[clientside.debugging.devmode]] -== Launching Development Mode - -The Development Mode launches the application in the browser, compiles the -client-side module (or widget set) when the page is loaded, and allows debugging -the client-side code in Eclipse. You can launch the Development Mode by running -the [classname]#com.google.gwt.dev.DevMode# class. It requires some parameters, -as described later. - -The Vaadin Plugin for Eclipse can create a launch configuration for the -Development Mode. In the Vaadin section of project properties, click the -[guibutton]#Create development mode launch# button. This creates a new launch -configuration in the project. You can edit the launch configuration in "Run > -Run Configurations". - - ----- --noserver -war WebContent/VAADIN/widgetsets com.example.myproject.widgetset.MyWidgetSet -startupUrl http://localhost:8080/myproject -bindAddress 127.0.0.1 ----- - -The parameters are as follows: - -[parameter]#-noserver#:: Normally, the Development Mode launches its own Jetty server for hosting the content. If you are developing the application under an IDE that deploys it to a server, such as Eclipse, you can disable the Development Mode server with this option. -[parameter]#-war#:: Specifies path to the location where the JavaScript is to be compiled. When developing a pure client-side module, this could be the [filename]#WebContent# (in Eclipse) or some other folder under it. When compiling widget sets, it must be [filename]#WebContent/VAADIN/widgetsets#. -[parameter]#-startupUrl#:: Specifies the address of the loader page for the application. For server-side Vaadin applications, this should be the path to the Vaadin application servlet, as defined in the deployment. For pure client-side widgets, it should be the page where the application is included. -[parameter]#-bindAddress#:: This is the IP address of the host in which the Development Mode runs. For debugging on the development workstation, it can be just [literal]#++127.0.0.1++#. Setting it as the proper IP address of the host enables remote debugging. - - -endif::web[] - -[[clientside.debugging.superdevmode]] -== Launching SuperDevMode - -The SuperDevMode is much like the old Development Mode, except that it does not -require a browser plugin. Compilation from Java to JavaScript is done -incrementally, reducing the compilation time significantly. It also allows -debugging JavaScript and even Java right in the browser (currently only -supported in Chrome). - -You can enable SuperDevMode as follows: - -. You need to set a redirect property in the [filename]#.gwt.xml# module -descriptor as follows: - - -+ ----- -<set-configuration-property name="devModeRedirectEnabled" value="true" /> ----- -+ -In addition, you need the [literal]#++xsiframe++# linker. It is included in the -[classname]#com.vaadin.DefaultWidgetSet# as well as in the -[classname]#com.vaadin.Vaadin# module. Otherwise, you need to include it with: - - -+ ----- -<add-linker name="xsiframe" /> ----- -. Compile the module (that is, the widget set), for example by clicking the button in Eclipse. -. If you are using Eclipse, create a launch configuration for the SuperDevMode by -clicking the [guibutton]#Create SuperDevMode launch# in the [guilabel]#Vaadin# -section of the project properties. - -.. The main class to execute should be [classname]#com.google.gwt.dev.codeserver.CodeServer#. -.. The application takes the fully-qualified class name of the module (or widget set) as parameter, for example, [classname]#com.example.myproject.widgetset.MyprojectWidgetset#. -.. Add project sources to the class path of the launch if they are not in the project class path. - - -The above configuration only needs to be done once to enable the SuperDevMode. -After that, you can launch the mode as follows: - -. Run the SuperDevMode Code Server with the launch configuration that you created above. This perfoms the initial compilation of your module or widget set. -. Launch the servlet container for your application, for example, Tomcat. -. Open your browser with the application URL and add [literal]#++?superdevmode++# parameter to the URL (see the notice below if you are not extending [classname]#DefaultWidgetSet#). This recompiles the code, after which the page is reloaded with the SuperDevMode. You can also use the [literal]#++?debug++# parameter and then click the [guibutton]#SDev# button in the debug console. - -If you make changes to the client-side code and refresh the page in the browser, -the client-side is recompiled and you see the results immediately. - -The Step 3 above assumes that you extend [classname]#DefaultWidgetSet# in your -module. If that is not the case, you need to add the following at the start of -the [methodname]#onModuleLoad()# method of the module: - - ----- -if (SuperDevMode.enableBasedOnParameter()) { return; } ----- - -Alternatively, you can use the bookmarklets provided by the code server. Go to -http://localhost:9876/ and drag the bookmarklets " [guilabel]#Dev Mode On#" and -" [guilabel]#Dev Mode Off#" to the bookmarks bar - - -[[clientside.debugging.chrome]] -== Debugging Java Code in Chrome - -Chrome supports source maps, which allow debugging Java source code from which -the JavaScript was compiled. - -Open the Chrome Inspector by right-clicking and selecting [guilabel]#Inspect -Element#. Click the settings icon in the lower corner of the window and check -the "Scripts > Enable source maps" option. Refresh the page with the Inspector -open, and you will see Java code instead of JavaScript in the scripts tab. - - - - diff --git a/documentation/clientside/clientside-installing.asciidoc b/documentation/clientside/clientside-installing.asciidoc deleted file mode 100644 index 0ad907f052..0000000000 --- a/documentation/clientside/clientside-installing.asciidoc +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Installing the Client-Side Development Environment -order: 2 -layout: page ---- - -[[clientside.installing]] -= Installing the Client-Side Development Environment - -The installation of the client-side development libraries is described in -<<dummy/../../../framework/getting-started/getting-started-overview.asciidoc#getting-started.overview,"Getting -Started with Vaadin">>. You especially need the [filename]#vaadin-client# -library, which contains the client-side Java API, and -[filename]#vaadin-client-compiler#, which contains the Vaadin Client Compiler -for compiling Java to JavaScript. - - - diff --git a/documentation/clientside/clientside-module.asciidoc b/documentation/clientside/clientside-module.asciidoc deleted file mode 100644 index 4656264ce1..0000000000 --- a/documentation/clientside/clientside-module.asciidoc +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Client-Side Module Descriptor -order: 3 -layout: page ---- - -[[clientside.module]] -= Client-Side Module Descriptor - -Client-side Vaadin modules, such as the Vaadin Client-Side Engine (widget set) -or pure client-side applications, that are to be compiled to JavaScript, are -defined in a __module descriptor__ ( [filename]#.gwt.xml#) file. - -When defining a widget set to build the Vaadin client-side engine, the only -necessary task is to inherit a base widget set. If you are developing a regular -widget set, you should normally inherit the [classname]#DefaultWidgetSet#. - - ----- - -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE module PUBLIC - "-//Google Inc.//DTD Google Web Toolkit 1.7.0//EN" - "http://google-web-toolkit.googlecode.com/svn/tags/1.7.0/distro-source/core/src/gwt-module.dtd"> - -<module> - <!-- Inherit the default widget set --> - <inherits name="com.vaadin.DefaultWidgetSet" /> -</module> ----- - -If you are developing a pure client-side application, you should instead inherit -[classname]#com.vaadin.Vaadin#, as described in -<<dummy/../../../framework/clientsideapp/clientsideapp-overview.asciidoc#clientsideapp.overview,"Client-Side -Applications">>. In that case, the module descriptor also needs an entry-point. - -If you are using the Eclipse IDE, the New Vaadin Widget wizard will -automatically create the GWT module descriptor. See -<<dummy/../../../framework/gwt/gwt-eclipse#gwt.eclipse.widget,"Creating a -Widget">> for detailed instructions. - -[[clientside.module.stylesheet]] -== Specifying a Stylesheet - -A client-side module can include CSS stylesheets. When the module is compiled, -these stylesheets are copied to the output target. In the module descriptor, -define a [literal]#++stylesheet++# element. - -For example, if you are developing a custom widget and want to have a default -stylesheet for it, you could define it as follows: - - ----- -<stylesheet src="mywidget/styles.css"/> ----- - -The specified path is relative to the __public__ folder under the folder of the -module descriptor. - - -[[gwt.module.compilation-limiting]] -== Limiting Compilation Targets - -Compiling widget sets takes considerable time. You can reduce the compilation -time significantly by compiling the widget sets only for your browser, which is -useful during development. You can do this by setting the -[parameter]#user.agent# property in the module descriptor. - - ----- -<set-property name="user.agent" value="gecko1_8"/> ----- - -The [parameter]#value# attribute should match your browser. The browsers -supported by GWT depend on the GWT version, below is a list of browser -identifiers supported by GWT. - -.GWT User Agents -[options="header"] -|=============== -|Identifier|Name -|ie6|Internet Explorer 6 -|ie8|Internet Explorer 8 -|gecko1_8|Mozilla Firefox 1.5 and later -|safari|Apple Safari and other Webkit-based browsers including Google Chrome -|opera|Opera -|ie9|Internet Explorer 9 - -|=============== - - - - -For more information about the GWT Module XML Format, please see Google Web -Toolkit Developer Guide. - - - diff --git a/documentation/clientside/clientside-overview.asciidoc b/documentation/clientside/clientside-overview.asciidoc deleted file mode 100644 index 8b475d812e..0000000000 --- a/documentation/clientside/clientside-overview.asciidoc +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Overview -order: 1 -layout: page ---- - -[[clientside.overview]] -= Overview - -As noted in the introduction, Vaadin supports two development models: -server-side and client-side. Client-side Vaadin code is executed in the web -browser as JavaScript code. The code is written in Java, like all Vaadin code, -and then compiled to JavaScript with the __Vaadin Client Compiler__. You can -develop client-side widgets and integrate them with server-side counterpart -components to allow using them in server-side Vaadin applications. That is how -the components in the server-side framework and in most add-ons are done. -Alternatively, you can create pure client-side GWT applications, which you can -simply load in the browser from an HTML page and use even without server-side -connectivity. - -The client-side framework is based on the Google Web Toolkit (GWT), with added -features and bug fixes. Vaadin is compatible with GWT to the extent of the basic -GWT feature set. Vaadin Ltd is a member of the GWT Steering Committee, working -on the future direction of GWT together with Google and other supporters of GWT. - - -[NOTE] -.Widgets and Components -==== -((("widget, -definition"))) -Google Web Toolkit uses the term __widget__ for user interface components. In -this book, we use the term widget to refer to client-side components, while -using the term __component__ in a general sense and also in the special sense -for server-side components. - -==== - - - -The main idea in server-side Vaadin development is to render the server-side -components in the browser with the Client-Side Engine. The engine is essentially -a set of widgets paired with __connectors__ that serialize their state and -events with the server-side counterpart components. The client-side engine is -technically called a __widget set__, to describe the fact that it mostly -consists of widgets and that widget sets can be combined, as described later. - - - diff --git a/documentation/clientside/clientside-widget.asciidoc b/documentation/clientside/clientside-widget.asciidoc deleted file mode 100644 index ed911a46b4..0000000000 --- a/documentation/clientside/clientside-widget.asciidoc +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Creating a Custom Widget -order: 5 -layout: page ---- - -[[clientside.widget]] -= Creating a Custom Widget - -Creating a new Vaadin component usually begins from making a client-side widget, -which is later integrated with a server-side counterpart to enable server-side -development. In addition, you can also choose to make pure client-side widgets, -a possibility which we also describe later in this section. - -[[clientside.widget.simple]] -== A Basic Widget - -All widgets extend the [classname]#Widget# class or some of its subclasses. You -can extend any core GWT or supplementary Vaadin widgets. Perhaps typically, an -abstraction such as [classname]#Composite#. The basic GWT widget component -hierarchy is illustrated in <<figure.clientside.widgets>>. Please see the GWT -API documentation for a complete description of the widget classes. - -[[figure.clientside.widgets]] -.GWT Widget Base Class Hierarchy -image::img/gwt-widgets-hi.png[] - -For example, we could extend the [classname]#Label# widget to display some -custom text. - - ----- -package com.example.myapp.client; - -import com.google.gwt.user.client.ui.Label; - -public class MyWidget extends Label { - public static final String CLASSNAME = "mywidget"; - - public MyWidget() { - setStyleName(CLASSNAME); - setText("This is MyWidget"); - } -} ----- - -The above example is largely what the Eclipse plugin generates as a widget stub. -It is a good practice to set a distinctive style class for the widget, to allow -styling it with CSS. - -The client-side source code __must__ be contained in a [filename]#client# -package under the package of the descriptor file, which is covered later. - - -[[clientside.widget.using]] -== Using the Widget - -You can use a custom widget just like you would use any widget, possibly -integrating it with a server-side component, or in pure client-side modules such -as the following: - - ----- -public class MyEntryPoint implements EntryPoint { - @Override - public void onModuleLoad() { - // Use the custom widget - final MyWidget mywidget = new MyWidget(); - RootPanel.get().add(mywidget); - } -} ----- - - - - |