vaadin / flow-and-components-documentation Goto Github PK

At the moment the tutorial explains the plain Java provided ServiceLoader approach in detail but does not contain any finer grained explanation for Spring or OSGI.

Sure, it is not hard to do but it saves time to have those.

Don’t use the pt unit, use rem or em (for font-size). If you must use a fixed size, use px.

The pt size is a leftover from print, and not relevant for most web apps.

On https://vaadin.com/docs/v10/flow/theme/theming-crash-course.html

There are some examples that are showing code that extend UI. These are no longer appropriate with the "new" router, and should thus be updated to show how things are done without a custom UI subclass. The cases are listed in this search listing.

I would expect some kind of pointers in the migration guide how to replace code like setIcon(VaadinIcons.SEARCH)

Please close the issue after this is done: vaadin/vaadin.com#36

Third blue info box of the page: https://vaadin.com/docs/v10/flow/polymer-templates/tutorial-template-basic.html

Is now

To get polymer-element.html into your project, you can use one of the ways provided by official Polymer page or use Maven plugins, such as frontend-maven-plugin

But probably should refer to webjars instead of frontend-maven-plugin? Since frontend-maven-plugin is used in Flow only for production builds. In pure client side projects (no Flow) frontend-maven-plugin might be used..

Deploying a Vaadin app to Tomcat 8.0.x, 8.5.x and 9.0.x being built with production mode has some visual elements broken.

Steps to reproduce

1. Download Beverage buddy from https://vaadin.com/start/v10-simple-ui
2. Import it to Eclipse
3. Download Tomcat and extract it
4. Add Tomcat to Eclipse via the servers tab
5. Add the app to deployment to Tomcat
6. Double click server -> Open Launch Configuration -> Arguments -> Add to VM arguments -Dvaadin.productionMode
7. Start up the server from servers tab.

Broken parts

When trying to start, you get the following exception and the app doesn't start.

java.lang.IllegalArgumentException: Unable to create an instance of 'com.vaadin.starter.beveragebuddy.ui.views.reviewslist.ReviewsList'. The constructor threw an exception.
	at com.vaadin.flow.internal.ReflectTools.createProxyInstance(ReflectTools.java:507)
	at com.vaadin.flow.internal.ReflectTools.createInstance(ReflectTools.java:444)
	at com.vaadin.flow.di.DefaultInstantiator.getOrCreate(DefaultInstantiator.java:64)
	at com.vaadin.flow.di.Instantiator.createRouteTarget(Instantiator.java:157)
	at com.vaadin.flow.router.internal.AbstractNavigationStateRenderer.lambda$getRouteTarget$1(AbstractNavigationStateRenderer.java:114)
	at java.util.Optional.orElseGet(Optional.java:267)
	at com.vaadin.flow.router.internal.AbstractNavigationStateRenderer.getRouteTarget(AbstractNavigationStateRenderer.java:113)
	at com.vaadin.flow.router.internal.AbstractNavigationStateRenderer.handle(AbstractNavigationStateRenderer.java:165)
	at com.vaadin.flow.router.Router.handleNavigation(Router.java:178)
	at com.vaadin.flow.router.Router.navigate(Router.java:150)
	at com.vaadin.flow.router.Router.initializeUI(Router.java:91)
	at com.vaadin.flow.component.UI.lambda$doInit$0(UI.java:205)
	at java.util.Optional.ifPresent(Optional.java:159)
	at com.vaadin.flow.component.UI.doInit(UI.java:205)
	at com.vaadin.flow.server.BootstrapHandler.createAndInitUI(BootstrapHandler.java:988)
	at com.vaadin.flow.server.BootstrapHandler.synchronizedHandleRequest(BootstrapHandler.java:388)
	at com.vaadin.flow.server.SynchronizedRequestHandler.handleRequest(SynchronizedRequestHandler.java:40)
	at com.vaadin.flow.server.VaadinService.handleRequest(VaadinService.java:1541)
	at com.vaadin.flow.server.VaadinServlet.service(VaadinServlet.java:345)
	at javax.servlet.http.HttpServlet.service(HttpServlet.java:729)
	at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:292)
	at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:207)
	at org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52)
	at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:240)
	at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:207)
	at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:212)
	at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:94)
	at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:141)
	at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:79)
	at org.apache.catalina.valves.AbstractAccessLogValve.invoke(AbstractAccessLogValve.java:620)
	at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:88)
	at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:502)
	at org.apache.coyote.http11.AbstractHttp11Processor.process(AbstractHttp11Processor.java:1132)
	at org.apache.coyote.AbstractProtocol$AbstractConnectionHandler.process(AbstractProtocol.java:684)
	at org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun(NioEndpoint.java:1539)
	at org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.run(NioEndpoint.java:1495)
	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
	at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
	at java.lang.Thread.run(Thread.java:745)
