vaadin / docs Goto Github PK

Official documentation for Vaadin and Hilla.

License: Other

Java 17.36% TypeScript 21.32% JavaScript 0.64% Makefile 0.02% CSS 0.62% Dockerfile 0.01% Shell 0.05% HTML 0.01% AsciiDoc 59.94% Mermaid 0.02% Python 0.02%

vaadin documentation hilla

docs's Introduction

Vaadin documentation

Official documentation and code examples for Vaadin.

This repository does not generate the vaadin.com/docs or hilla.dev/docs websites. It only contains the content for them. The builds are done using Vaadin Design System Publisher.

Files not explicitly listed below are from the standard Vaadin project setup.

`articles`

A hierarchy of AsciiDoc files (.adoc), documenting the use of all Vaadin features. The file path defines the resulting URL on the documentation site.

For example:

articles/flow/index.adoc → /flow/
articles/flow/forms/data-binding.adoc → /flow/forms/data-binding/

See the contribution guides to learn more.

`frontend`

TypeScript examples, which are included as rendered examples in the documentation. Follow Vaadin best practices when creating code examples.

`src`

Flow/Java examples, which are included as rendered examples in the documentation. Follow Vaadin best practices when creating code examples.

`scripts`

Project-related scripts (tests, validation builds, preview deployment, etc).

`.github`

Files related to linting the articles against the writing style guidelines with Vale. See Vale linter setup instructions.

`versions.json`

Describes the publicly available documentation versions. These versions will appear in the published website, as options for the users. This file is only relevant in the latest branch.

docs's People

Contributors

Stargazers

Watchers

Forkers

kaviwe cnbroderick tatulund heruan knaven0128 jcgueriaud1 attenymalm jojule sobhan-java tarekoraby dougjewsbury janspoerer hermanndorgeles ulmasovjafarbek cgnunezbantics ohmsdev kouichinoro sakorepanov sindrehauglum sozewa rehanahmedd hengsokchea rickqinj khbtrr pbaris jamie-codez aravaswapna moodi2005 sebastiandietrich smashah hamid3764 aliceosclassic wilson1745 devmyc christosavramis sundayeze hillelcs gronono guiyi-q knoobie jannatj421 blackpjotr andreika63 dallr0g starg09 obfischer vtutay simasch fatihtufann masifi omamaisrar slepvlad siasamkelamzamo alissonsegattodesouza soltercom sp-2827 tmutlu yelsonveras nguyenminhkhoa26 ramanamuttana tobias003 gocbar paulowei daidz1 johann404 daphnad felix-seifert socb oliveryasuna flmz farkascsanad gerti055 hycjack frankielc ramzzshanko simeshev meriemterki timo-con hamilton-marc yunuse1 chkpnt grgendron moskvichevviktor lucacolaianni guilhermemontanher eiradev sultanovmb rsembajjwe meissatouncaradiarra kirtiautade omerhakanbilici ivanovm2020 jkblskw mlopezfc yuliapower dmitry1308 jluque23 sezim8 jiujua kirmerzlikin

docs's Issues

Broken link to Vaadin add-on starter

Reported by the user. The link https://vaadin.com/start/latest/component mentioned in this article isn't working.

The correct link is this one: https://github.com/vaadin/addon-starter-flow

Document styling web components using registerStyles API and css literals

// shared-styles.js

import { css } from '@vaadin/vaadin-themable-mixin/register-styles.js';

export const sharedStyles = css`
 // Shared style rules
`;

// client.js

import { registerStyles } from '@vaadin/vaadin-themable-mixin/register-styles.js';
import { sharedStyles } from  './shared-styles.js'

registerStyles('my-element', sharedStyles);

Fix TODOs

Component API references inline in docs pages

It would be good to have API references (Java and TS) for components in the component docs themselves, so that you wouldn't have to navigate to a different part of vaadin.com to read them.

Collaboration Engine docs for V18+ have @Push on the wrong class

https://vaadin.com/docs/v18/ce/tutorial.html#ce.tutorial.push
The @Push annotation should be on the AppShellConfigurator class, not the main layout, in V18 and later.

Search Icons in the demo by keywords in addition to the name

