From b37f61f8540ff24ea0c0fe3ad9a6acdada82e175 Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Wed, 14 Aug 2024 12:31:57 +0300 Subject: [PATCH 1/2] docs: document FormLayout style properties (#3573) * docs: document FormLayout style properties * change order of table rows * alternative wording * Update articles/components/form-layout/index.adoc * simplify wording * limit since to only Flow * Update articles/components/form-layout/index.adoc Co-authored-by: Jouni Koivuviita * Editing changed text and some minor items. * Full editing of document touched. * Second pass at full editing of document touched. --------- Co-authored-by: Jouni Koivuviita Co-authored-by: russelljtdyer <6652767+russelljtdyer@users.noreply.github.com> --- articles/components/form-layout/index.adoc | 70 +++++++++++++------ .../component/formlayout/form-layout-side.ts | 2 +- .../formlayout/react/form-layout-side.tsx | 2 +- .../component/formlayout/FormLayoutSide.java | 1 + 4 files changed, 53 insertions(+), 22 deletions(-) diff --git a/articles/components/form-layout/index.adoc b/articles/components/form-layout/index.adoc index f69cdab8c1..c3a914a3ba 100644 --- a/articles/components/form-layout/index.adoc +++ b/articles/components/form-layout/index.adoc @@ -1,7 +1,7 @@ --- tab-title: Usage title: Form Layout -description: Form Layout allows you to build responsive forms with multiple columns, and to position input labels above or to the side of the input. +description: Using Form Layout to build responsive forms with multiple columns and better positioned input labels. page-links: - 'API: https://cdn.vaadin.com/vaadin-web-components/{moduleNpmVersion:@vaadin/form-layout}/#/elements/vaadin-form-layout[TypeScript] / https://vaadin.com/api/platform/{moduleMavenVersion:com.vaadin:vaadin}/com/vaadin/flow/component/formlayout/FormLayout.html[Java]' - 'Source: https://github.com/vaadin/web-components/tree/v{moduleNpmVersion:@vaadin/form-layout}/packages/form-layout[TypeScript] / https://github.com/vaadin/flow-components/tree/{moduleMavenVersion:com.vaadin:vaadin}/vaadin-form-layout-flow-parent[Java]' @@ -39,16 +39,15 @@ include::{root}/frontend/demo/component/formlayout/react/form-layout-basic.tsx[r endif::[] -- + == Columns -By default, Form Layout has two columns, meaning it displays two input fields per line. When the layout width is smaller, it adjusts to a single-column. +By default, Form Layout has two columns: it displays two input fields per line. When the layout width is smaller, it adjusts to a single-column. -=== Custom Layout -You can define how many columns Form Layout should use based on the screen width. +=== Custom Layout -[IMPORTANT] -Use the draggable split handle to resize Form Layout's available space and to test its responsiveness. +You can define how many columns that Form Layout should use based on the screen width. Use the draggable split handle to resize Form Layout's available space and to test its responsiveness. [.example] -- @@ -75,16 +74,14 @@ include::{root}/frontend/demo/component/formlayout/react/form-layout-custom-layo endif::[] -- -A single-column layout is preferable to a multi-column one. A multi-column layout can be prone to confusion and misinterpretation by the user. - -However, related fields can be placed in a line without confusion, typically. Examples of this would be first and last name, address fields such as postal code and city, and ranged input for dates, time, and currency. +A single-column layout is preferable to a multi-column layout. A multi-column layout can be prone to confusion and misinterpretation by the user. However, related fields placed in a line are typically understandable. Examples of this would be first and last name, address fields such as city and postal code, and ranged input for dates, time, and price or cost. === Column Span When using a multi-column layout, you can define a `colspan` for each component. The `colspan` determines how many columns a component extends or stretches across. -For example, if you have a Form Layout with three columns and a component's `colspan` is set to 3, it takes up the entire width of the Form Layout. +For example, if you have a Form Layout with three columns and a component's `colspan` is set to 3, it'll therefore take the entire width of the Form Layout. [.example] -- @@ -111,23 +108,26 @@ include::{root}/frontend/demo/component/formlayout/react/form-layout-colspan.tsx endif::[] -- + == Label Position -Input fields' built-in labels are positioned above the input. Form Layout supports side-positioned labels, provided they are wrapped in Form Items and the label position is set to `aside`. +The built-in labels for input fields are positioned above the input. Form Layout supports side-positioned labels, provided they're wrapped in Form Items and the label position is set to `aside`. The only reason for wrapping labels in Form Items is to put the labels to the side of the input. + === Top -Users complete forms that have top-positioned labels more quickly because they provide a consistent scanning pattern -- top-down, as opposed to zigzag -- while minimizing the distance between the label and input. +Users complete forms that have top-positioned labels more quickly because they provide a consistent scanning pattern -- top-down, as opposed to zigzag -- while minimizing the distance between the label and input field. Top-positioned labels are also less prone to causing layout issues due to variable label lengths, which happens usually in multilingual applications. However, they do result in vertically longer forms. This is why <<#sectioning,sectioning>> is important. + === Side Side-positioned labels help reduce a form's total height. This is especially useful for longer forms and when vertical space is limited. -Labels positioned on the side are also often used when there is a need to compare numeric data. +The positioning of labels on the side is also useful when there's a need to compare numeric data. [.example] -- @@ -154,14 +154,38 @@ include::{root}/frontend/demo/component/formlayout/react/form-layout-side.tsx[re endif::[] -- -Aim for similar-length labels to keep the distance between the labels and input fields consistent. Inconsistent spacing can slow the user in completing the form. +Aim for similar-length labels to keep the distance consistent between the labels and the input fields. Inconsistent spacing can slow the user in completing a form. + +Forms that use this position require more horizontal space, which isn't always ideal in narrow forms. Instead, configure Form Layout to use top-positioned labels when the form has a narrow width. -Forms that use this position require more horizontal space, which isn't always ideal in narrow forms. It's recommended to configure Form Layout to use top-positioned labels when the form has a narrow width. +The width of side-positioned labels can be adjusted using the `--vaadin-form-item-label-width` CSS property on the Form Layout element, or with the [since:com.vaadin:vaadin@V24.5]#[methodname]`setLabelWidth()` method# on the [classname]`FormLayout` instance in Flow. === Responsive Label Position -Similar to the number of columns, the label position is configurable based on the width of the layout. For example, you can position the labels to the side when there is ample horizontal space available, and on top for narrower screens. +Similar to the number of columns, the label position is configurable based on the width of the layout. For example, you can position the labels to the side when there's ample horizontal space available, and on top for narrower screens. + + +== Spacing + +Form Layout allows you to configure the spacing between columns, rows, and between the label and input field when labels are positioned on the side. + +To configure the spacing, use the following CSS properties on the Form Layout element: + +[.example] + +|=== +| Property | Default Value + +| `--vaadin-form-layout-column-spacing` +| `var(--lumo-space-l)` + +| `--vaadin-form-item-row-spacing` +| `1em` + +| `--vaadin-form-item-label-spacing` +| `1em` +|=== == Native Input Fields @@ -193,6 +217,7 @@ include::{root}/frontend/demo/component/formlayout/react/form-layout-native-inpu endif::[] -- + == Multiple Fields Form Item only supports placing a single field inside. Where you need to place multiple fields, <<../custom-field#,Custom Field>> should be used as a wrapper: @@ -222,21 +247,26 @@ include::{root}/frontend/demo/component/formlayout/react/form-layout-custom-fiel endif::[] -- -Keeping fields in individual Form Items, however, is preferable. Wrapped fields can be hard to distinguish visually since they usually have no individual label except for a placeholder, which is only visible when the field has no value. +Keeping fields in individual Form Items is preferable. Wrapped fields can be hard to distinguish visually since they usually have no individual label except for a placeholder, which is only visible when the field has no value. + == Best Practices +With regards to developing with Form Layout, this section provides some suggestions for better user experiences. + + === Sectioning Longer forms should be split into smaller, more manageable and user-friendly sections using sub-headings, <<../tabs#,Tabs>>, <<../details#,Details>> or separate views when possible. Each section should consist of related content and fields. + === Button Placement Use the following guidelines for Button placement in forms: -* Buttons should be placed below the form with which they are associated. -* Buttons should be aligned to the left. -* Primary action should be placed first, followed by other actions, in order of importance. +- Buttons should be placed below the form with which they're associated. +- Buttons should be aligned to the left. +- Primary action should be placed first, followed by other actions, in order of importance. For more information, see the <<../button#,Button documentation>>. diff --git a/frontend/demo/component/formlayout/form-layout-side.ts b/frontend/demo/component/formlayout/form-layout-side.ts index f6cc3b589d..1387e1a4e1 100644 --- a/frontend/demo/component/formlayout/form-layout-side.ts +++ b/frontend/demo/component/formlayout/form-layout-side.ts @@ -19,7 +19,7 @@ export class Example extends LitElement { protected override render() { return html` - + diff --git a/frontend/demo/component/formlayout/react/form-layout-side.tsx b/frontend/demo/component/formlayout/react/form-layout-side.tsx index 71aeb22776..027e65d16b 100644 --- a/frontend/demo/component/formlayout/react/form-layout-side.tsx +++ b/frontend/demo/component/formlayout/react/form-layout-side.tsx @@ -7,7 +7,7 @@ import { TextField } from '@vaadin/react-components/TextField.js'; function Example() { return ( // tag::snippet[] - + {/* Wrap fields into form items, which displays labels on the side by default */} diff --git a/src/main/java/com/vaadin/demo/component/formlayout/FormLayoutSide.java b/src/main/java/com/vaadin/demo/component/formlayout/FormLayoutSide.java index 0664a06b51..62b0b05b80 100644 --- a/src/main/java/com/vaadin/demo/component/formlayout/FormLayoutSide.java +++ b/src/main/java/com/vaadin/demo/component/formlayout/FormLayoutSide.java @@ -22,6 +22,7 @@ public FormLayoutSide() { FormLayout formLayout = new FormLayout(); // tag::snippet[] + formLayout.setLabelWidth("60px"); // Use addFormItem instead of add, to wrap fields into form items, // which displays labels on the side by default formLayout.addFormItem(revenue, "Revenue"); From 6fffa3685db6b99576b3a94e04f0a5a76284c19e Mon Sep 17 00:00:00 2001 From: David Sosa <76832183+sosa-vaadin@users.noreply.github.com> Date: Wed, 14 Aug 2024 13:06:00 +0300 Subject: [PATCH 2/2] Remove step no longer needed to deploy Vaadin app to Control Center (#3589) * remove instruction to add a boostrap.yml file in Vaadin apps to be deployed through Control Center * Add title for admonition * replace boostrap file warning with application name note * add example Dockerfile and some rephrasing to prevent lint warnings --------- Co-authored-by: Jouni Koivuviita --- .../application-discovery/index.adoc | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/articles/control-center/application-discovery/index.adoc b/articles/control-center/application-discovery/index.adoc index 51c15bf707..c9f2378e48 100644 --- a/articles/control-center/application-discovery/index.adoc +++ b/articles/control-center/application-discovery/index.adoc @@ -23,26 +23,25 @@ First, you must add the `control-center-starter` dependency to your Vaadin appli ---- -Next, create a [filename]`bootstrap.yaml` file with the application name and Kubernetes reload enabled. +Then build a Docker image of your application with an appropriate [filename]`Dockerfile` file. -[source,yaml] +[source,docker] ---- -spring: - application: - name: control-center-application - cloud: - kubernetes: - reload: - enabled: true +FROM eclipse-temurin:21-jre +COPY target/*.jar app.jar +EXPOSE 8080 +ENTRYPOINT ["java", "-jar", "/app.jar"] ---- -Then build a docker image of your application with an appropriate [filename]`Dockerfile` file. - [source,shell] ---- docker build -t vaadin/example:0.1.1 . ---- +.Potential Side-Effects +[NOTE] +Control Center sets the `SPRING_APPLICATION_NAME` environment variable with the name chosen in the deployment dialog and that might override any application name set in the application's properties. + == Deploy & Adopt a Vaadin Application