Caused by: java.lang.reflect.InvocationTargetException
	at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
	at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62)
	at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
	at java.lang.reflect.Constructor.newInstance(Constructor.java:423)
	at com.vaadin.flow.internal.ReflectTools.createProxyInstance(ReflectTools.java:476)
	... 39 more
Caused by: java.lang.IllegalStateException: Can't find resource 'frontend://src/views/reviewslist/reviews-list.html' via the servlet context
	at com.vaadin.flow.component.polymertemplate.DefaultTemplateParser.getTemplateContent(DefaultTemplateParser.java:111)
	at com.vaadin.flow.component.polymertemplate.TemplateDataAnalyzer.parseTemplate(TemplateDataAnalyzer.java:180)
	at com.vaadin.flow.component.polymertemplate.TemplateInitializer.<init>(TemplateInitializer.java:91)
	at com.vaadin.flow.component.polymertemplate.PolymerTemplate.<init>(PolymerTemplate.java:78)
	at com.vaadin.flow.component.polymertemplate.PolymerTemplate.<init>(PolymerTemplate.java:93)
	at com.vaadin.starter.beveragebuddy.ui.views.reviewslist.ReviewsList.<init>(ReviewsList.java:78)
	... 44 more

```

I can't find V8 Composite from the mapping table between components from V8 to V10.

If the com.vaadin.flow.theme.lumo.Lumo class is available in the classpath (which comes from the vaadin-lumo-theme project)

What is this vaadin-lumo-theme project? Is it a Github repo?

On https://vaadin.com/docs/v10/flow/theme/using-component-themes.html

Some of the links point to 1.0 alpha3.

Update https://github.com/vaadin/flow-and-components-documentation/blob/master/polymer-templates/tutorial-template-components.asciidoc to clarify that properties and children defined in the template won't be available through the server-side API.

Also describe the implications of this that would not be mitigated by vaadin/flow#3713, i.e. that getChildren() or getText() will be empty and that property values defined through the template won't be available.

Not sure what this part is supposed to look like (sentence end after 2022?), but this is confusing:

Staying with Vaadin Eight - it is Great! And supported at least until 2022 Using the upcoming Multiplatform Runtime from the Prime subscription to run views or components from a V8 app inside V10 for

...

On https://vaadin.com/docs/v10/flow/theme/using-component-themes.html

Theme variants section declares a DarkThemeApplication but then uses a “large” variant for it?

From DX testing Grid & DataProvider:
Writing custom implementation of DataProvider is hard without an example in the tutorial for Grid (no-one followed the link to DataProvider tutorial, probably it wasn’t prominent enough)

Acceptance Criteria

Need to make sure the correct parts of the data provider tutorials are highlighted in the corresponding parts of the Grid tutorials.
Another option is to somehow be able to merge these two different tutorial topics into one coherent tutorial. Or split into one journey that will introduce the listings (Grid, CompoBox etc.) and DataProviders together.

Theming is done as with any HTML content by using cascading style sheets or in short CSS to it

Strange sentence, “by using -- CSS to it”

On https://vaadin.com/docs/v10/flow/theme/theming-overview.html

Website feedback:
"Maybe i am the only one, but i am having a hard time understanding the Vaadin Flow localization documentation. What bothers me is the example given at the end:

public class MyLocale extends Div {

public MyLocale() {
    setText(getTranslation("my.translation", getUserId()));
}

}
I think it is unclear what the recommended way is for invoking the getTranslation() method.
Where does it come from? Am i supposed to inject the I18NProvider or does Vaadin somehow know where to invoke this method via the I18N provider property?

In Vaadin 8 i wrote a Singleton class for invoking I18N.get(String key) via static methods. This approach is very convenient for me and i would like to continue using that approach.

EDIT: I wrote an extra Singleton class now (just like i did with Vaadin 8) which gets my I18NProvider injected. That works fine, but i do not know if this is the way it is intended to be used. (?)"

Please also manage the website feedback issue:
vaadin/vaadin.com#33

As a developer I want to see clear documentation about which Java and JS types are supported in template model properties, how these types correspond to each other, and how the initial values of the synchronized properties are determined.

The documentation should answer the following questions:

• When declaring a TemplateModel interface in Java, should I use primitive or boxed types (e.g. boolean or Boolean)? (answer: both ways are supported, but there are subtle differences)
• What are the differences between using a primitive and a boxed type in a template model?
• When defining a boolean property, should I use a different name for the property getter (isCheckboxChecked or getCheckboxChecked)?
• How does Flow convert types between JS and Java for model properties?
  -- how a JS null is converted into a Java boolean / Boolean / int / Integer / etc
  -- how a JS undefined is converted into a Java boolean / Boolean / int / Integer / etc
• How is the initial value of a model property determined?
  -- if a property is set on the server side, how is the value of that property visible to the client side code? (initial JS value would be undefined, then the server-set value will be delivered to the client)
  -- if a property is set on the client side, how is the value of that property visible to the server side cide?

At the moment (with the version 1.0.0.alpha20) the actual Flow behavior is confusing, and the docs are inconsistent. For example, the docs have examples for using both Boolean and boolean: https://github.com/vaadin/flow-and-components-documentation/search?l=AsciiDoc&q=Boolean&type=&utf8=%E2%9C%93

The actual behavior is confusing:

• Boolean getCheckboxChecked(); --> java.lang.NullPointerException
• boolean getCheckboxChecked(); --> OK
• boolean isCheckboxChecked(); --> OK
• Boolean isCheckboxChecked(); --> InvalidTemplateModelException: Template Model does not support: isModelProperty with return type: java.lang.Boolean with parameters.

See vaadin/flow#3556 for details.

The migration documentation mentions differences between Charts 4 and Charts 6, without ever mentioning Charts 5. This makes the reader wonder whether there's a typo in the version number.

Application Theme - What and Where ?

Should not have a space before question mark.

On https://vaadin.com/docs/v10/flow/theme/application-theming-basics.html

Marketing is kicking off a project to increase website identifications.

V8 book PDF has performed very well. We should offer similar PDF for V10 (though it is not a book but docs collection).

Please create V10 documentation PDF.

There is another theme being build

On https://vaadin.com/docs/v10/flow/theme/using-component-themes.html

discussed further in the next chapter’s.

Should it be “chapters” (not possessive)? If yes, how does one link lead to many chapters? If it should be possessive “chapter’s” then there’s some words missing after it.

On https://vaadin.com/docs/v10/flow/theme/application-theming-basics.html

https://vaadin.com/docs/v10/flow/migration/5-components.html says Label is replaced by Label but those are two very different components

“polymer” -> ”Polymer”

https://vaadin.com/docs/v10/flow/theme/application-theming-basics.html

Close the website issue when done: vaadin/vaadin.com#34

When building an addon using PolymerTemplate (or maybe even generally), by default the addon won't be able to run under IE 11.

• This fact is I believe not mentioned in the documentation.
• There is no documentation how to support IE 11.

The documentation for taking your application to the prom oops production, was removed since it was in the wrong place.

We should reintroduce it, but make it better. There should be a new main level topic "Packaging for Production" with following proposed subtopics:

1. Taking your Application into Production

• Start with TL;DR: version
  • States the minimum things you need to have in pom.xml and how package for production by running mvn package -Dvaa...
• Describe what the packaging does in more details, eg. transpilation and bundling
  • No details on how to customize anything, just on general level
• Link to an example of this setup, like the project base.

2. Customizing Bundling

• How to configure and use fragments

3. Advanced Topics

• How to resolve issues
• Any advanced customization points for the maven plugin, but in best case this should just link to the site produced by vaadin/flow#3903 and the configuration descriptions should have been added vaadin/flow#3547

This is an umbrella (epic) for OSGi issues

Partially its done here:
#12

Still needs to be fixed because of changes related to Renderer refactoring.
Waits for Grid which depends on Renderer refactoring as well and docs depend on Grid.

Similar task for FW: vaadin/framework#8594

Note that the implementation of the task in FW contains only smoke tests and also tests
custom GWT widgetset which is not applicable for Flow.

It would be nice to run the same tests in the flow-tests module in OSGi container.
At least flow-tests/test-root-context.

But I'm not sure whether it's possible.
At least smoke tests and test which validates all OSGi specific functionality implemented in Flow should be provided.

There is an example on this in the crash course chapter too.

A link to that chapter would be great, and maybe use the actual chapter title to reinforce the connection.

Also, it should be “example of” not “example on”.

On https://vaadin.com/docs/v10/flow/theme/application-theming-basics.html

I would expect from the migration guide some kind of mention what to do with Valo built-in styles when moving to Vaadin 10.

https://github.com/vaadin/flow-and-components-documentation/blob/master/documentation/importing-dependencies/tutorial-include-css.asciidoc

This document should include a warning about using a regular global stylesheet, as that can leak into components in polyfilled browsers.

For example, something like the following would most probably cause havoc in many components:

div {
  margin: 20px;
}

In addition, we should document how to included CSS that is correctly scoped in all browsers – basically, to create a HTML import that contains an import for custom-style.html (from Polymer) and then a <custom-style> declaration including the CSS you want to add.

Provide a documentation for OSGi support similar to vaadin/framework#9155

Some sections from the PR above are not applicable for Flow

Big red warning box at the end of the article is scary.

AFAIK it’s unnecessary, as all of our own component themes are basically based on shared styles (duplicating the same stylesheet inside each component instance), so it feels odd to say an app developer should not do that.

On https://vaadin.com/docs/v10/flow/theme/theming-crash-course.html

allow you to very fine tune the look

Looks like a typo (either a word too much or a word missing).

On https://vaadin.com/docs/v10/flow/theme/using-component-themes.html

The example (in Theming Crash Course) should encourage the user to import the custom-style.html from Polymer (when using <custom-style>).

Perhaps Flow always imports that, I don’t know. Lumo does import that, but for users who are not using Lumo, what happens?

Vaadin 8 Notification.Type doesn't seem to have Vaadin 10 alternative. Migration guide should give pointers how to achieve same functionality.

https://mvnrepository.com/artifact/com.vaadin.external/gentyref/1.2.0.vaadin1

Original Gentyref library is not OSGi compatible.
External OSGi compatible vaadin artifact has been created for FW.
It should be used for Flow as well.

Flow tutorial mentions

As its name implies, the value change listener allows you to react to changes in the value contained in the text field. It is configured so that the event is fired lazily while the user is typing, when there is a small pause in the typing. This makes it perfect for this kind of automatic filtering.

If I'm not mistaken the tutorial creates a text field that applies value change in blur, which is not optimal for search field and not as advertised in tutorial.

In some sections of our documentations (i.e. how to use webjars), we are giving an example of using the old webjars. As it is not supported anymore in flow, we should update the examples to use new webjars.

But on the other hand, should we mention the old way to publish the webjars and what will be the new way (Artur's script?? )? It is a little bit confusing for the users, as they cannot find the correct example from www.webjars.org (or maybe later, the website will update?)

we can following the process on -> webjars/webjars#1703

In https://vaadin.com/docs/v10/flow/migration/5-components.html there is only links to Grid demo and tutorial, but I think there should be more explanation what are the differences and what needs to be done differently (if anything) and what cannot be achieved compared to Vaadin 8.

On https://vaadin.com/docs/v10/flow/theme/using-component-themes.html

The first list contains rules how a theme is selected. The last point is just a conclusion of the above, so it should not be contained in the list, but just a regular paragraph after the list (which is actually already there after the list).

Also, the sentence structure is cumbersome as an “if all are not”. Would probably be easier to understand as an “if none are” (since the “not“ is very disconnected from “all”).

If all the previous conditions are not met, no theme is used.
vs.
If none the previous conditions are met, no theme is used.

@kristofdan commented on Fri Apr 20 2018

In the documentation page at https://vaadin.com/docs/v10/flow/binding-data/tutorial-flow-data-provider.html, in the first code listing the Status::getLabel method is used to display a Status, although the text before the listing tells that Status.getCaption() will be used.

• make a V10 branch
  • make branch protected
  • enable validation build, sonar, cla-assistant, etc. for the branch
  • be sure the Vcom team build from the V10 branch.
• the master branch should still have the validation build it has now (!)
• Add mention to both branches READMEs how the branches work, eg. master for V11 and V10 for V10

I would love to understand the biggest differences between Vaadin 8 and Vaadin 10 ordered layouts.
Hopefully I could see also pictured together with the explanations: "to achieve this scenario from Vaadin 8, now you do it like this in Vaadin 10"