The search should find icons using the keywords (specified in https://github.com/vaadin/vaadin-icons/blob/master/assets/vaadin-font-icons.json) as well as the main icon name.

Documentation : Lacking use cases for LoginForm and LoginOverlay

There is not much information about differences between LoginForm and LoginOverlay, which imposes the question, which one should be used under what circumstances. Also, it's not opened anywhere what does overlay exactly means (Nor I found any official definition, so it would be nice if we could open it on our site)
Encouraged by this discussion on SO: https://stackoverflow.com/questions/59482312/loginform-versus-loginoverlay-in-vaadin-14/

Session init listener documentation is hard to find

User feedback, linked to https://vaadin.com/docs-beta/v14/flow/advanced/tutorial-service-init-listener/

I assume they expected to see an example how to add a session init listener.

Should be fixed in latest as well.

Document that ListBox does not use lazy loading

Using the dataProvider, but internally always using the max value for query limit. This defeats the purpose of the data provider in my opinion.

Add more detailed documentation/demo about default behavior after login

When user submits the login, the submit button is disabled to prevent another attempt before the login is processed.

Add:

Documentation describing the behavior
Demo with details with what the developer should do in order to re-enable login

Broken link found (flow/Overview/)

Broken link found

Broken Link Checker found a broken link on https://vaadin.com/docs-beta/latest/

Target: flow/Overview/

HTTP_404

View Actions Results

Enable the Vale linter for the documentation

Vale should be run automatically on commit, checking the changed AsciiDoc files.
Use necessary styles, disable unwanted checks.

It should be mentioned that AppLayout as designed to be a root layout

AppLayout is designed to be a root element. While it's mentioned in client-side documentation https://cdn.vaadin.com/vaadin-app-layout/2.0.4/#/elements/vaadin-app-layout, it's completely omitted from a server-side.

For best results, the component should be added to the root level of your application (i.e., as a direct child of <body>).

Now adding it as a child makes NavBar rendered at the top of the page, not its parent element. (which causes frustration, at the very least)

Improve landing page

The landing page could be more helpful for new users in finding the best way forward, promoting the main tutorials and interesting content.

For ideation:

Broken cross references (links)

Use absolute references

When fixing the references, use the {articles} attribute as a prefix when linking across top-level sections (between Flow, Fusion, Design System, etc), to make the references more future-proof (they won’t break if the article hierarchy is modified).

For example: <<{articles}/guide/overview#, Beginner's Guide>>

warn Broken cross reference ../guide/production/production-overview in ce/going-to-production.asciidoc
warn Broken cross reference ../guide/production/mode in ce/going-to-production.asciidoc
warn Broken cross reference ../flow/advanced/flow-runtime-configuration in ce/going-to-production.asciidoc
warn Broken internal reference css-styling in ds/components/charts/java-api/migrating-from-earlier-versions.asciidoc
warn Broken cross reference ../treegrid in ds/components/grid-pro/index.asciidoc
warn Broken cross reference ../check-box in ds/components/radio-button/index.asciidoc
warn Broken cross reference ../ordered-layout in ds/components/scroller/index.asciidoc
warn Broken cross reference ../ordered-layout in ds/components/scroller/index.asciidoc
warn Broken cross reference flow-runtime-configuration in flow/advanced/application-lifecycle.asciidoc
warn Broken cross reference ../typescript/starting-the-app in flow/advanced/service-init-listener.asciidoc
warn Broken cross reference starting-the-app in flow/advanced/modifying-the-bootstrap-page.asciidoc
warn Broken internal reference loading-resources/<mark>importing-javascript-and-css in flow/advanced/dependency-filter.asciidoc
warn Broken internal reference styling/importing-style-sheets</mark> in flow/advanced/dependency-filter.asciidoc
warn Broken cross reference ways-of-importing in flow/advanced/css-loading-order.asciidoc
warn Broken cross reference component-integration in flow/application/templates.asciidoc
warn Broken cross reference ../../theming/overview in flow/components/overview.asciidoc
warn Broken cross reference ../../theming/styling-components in flow/components/grid.asciidoc
warn Broken cross reference component-basic in flow/creating-components/overview.asciidoc
warn Broken cross reference component-many-elements in flow/creating-components/overview.asciidoc
warn Broken cross reference component-composite in flow/creating-components/overview.asciidoc
warn Broken cross reference component-container in flow/creating-components/overview.asciidoc
warn Broken cross reference component-property-descriptor in flow/creating-components/overview.asciidoc
warn Broken cross reference component-events in flow/creating-components/overview.asciidoc
warn Broken cross reference component-lifecycle-callbacks in flow/creating-components/overview.asciidoc
warn Broken cross reference component-mixins in flow/creating-components/overview.asciidoc
warn Broken cross reference ../../theming/styling-components in flow/creating-components/extending-component.asciidoc
warn Broken internal reference drag-source in flow/dnd/drop-target.asciidoc
warn Broken cross reference ../../advanced/flow-runtime-configuration in flow/integrations/cdi/overview.asciidoc
warn Broken cross reference ../spring/spring-scopes in flow/integrations/cdi/contexts.asciidoc
warn Broken cross reference ../../advanced/push-access in flow/integrations/cdi/contexts.asciidoc
warn Broken cross reference ../../routing/annotation in flow/integrations/cdi/contexts.asciidoc
warn Broken cross reference ../routing/router-layout in flow/integrations/cdi/contexts.asciidoc
warn Broken cross reference basic in flow/integrations/spring/spring-mvc.asciidoc
warn Broken cross reference spring-scopes in flow/integrations/spring/spring-mvc.asciidoc
warn Broken cross reference basic in flow/integrations/spring/spring-mvc.asciidoc
warn Broken cross reference ../../routing/annotation in flow/integrations/embedding/limitations.asciidoc
warn Broken cross reference ../../routing/annotation in flow/integrations/embedding/limitations.asciidoc
warn Broken cross reference webcomponent-push in flow/integrations/embedding/limitations.asciidoc
warn Broken cross reference webcomponent-intro in flow/integrations/embedding/limitations.asciidoc
warn Broken cross reference ../../routing/annotation in flow/integrations/spring/routing.asciidoc
warn Broken cross reference basic in flow/integrations/spring/routing.asciidoc
warn Broken cross reference spring-basic-mvc in flow/integrations/spring/routing.asciidoc
warn Broken cross reference ../../routing/annotation in flow/integrations/spring/routing.asciidoc
warn Broken cross reference basic in flow/integrations/spring/routing.asciidoc
warn Broken cross reference spring-basic-mvc in flow/integrations/spring/routing.asciidoc
warn Broken cross reference basic-mvc in flow/integrations/spring/configuration.asciidoc
warn Broken cross reference ../../guide/production/production-mode-basic in flow/integrations/osgi-basic.asciidoc
warn Broken cross reference ../routing/routing-annotation in flow/integrations/osgi-basic.asciidoc
warn Broken cross reference ../routing/routing-exception-handling in flow/integrations/osgi-basic.asciidoc
warn Broken cross reference ../pwa/pwa-pwa-with-flow in flow/integrations/osgi-basic.asciidoc
warn Broken cross reference spring/basic in flow/integrations/overview.asciidoc
warn Broken cross reference cdi/basic in flow/integrations/overview.asciidoc
warn Broken cross reference embedding/intro in flow/integrations/overview.asciidoc
warn Broken cross reference integrations/osgi-basic in flow/integrations/overview.asciidoc
warn Broken cross reference integrations/osgi-karaf in flow/integrations/overview.asciidoc
warn Broken cross reference security-intro in flow/security/overview.asciidoc
warn Broken cross reference security-vulnerabilities in flow/security/overview.asciidoc
warn Broken cross reference security-frequent-issues in flow/security/overview.asciidoc
warn Broken cross reference ../components/flow-grid in flow/templates/polymer-template-and-binder.asciidoc
warn Broken cross reference ../routing/router-layout in flow/templates/parent-layout.asciidoc
warn Broken cross reference template-model-bean in flow/templates/event-handlers.asciidoc
warn Broken cross reference ../binding-data/flow-components-binder in flow/templates/and-binder.asciidoc
warn Broken cross reference ../components/flow-grid in flow/templates/and-binder.asciidoc
warn Broken cross reference ../binding-data/flow-components-binder in flow/web-components/java-api-for-a-web-component.asciidoc
warn Broken cross reference ../production/production-mode-basic in flow/templates/basic.asciidoc
warn Broken cross reference ../advanced/all-vaadin-properties in flow/web-components/integrating-a-web-component.asciidoc
warn Broken cross reference ../production/production-mode-advanced in flow/web-components/integrating-a-web-component.asciidoc
warn Broken cross reference templates/template-intro in flow/overview.asciidoc
warn Broken cross reference dnd/generic-dnd in flow/overview.asciidoc
warn Broken cross reference pwa/overview in flow/overview.asciidoc
warn Broken cross reference typescript-endpoints-generator in fusion/advanced/type-conversion.asciidoc
warn Broken internal reference UserEndpoints.ts in fusion/advanced/endpoints-generator.asciidoc
warn Broken cross reference ../introduction/overview in fusion/application/starting.asciidoc
warn Broken cross reference ../v15-migrationupgrading-from-vaadin14 in fusion/application/starting.asciidoc
warn Broken cross reference quick-start-guide in fusion/application/starting.asciidoc
warn Broken cross reference ../../flow/application/application-overview in fusion/application/overview.asciidoc
warn Broken cross reference ../../guide/introduction/overview in fusion/application/overview.asciidoc
warn Broken cross reference ../../fusion/routing/routing-defining in fusion/application/overview.asciidoc
warn Broken cross reference ../../fusion/routing/routing-defining in fusion/application/overview.asciidoc
warn Broken cross reference ../../fusion/security/fusion-security-overview in fusion/application/overview.asciidoc
warn Broken internal reference v15-migration/upgrading-from-vaadin14 in fusion/application/main-view.asciidoc
warn Broken cross reference type-conversion in fusion/application/client-exceptions.asciidoc
warn Broken cross reference starting-the-app in fusion/application/basics.asciidoc
warn Broken cross reference starting-the-app in fusion/application/basics.asciidoc
warn Broken cross reference creating-routes in fusion/application/basics.asciidoc
warn Broken cross reference creating-routes in fusion/application/basics.asciidoc
warn Broken cross reference ../advanced/fusion-advanced-type-conversion in fusion/application/accessing-backend.asciidoc
warn Broken cross reference ../binding-data/components-binder-validation in fusion/forms/binder-validation.asciidoc
warn Broken cross reference binder in fusion/forms/appendix-web-component-field-strategy.asciidoc
warn Broken cross reference binder in fusion/forms/appendix-vaadin-components.asciidoc
warn Broken cross reference binder in fusion/forms/appendix-vaadin-components.asciidoc
warn Broken cross reference ../advanced/modifying-the-bootstrap-page in fusion/routing/layouts.asciidoc
warn Broken cross reference ../java/routing-java-defining in fusion/routing/defining.asciidoc
warn Broken cross reference ../java/routing-java-defining in fusion/routing/defining.asciidoc
warn Broken cross reference quick-start-guide in fusion/security/spring-login.asciidoc
warn Broken cross reference ../../flow/security/flow-overview in fusion/security/overview.asciidoc
warn Broken cross reference ../advanced/fusion-advanced-client-middleware in fusion/security/handle-session-expiration.asciidoc
warn Broken cross reference fusion-security-spring-login in fusion/security/custom-spring-login.asciidoc
warn Broken cross reference fusion-security-spring-login in fusion/security/custom-spring-login.asciidoc
warn Broken cross reference adding-login-form-with-spring-security in fusion/security/configuring.asciidoc
warn Broken cross reference ../advanced/servlet-container-authentication in fusion/security/configuring.asciidoc
warn Broken cross reference check-user-login in fusion/security/configuring.asciidoc
warn Broken cross reference ../advanced/framework-security in fusion/security/configuring.asciidoc
warn Broken internal reference guide/installing/installing-overview in fusion/quick-start-tutorial.asciidoc
warn Broken cross reference ../guide/getting-started/intellij in fusion/quick-start-tutorial.asciidoc
warn Broken cross reference ../guide/getting-started/getting-started-eclipse in fusion/quick-start-tutorial.asciidoc
warn Broken cross reference ../guide/getting-started/getting-started-netbeans in fusion/quick-start-tutorial.asciidoc
warn Broken internal reference configuring-security in fusion/quick-start-tutorial.asciidoc
warn Broken internal reference theming/style-scopes in fusion/quick-start-tutorial.asciidoc
warn Broken internal reference routing/routing-defining in fusion/quick-start-tutorial.asciidoc
warn Broken cross reference configuring-security in fusion/security/authentication.asciidoc
warn Broken cross reference adding-login-form-with-spring-security in fusion/security/authentication.asciidoc
warn Broken cross reference check-user-login in fusion/security/authentication.asciidoc
warn Broken cross reference ../advanced/modifying-the-bootstrap-page in guide/configuration/pwa.asciidoc
warn Broken cross reference service-worker in guide/configuration/pwa.asciidoc
warn Broken cross reference icons in guide/configuration/pwa.asciidoc
warn Broken cross reference offline in guide/configuration/pwa.asciidoc
warn Broken cross reference offline in guide/configuration/pwa.asciidoc
warn Broken cross reference manifest in guide/configuration/pwa.asciidoc
warn Broken cross reference icons in guide/configuration/pwa.asciidoc
warn Broken cross reference flow-runtime-configuration in guide/configuration/npm-pnpm.asciidoc
warn Broken cross reference i18n-localization in guide/configuration/index.asciidoc
warn Broken cross reference ../../testbench/creating-tests in guide/contributing/web-component-integration-testing.asciidoc
warn Broken cross reference ../../flow/spring/configuration in guide/production/spring-boot.asciidoc
warn Broken cross reference ../typescript/creating-routes in guide/upgrading.asciidoc
warn Broken cross reference ../../v14/flow/migration/1-migrating-v8-v10 in guide/upgrading.asciidoc
warn Broken cross reference ../../v14/flow/v14-migration/v14-migration-guide in guide/upgrading.asciidoc
warn Broken cross reference ../../guide/installing/installing-overview in guide/start/gradle.asciidoc
warn Broken cross reference ../../guide/production/mode in guide/start/gradle.asciidoc
warn Broken cross reference ../../guide/production/mode in guide/start/gradle.asciidoc
warn Broken cross reference designer-installing-eclipse in tools/designer/getting-started/setting-up-your-environment.asciidoc
warn Broken cross reference ../../../ds/foundation/size-space/ in tools/designer/using-designer/layout.asciidoc
warn Broken cross reference {guide}/designer/getting-started/build-your-main-view in tools/designer/using-designer/java.asciidoc
warn Broken internal reference ../../flow/templates/template-components in tools/designer/using-designer/java.asciidoc
warn Broken internal reference {guide}/flow/templates/template-bindings in tools/designer/using-designer/java.asciidoc
warn Broken cross reference ../../../guide/production/mode in tools/mpr/configuration/production-mode.asciidoc
warn Broken cross reference ../../../guide/upgrading/v8-upgrade/routing-navigation in
tools/mpr/introduction/5-adding-legacy-components.asciidoc
warn Broken cross reference ../../../flow/routing/routing-overview in tools/mpr/introduction/5-adding-legacy-components.asciidoc
warn Broken internal reference 3-legacy-uis in tools/mpr/introduction/3-spring-boot.asciidoc
warn Broken cross reference ../../../flow/spring/spring-basic in tools/mpr/introduction/3-spring-boot.asciidoc
warn Broken cross reference step-3-navigator in tools/mpr/introduction/3-spring-boot.asciidoc
warn Broken internal reference 3-legacy-uis in tools/mpr/introduction/3-no-framework.asciidoc
warn Broken internal reference 3-legacy-uis in tools/mpr/introduction/3-navigator.asciidoc
warn Broken cross reference ../../../flow/routing/routing-lifecycle in tools/mpr/introduction/3-navigator.asciidoc
warn Broken internal reference step-3-legacy-uis in tools/mpr/introduction/3-cdi.asciidoc
warn Broken cross reference step-3-navigator in tools/mpr/introduction/3-cdi.asciidoc
warn Broken cross reference introduction/step-1-upgrade-guide in tools/mpr/overview.asciidoc
warn Broken cross reference configuration/mode in tools/mpr/overview.asciidoc
warn Broken cross reference dummy/../testbench-maintainable-tests-using-page-objects in tools/testbench/getting-started.asciidoc
warn Broken cross reference dummy/../testbench-running-test-on-multiple-browsers in tools/testbench/ci-server.asciidoc
warn <stdin>: SVG does not exist or cannot be read: /Users/jouni/Documents/dev/docs/articles/_images/testbenchicon.svg

Broken links in Fusion Quick Start Tutorial

The link to "Configuring Security" in Fusion Quick Start Tutorial isn't working.

(It links to https://vaadin.com/docs-beta/latest/fusion/quick-start-tutorial/#configuring-security whereas it should probably link to https://vaadin.com/docs-beta/latest/fusion/security/fusion-security-configuring/)

Convert explicit links to cross references

Check all articles for explicit links that point to vaadin.com/docs/* and convert them to cross references.

Update RichTextEditor examples to document Quill delta structure

Broken links in Fusion "Configuring Security"

Two links in https://vaadin.com/docs-beta/latest/fusion/security/fusion-security-configuring/ are not working:

Adding a Login Form with Spring Security
Configuring Servlet-Container Authentication

The dom-repeat example is broken

The example at https://vaadin.com/docs-beta/v14/flow/polymer-templates/tutorial-template-list-bindings/ doesn't work because of this bug: Polymer/polymer#4135

The workaround is to use <template is="dom-repeat" items="{{employees}}">

Group icons in the demo by category

The icons should be grouped by category (as defined in https://github.com/vaadin/vaadin-icons/blob/master/assets/vaadin-font-icons.json) for easier browsing.

Spring MVC example is confusing

The example for Spring MVC configuration in the documentation looks like 1 class

And it can result to one class:

public class SampleWebAppInitializer extends VaadinMVCWebAppInitializer {

@Override
protected Collection<Class<?>> getConfigurationClasses() {
return Collections.singletonList(
SampleConfiguration.class);
}

@Configuration
@ComponentScan
@PropertySource("classpath:application.properties")
public class SampleConfiguration {

}
}

With this code, the application is not working:
org.springframework.beans.factory.NoSuchBeanDefinitionException: No qualifying bean of type

Missing code example include

error: docs/articles/flow/application/routing-navigation.asciidoc, line 28 - include file not found: docs/src/main/java/com/vaadin/demo/flow/routing/LoginScreen.java

Set up alex-linter GitHub action

Options:

HorizontalLayout with spacing, margin and expand is too wide

HorizontalLayout formLayout = new HorizontalLayout();
formLayout.setWidth("100%");
formLayout.setMargin(true);
formLayout.setSpacing(true);
TextField taskField = new TextField();
Button addButton = new Button("Add");
formLayout.add(taskField, addButton);
formLayout.expand(taskField);

Leads to the layout being approx margin + padding too wide:

Flow component version links are broken

We need to decide what to do with the version number link that goes to the Flow component GitHub repo release notes.

Examples how to sort and filter grid items when using a data provider

Add a link to Vaadin CRUD component page from Grid “Crud Demos” page

Once we have a release visible on vaadin.com, we should add a link to that from https://vaadin.com/components/vaadin-grid/html-examples/grid-crud-demos

Installation / package information?

We might want to include info on packages and installation, for developers who are not using the full platform dependencies.

E.g. Directory has this:

and

While current component pages have:

and

Charts configuration docs for DATETIME axis should use Instant instead of Date

The Charts configuration documentation page says:

DATETIME
Enables date/time mode in the axis. The date/time values are expected to be given either as a Date object or in milliseconds since the Java (or Unix) date epoch on January 1st 1970 at 00:00:00 GMT. You can get the millisecond representation of Java Date with getTime().

However, Date type has been deprecated for quite a long time. While it will still work, there is a new possibility that should probably be used, which is Instant (this is already indicated by the setX(Instant) method).

Set up code formatter and linter

To avoid unnecessary nitpicking in code reviews, set up a code formatter(s) and linters.

TypeScript, HTML, CSS
Java

List requirements/recommendations of web components that can be integrated with Flow

People have hard time figuring out what are the requirements for (web) components they want to create a Flow integration for.

This forum thread (and articles linked from it) contains a lot of good information that should be formulated to our official documentation:
https://vaadin.com/forum/thread/18472547/how-to-find-a-web-component-usable-with-vaadin

Remove section prefix from filenames

Add unicodes to Vaadin icons demo

The example page should list the unicode value of each icon in the font.

Here’s an example from the old marketing website:

The demos at vaadin.com are confusing as they contain "magic methods"

The component demo at https://vaadin.com/components/vaadin-ordered-layout/java-examples/verticallayout contains a lot of methods that are not defined for end users. Those reading the documentation should have access to those, so that examples can be easily copy-pasted to developers own IDE.

Add example how to use grid with the dataProvider

I cannot find any example on how to realize an infinite (remote) scrolling with the new dataprovider component.
I found only old examples, here and there, and the closest one provided with the grid is too simple to reach this important goal. I mean: surely it's not only me to need such a behavior...
I tried modifying the examples, but I get 'repeating' tiles (every group of rows is always the same!) and I don't know how to implement a proper 'stop' condition, when reaching the end of the dataset.
I would like a solution where I don't have to ask explicitly the size of the dataset upfront...
Thank you!

Live examples missing imports for Web Components

The examples on the page https://vaadin.com/docs-beta/latest/flow/application/application-events/ don't have ts files with imports of the required Web Components for the Flow counterparts

Remove section article listings from Flow Overview

Instead of listing all articles within the section, describe them sections (as it was in the V8 print edition).

Broken link found (https://docs.google.com/forms/d/e/1FAIpQLScn4gtQzGxMDusU6n6UTR_pjghTkyFsNQij_Bb2NqJgiyNMlw/viewform?usp=pp_url&entry.1307305669=undefined)

Broken link found

Broken Link Checker found a broken link on https://vaadin.com/docs-beta/latest/

Target: https://docs.google.com/forms/d/e/1FAIpQLScn4gtQzGxMDusU6n6UTR_pjghTkyFsNQij_Bb2NqJgiyNMlw/viewform?usp=pp_url&entry.1307305669=undefined

HTTP_503

View Actions Results

Broken link found (designer/getting-started/designer-overview/)

Broken link found

Broken Link Checker found a broken link on https://vaadin.com/docs-beta/latest/

Target: designer/getting-started/designer-overview/

HTTP_404

View Actions Results

Add how to set Chart series colors to "CSS Styling" docs page

https://github.com/vaadin/vaadin-charts-flow/blob/master/documentation/java-api/css-styling.asciidoc this page should have info about how to set the chart colors using Java API (so that it is findable via https://vaadin.com/docs/v14/charts/java-api/css-styling.html).

The colors can be set via CSS custom properties --vaadin-charts-color-{n} but afaik those are currently documented only here: https://vaadin.com/components/vaadin-charts/html-api/elements/Vaadin.ChartElement (see "Setting colors").

Maybe we could even link to the above HTML API docs page for more info but it should be pretty straight forward to at least show how to set those CSS variables with the Java API for low hanging improvement.

Create demo for using Icons/tooltips in TreeGrid

We have the API but no demo for this feature.

Add examples of configuring CRUD editor max-height and max-width

When editor is displayed below the grid it is too small.
Proposals:

Set min-height
Use as much space as it needed for the form, use up to ~40% to see at least several editor rows by default.

Automate updating the Vaadin dependency version to the latest

For the latest and v14 documentation branches, consider using the Versions Maven plugin, which allows CI servers to easily update the Vaadin version to latest.

Here’s one article explaining how to use it: https://www.baeldung.com/maven-dependency-latest-version

The benefit would be that documentation is always using the latest version (could be stable or pre-release, depends on what we want), and there wouldn’t be a need for anyone to manually keep updating it.

If we do this, we should make sure that whatever CI scripts we have running will also fail the deployment of docs-app if the Maven build of docs fails (i.e. have the Maven build precede the docs-app build). This is probably already the case (see https://github.com/vaadin/docs-app/pull/164). See #69 as well.

Drag&Drop code example for TreeGrid

I have noticed that there is no code example for drag&drop on a TreeGrid in the docs. So I thought I would share my complete proof-of-concept view featuring two TreeGrids where items can be dragged between them. Please feel free to further adapt or finetune this for potential usage as a code example in the docs.

I tried to adapt the d&d example code for Grid for a TreeGrid and have stumbled over several things that are more complicated than for a simple Grid. Among those are Checking if the dragged item or any of its descendants is already in the target TreeGrid, adding dragged items as child of the dropTarget, removing dragged items from their parent, and getting the itemlist from the dataprovider of a treegrid.

Edit: By setting GridDropMode to ON_TOP_OR_BETWEEN, and checking the GridDropLocation in the dropEvent, it is possible to either add the draggedItem as root-item in the target treegrid or add it as child of an existing item in the target treegrid. updated the demo gif accordingly

demo gif of this View

@Route("treegrid-dnd")
public class TreeGridDNDView extends VerticalLayout {
    private Foo draggedItem = null;
    private Grid<Foo> dragSource = null;
    private int globalFooSeq = 0;

    public TreeGridDNDView(){
        add(new H1("TreeGrid Drag&Drop View"));
        SplitLayout splitLayout = new SplitLayout();
        splitLayout.setSizeFull();

        Set<Foo> primaryRootItems = mockTreeGridData();
        splitLayout.addToPrimary(prepareTreeGrid(primaryRootItems, true));

        Set<Foo> secondaryRootItems = mockTreeGridData();
        splitLayout.addToSecondary(prepareTreeGrid(secondaryRootItems, true));

        add(splitLayout);
    }

    private TreeGrid<Foo> prepareTreeGrid(Set<Foo> rootItems, boolean removeFromSouce) {
        TreeGrid<Foo> treeGrid = new TreeGrid<>();
        treeGrid.setItems(rootItems, Foo::getChildren);
        Grid.Column<Foo> hierarchyColumn = treeGrid.addHierarchyColumn(Foo::getName).setHeader("Name");
        treeGrid.addColumn(Foo::getChildrenCount).setHeader("Direct Children Count");
        treeGrid.addColumn(Foo::getChildrenCountRecursive).setHeader("Recursive Children Count");

        treeGrid.sort(Collections.singletonList(new GridSortOrder<>(hierarchyColumn, SortDirection.ASCENDING)));
        treeGrid.setHeight("800px");

        prepareDragNDrop(treeGrid, removeFromSouce);

        return treeGrid;
    }

    private void prepareDragNDrop(TreeGrid<Foo> treeGrid, boolean removeFromSource) {
        treeGrid.setRowsDraggable(true);
        treeGrid.setDropMode(GridDropMode.ON_TOP_OR_BETWEEN);
        treeGrid.addDragStartListener(event -> {
            draggedItem = event.getDraggedItems().get(0);
            dragSource = event.getSource();
        });
        treeGrid.addDragEndListener(event -> {
            draggedItem = null;
            dragSource = null;
        });
        treeGrid.addDropListener(event -> {
            // check if the draggedItem or its descendants is already in the target treegrid
            // get all items of the target-treegrid recursively (not only root-items)
            List<Foo> targetRootItemsUnmodifiable = ((TreeDataProvider<Foo>) treeGrid.getDataProvider()).getTreeData().getRootItems();
            Set<Foo> targetRootItems = new HashSet<>(targetRootItemsUnmodifiable);
            Set<Foo> targetItemsWithDescendants = getAllItemsDescendants(targetRootItems);

            // get all descendants of the dragged item recursivley
            Set<Foo> draggedItemDescendants = new HashSet<>();
            draggedItemDescendants.add(draggedItem);
            draggedItemDescendants = getAllItemsDescendants(draggedItemDescendants);

            // compare descendants from draggedItem with all items from target-treegrid
            boolean alreadyPresent = false;
            for (Foo draggedItemDescendant : draggedItemDescendants) {
                if(targetItemsWithDescendants.contains(draggedItemDescendant)){
                    alreadyPresent = true;
                }
            }

            if(alreadyPresent){
                Notification.show("This item (or a descendant thereof) is already in the target grid. Nothing is going to happen.");
            } else {
                // remove dragged item from source-treegrid
                if(removeFromSource && dragSource instanceof TreeGrid) {
                    List<Foo> sourceRootItemsUnmodifiable = ((TreeDataProvider<Foo>) dragSource.getDataProvider()).getTreeData().getRootItems();
                    List<Foo> sourceRootItems = new ArrayList<>(sourceRootItemsUnmodifiable);

                    if(sourceRootItems.contains(draggedItem)) {
                        sourceRootItems.remove(draggedItem);
                    } else {
                        // remove from parent bean
                        draggedItem.getParent().removeChild(draggedItem);
                    }
                    // refresh source treegrid
                    ((TreeGrid<Foo>)dragSource).setItems(sourceRootItems, Foo::getChildren);
                    dragSource.getDataProvider().refreshAll();
                }

                // add draggedItem in target treegrid
                // depending on gridDropMode, it will be added as root-item, or as child of the dropTarget
                if(event.getDropLocation().equals(GridDropLocation.ON_TOP)){
                    // add draggedItem as child of dropTarget
                    Optional<Foo> dropTarget = event.getDropTargetItem();
                    dropTarget.ifPresent(foo -> foo.addChild(draggedItem));
                } else {
                    // add draggedItem as root-item to target treegrid
                    targetRootItems.add(draggedItem);
                }
                // refresh target treegrid
                treeGrid.setItems(targetRootItems, Foo::getChildren);
                treeGrid.getDataProvider().refreshAll();
            }
        });
    }

     private Set<Foo> getAllItemsDescendants(Set<Foo> viewEntries) {
         Set<Foo> allItemsRecursive = new HashSet<>();
         viewEntries.forEach(entity -> {
             allItemsRecursive.add(entity);
             allItemsRecursive.addAll(getAllItemsDescendants(entity.getChildren()));
         });
         return allItemsRecursive;
     }

    //creates a list of 10 root-items, with each 2 children, which again have 5 children
    private Set<Foo> mockTreeGridData() {
        Set<Foo> rootItems= new HashSet<>();
        for (int i = 1; i <= 10; i++) {
            globalFooSeq++;
            Foo rootFoo = new Foo(String.format("Foo - %d", globalFooSeq));
            for (int j = 1; j <= 2; j++) {
                String secondLevelFooName = String.format("Foo - %d.%d", globalFooSeq, j);
                Foo secondLevelFoo = new Foo(secondLevelFooName);
                for (int k = 1; k <= 5; k++) {
                    String thirdLevelName = String.format("Foo - %d.%d.%d", globalFooSeq, j, k);
                    Foo thirdLevelFoo = new Foo(thirdLevelName);
                    secondLevelFoo.addChild(thirdLevelFoo);
                }
                rootFoo.addChild(secondLevelFoo);
            }
            rootItems.add(rootFoo);
        }
        return rootItems;
    }

    public class Foo {
        private String name;
        private Set<Foo> children = new HashSet<>();
        private Foo parent = null;
        
        public Foo(String name){
            this.name = name;
        }
        
        public String getName(){
            return name;
        }
        
        public Set<Foo> getChildren(){
            return children;
        }

        public void addChild(Foo child){
            child.setParent(this);
            children.add(child);
        }

        public void removeChild(Foo child){
            child.setParent(null);
            children.remove(child);
        }

        public void setParent(Foo parent){
            this.parent = parent;
        }

        public Foo getParent(){
            return parent;
        }

        public int getChildrenCount(){
            return getChildren().size();
        }

        public int getChildrenCountRecursive(){
            int count = 0;
            for (Foo child : getChildren()) {
                count++;
                count += child.getChildrenCountRecursive();
            }
            return count;
        }
    }
}

Validation build check for Java examples

Have PR check to verify that the build works, that all Java code examples compile. Would be nice to check that there are no duplicate @Route configurations as well (as those cause all component examples to not work).

Complete the "Security" section of the Fusion docs

When looking for security-related documentation for Vaadin Fusion, I would like the the Security Overview page to include the same content as the matching Security Overview page for Flow.

Specifically, the security section of the Fusion docs should cover the following topics:

Security in Vaadin Applications
Gives an introduction to the Vaadin Fusion security architecture and how it works in practice. (Where and how does it determine if a user has access? Where does the auth info come from?) Further, release and security practices in developing and releasing Vaadin products are described (How would I replace the default Spring Security setup with something else? Which classes can I provide my own implementations for, and how?)
Best Practices
Describes various best practices for configuring access control for back-end endpoints, authentication with Spring Security, access to the user authentication data.
Common Vulnerabilities
Describes common vulnerabilities such as SQL injections, cross-site request forgeries (CSRF/XSRF), cross-site scripting (XSS), and so forth.

For each new Fusion-focused article consider how to unify / align / cross-reference it with the corresponding Flow article to avoid repeating the same text in two places.

Add a light/dark palette switcher that can be used for demos

IMO, we should show the dark palette also on the demo pages.

This could be custom element, which imports vaadin-valo-styles/color.html and includes the valo-color style module for the demo pages, and has a native select for switching between “Light” and “Dark”, which sets the theme="dark" attribute on the demo-snippet elements (and possibly persists that setting in local storage so the user can browse multiple demo pages with the dark palette).

Grid performance demo with big data is missing

One of important vaadin-grid's features is performance. We need to demonstrate it.

The demo example of big data with maximum features enabled - filtering, sorting, column reordering, etc. (here's ag-grid's demo: https://www.ag-grid.com/example.php#/performance/1)

VaadinServletConfiguration is deprecated and will be removed in 6.0 Flow. The docs should be updated.

The replacement for VaadinServletConfiguration should be described since it's deprecated and is going to be removed in
6.0.

vaadin / docs Goto Github PK

docs's Introduction

Vaadin documentation

Contents

articles

frontend

src

scripts

.github

versions.json

docs's People

Contributors

Stargazers

Watchers

Forkers

docs's Issues

Broken link found

Use absolute references

Broken link found

Broken link found

Recommend Projects

Recommend Topics

Recommend Org

`articles`

`frontend`

`src`

`scripts`

`.github`

`versions.json`