From 7ac2089afb27af6fdb4f187c934a9a1dde937f1b Mon Sep 17 00:00:00 2001 From: Teemu Suo-Anttila Date: Thu, 12 May 2016 14:24:33 +0300 Subject: Add basic AppWidgetset documentation Change-Id: Iaea8b5267c7ccb2a6bc667cc89078bd3c4bf2435 --- .../application/application-environment.asciidoc | 48 ++++++++++++++-------- 1 file changed, 31 insertions(+), 17 deletions(-) (limited to 'documentation/application') diff --git a/documentation/application/application-environment.asciidoc b/documentation/application/application-environment.asciidoc index 0322c77e4a..f5933afe85 100644 --- a/documentation/application/application-environment.asciidoc +++ b/documentation/application/application-environment.asciidoc @@ -62,7 +62,9 @@ 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. +If your application uses add-ons or custom widgets, they must be compiled to the [filename]#VAADIN/widgetset/# directory. +When using add-ons, this is done automatically in Maven projects. +See <> for more information. [[application.environment.webservlet]] == Web Servlet Class @@ -137,7 +139,7 @@ The servlet is then mapped to a URL path in a standard way for Java Servlets. <!-- If not using the default widget set--> <init-param> <param-name>widgetset</param-name> - <param-value>[replaceable]##com.ex.myprj.MyWidgetSet##</param-value> + <param-value>[replaceable]##com.ex.myprj.AppWidgetSet##</param-value> </init-param> </servlet> @@ -173,24 +175,36 @@ Servlet 3.0 support is useful for at least server push. [[application.environment.web-xml.widgetset]] === Widget Set -If the UI uses add-on components or custom widgets, it needs a custom widget -set, which can be specified with the [parameter]#widgetset# parameter for the -servlet. Alternatively, you can defined it with the [classname]#@WidgetSet# -annotation for the UI class. The parameter is a class name with the same path -but without the [filename]#.gwt.xml# extension as the widget set definition -file. If the parameter is not given, the -[classname]#com.vaadin.DefaultWidgetSet# is used, which contains all the widgets -for the built-in Vaadin components. +The widget set is normally defined and compiled automatically in Maven projects. +It may be necessary to define it manually in some cases, such as when developing custom widgets or if you need to include special rules in the widget set definition file ([filename]#.gwt.xml# module descriptor). -Unless using the default widget set (which is included in the -[filename]#vaadin-client-compiled# JAR), the widget set must be compiled, as -described in -<> or -<>, and properly deployed with the application. +The widget set of a UI can be defined with the [classname]#@WidgetSet# annotation for the UI class. +[source, Java, subs="normal"] +---- +@WidgetSet("[replaceable]#com.example.myproject.MyWidgetSet#") +class MyUI extends UI { + ... +---- + +You can also define it in the [filename]#web.xml# descriptor for the servlet: + +[source, xml, subs="normal"] +---- + + widgetset + com.example.myproject.MyWidgetSet + +---- + +The name of a widget set is technically a Java class name with the same path as the widget set definition file, but without the [filename]#.gwt.xml# extension. + +If a widget set is not specified, the default is used. +In a project that does not use add-ons or custom widgets, the [classname]#com.vaadin.DefaultWidgetSet# is used. +It contains all the widgets for the built-in Vaadin components. +When using add-ons, the Vaadin Maven Plugin automatically defines an [classname]#AppWidgetSet# that includes all the add-on widget sets. +The widget set must be compiled, as described in <> (for add-ons) or <> (for custom widgets and client-side modules), and properly deployed with the application. [[application.environment.servlet-mapping]] == Servlet Mapping with URL Patterns -- cgit v1.2.3