-
Notifications
You must be signed in to change notification settings - Fork 197
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: enhance dialog component documentation with positioning and siz…
…ing details (#3946) * docs: enhance dialog component documentation with positioning and sizing details * docs: update dialog component documentation to include version-specific positioning and sizing details * Update articles/components/dialog/index.adoc Co-authored-by: Sergey Vinogradov <[email protected]> * Apply suggestions from code review Co-authored-by: Rolf Smeds <[email protected]> * Edited added text and format clean-up of whole document. * Full edit of whole document. * Minor edit. --------- Co-authored-by: Sergey Vinogradov <[email protected]> Co-authored-by: Rolf Smeds <[email protected]> Co-authored-by: Russell J.T. Dyer <[email protected]>
- Loading branch information
4 people
authored
Dec 2, 2024
1 parent
44d51ec
commit 594e55d
Showing
1 changed file
with
103 additions
and
41 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -50,13 +50,15 @@ endif::[] | |
| </style> | ||
| ++++ | ||
|
|
||
|
|
||
| == Structure | ||
|
|
||
| The Dialog component has static header and footer areas, and a scrolling content area between them. | ||
| The header and footer are optional, and automatically hidden if empty and not explicitly enabled. | ||
| The Dialog component has static header and footer areas, and a scrolling content area between them. The header and footer are optional, and are hidden if empty and not explicitly enabled. | ||
|
|
||
|
|
||
| [role="since:com.vaadin:[email protected]"] | ||
| === Header | ||
|
|
||
| The header contains an optional title element, and a slot next to it for custom header content, such as a close button. | ||
|
|
||
| [.example] | ||
|
|
@@ -84,12 +86,11 @@ include::{root}/frontend/demo/component/dialog/react/dialog-header.tsx[render,ta | |
| endif::[] | ||
| -- | ||
|
|
||
|
|
||
| [role="since:com.vaadin:[email protected]"] | ||
| === Footer | ||
| Buttons for closure actions, such as _Save_, _Cancel_, _Delete_, and so on, should be placed in the footer. | ||
| See the <<../button#buttons-in-dialogs,Button>> component for guidelines for the placement of buttons in dialogs. | ||
| Footer content is right-aligned by default. | ||
| Components can be left-aligned by applying a margin: | ||
|
|
||
| Buttons for closure actions (e.g., _Save_, _Cancel_, _Delete_) should be placed in the footer. See the <<../button#buttons-in-dialogs,Button>> component for guidelines for the placement of buttons in Dialogs. Footer content is right-aligned by default. Components can be left-aligned by applying a margin like so: | ||
|
|
||
| [.example] | ||
| -- | ||
|
|
@@ -116,6 +117,7 @@ include::{root}/frontend/demo/component/dialog/react/dialog-footer.tsx[render,ta | |
| endif::[] | ||
| -- | ||
|
|
||
|
|
||
| === Padding | ||
|
|
||
| The content area's built-in padding can be removed by applying the `no-padding` theme variant. | ||
|
|
@@ -145,29 +147,25 @@ include::{root}/frontend/demo/component/dialog/react/dialog-no-padding.tsx[rende | |
| endif::[] | ||
| -- | ||
|
|
||
|
|
||
| == Modality | ||
| A modal dialog blocks the user from interacting with the rest of the user interface while the dialog is open. | ||
| A non-modal dialog, however, doesn't block interaction. | ||
|
|
||
| Dialogs are modal by default. | ||
| A modal dialog blocks the user from interacting with the rest of the user interface while the dialog is open. A non-modal dialog, however, doesn't block interaction. Dialogs are modal by default. | ||
|
|
||
| Use modal dialogs for: | ||
|
|
||
| * displaying important information, like system errors | ||
| * requesting user input as part of a workflow, for example an edit dialog | ||
| * confirmation of irreversible actions, such as deleting data (Confirm Dialog is a convenient alternative for these use cases) | ||
| * breaking out sub-tasks into a separate user interface | ||
| - Displaying important information, like system errors; | ||
| - Requesting user input as part of a workflow, for example an edit dialog; | ||
| - Confirmation of irreversible actions, such as deleting data -- Confirm Dialog is a convenient alternative for these use cases; and | ||
| - Breaking out sub-tasks into a separate user interface. | ||
|
|
||
| ifdef::flow[] | ||
| .Modal parent dialogs in Flow | ||
| .Modal Parent Dialogs in Flow | ||
| [IMPORTANT] | ||
| See the <<Technical>> section for details on the behavior of modal dialogs in Vaadin Flow. | ||
| endif::flow[] | ||
|
|
||
| Use non-modal dialogs: | ||
|
|
||
| * when the user needs access to the content below the dialog | ||
| * for less critical, optional, and/or support tasks | ||
| Use non-modal dialogs when the user needs access to the content below the dialog, and for less critical, optional, or support tasks. | ||
|
|
||
| [.example] | ||
| -- | ||
|
|
@@ -199,19 +197,51 @@ endif::[] | |
|
|
||
| Usually, non-modal dialogs should be draggable, so that the user can move them to access the user interface beneath. | ||
|
|
||
| == Draggable | ||
|
|
||
| == Position | ||
|
|
||
| By default, dialogs open in the center of the viewport. [since:com.vaadin:[email protected]]##A different positioning can be set programmatically##. Dialogs can also be made draggable, allowing the end user to move them around. | ||
|
|
||
| The position of the dialog can be set using the `top` and `left` properties: | ||
|
|
||
| [.example] | ||
| -- | ||
| ifdef::lit[] | ||
| [source,html] | ||
| ---- | ||
| <source-info group="Lit"></source-info> | ||
| <vaadin-dialog top="50px" left="50px">...</vaadin-dialog> | ||
| ---- | ||
| endif::[] | ||
|
|
||
| ifdef::flow[] | ||
| [source,java] | ||
| ---- | ||
| <source-info group="Flow"></source-info> | ||
| Dialog dialog = new Dialog(); | ||
| dialog.setTop("50px"); | ||
| dialog.setLeft("50px"); | ||
| ---- | ||
| endif::[] | ||
|
|
||
| ifdef::react[] | ||
| [source,html] | ||
| ---- | ||
| <source-info group="React"></source-info> | ||
| <Dialog top="50px" left="50px">...</Dialog> | ||
| ---- | ||
| endif::[] | ||
| -- | ||
|
|
||
| === Draggable | ||
|
|
||
| Dialogs can be made draggable, enabling the user to move them around using a pointing device. | ||
|
|
||
| By default, the outer edges of a dialog, as well as the space between its components, can be used to move the dialog around. | ||
|
|
||
| The default areas from which a dialog can be dragged depend on whether the built-in header is used: | ||
| The default areas from which a dialog can be dragged depend on whether the built-in header is used if the built-in header or footer is used: they function as the default drag handles of the dialog. Without the built-in header, any empty space within the dialog functions can be used as a drag handle. | ||
|
|
||
| - If the built-in header or footer is used, they function as the default drag handles of the dialog | ||
| - Without the built-in header, any empty space within the dialog functions as a drag handle | ||
|
|
||
| Any component contained within a dialog can be marked and used as a drag handle by applying the `draggable` class name to it. | ||
| You can choose whether to make the component's content draggable as well, or only the component itself. | ||
| Any component contained within a dialog can be marked and used as a drag handle by applying the `draggable` class name to it. You can choose whether to make the component's content draggable as well, or only the component itself. | ||
|
|
||
| [.example] | ||
| -- | ||
|
|
@@ -242,20 +272,53 @@ include::{root}/frontend/demo/component/dialog/react/dialog-draggable.tsx[render | |
| endif::[] | ||
| -- | ||
|
|
||
| It's recommended to make non-modal dialogs draggable, so that the user can interact with content that might otherwise be obscured by the Dialog. | ||
| For example, a Dialog for taking notes or for adding widgets to a dashboard by dragging can offer a better experience by allowing the user to move the Dialog around. | ||
| Make non-modal dialogs draggable so the user can interact with content that might otherwise be obscured by the Dialog. For example, a Dialog for taking notes or for adding widgets to a dashboard by dragging can offer a better experience by allowing the user to move the Dialog around. | ||
|
|
||
| Modal dialogs don't benefit from being draggable, as their modality curtain (the dark overlay behind the dialog) obscures the underlying user interface. | ||
|
|
||
| == Resizable | ||
|
|
||
| A resizable dialog allows the user to resize the Dialog by dragging from the edges of the Dialog with a pointing device. | ||
| Dialogs aren't resizable by default. | ||
| == Size | ||
|
|
||
| Dialogs containing dynamic content and/or a lot of information, such as complex forms or Grids, may benefit from being resizable, as this offers the user some flexibility with how much data is visible at once. | ||
| It also gives the user control over which part of the underlying user interface is obscured. | ||
| The Dialog size can be set with the width and height on the Dialog itself (__since V24.6 for React and Lit__). You can also set the size of the content of Dialog, whereby the Dialog scales to accommodate it. In both cases, the Dialog can also be made resizable. | ||
|
|
||
| Dialogs that contain very little, or compact, information don't need to be resizable. | ||
| [.example] | ||
| -- | ||
|
|
||
| ifdef::lit[] | ||
| [source,html] | ||
| ---- | ||
| <source-info group="Lit"></source-info> | ||
| <vaadin-dialog width="400px" height="200px">...</vaadin-dialog> | ||
| ---- | ||
| endif::[] | ||
|
|
||
| ifdef::flow[] | ||
| [source,java] | ||
| ---- | ||
| <source-info group="Flow"></source-info> | ||
| Dialog dialog = new Dialog(); | ||
| dialog.setWidth("400px"); | ||
| dialog.setHeight("200px"); | ||
| ---- | ||
| endif::[] | ||
|
|
||
| ifdef::react[] | ||
| [source,html] | ||
| ---- | ||
| <source-info group="React"></source-info> | ||
| <Dialog width="400px" height="200px">...</Dialog> | ||
| ---- | ||
| endif::[] | ||
| -- | ||
|
|
||
|
|
||
| === Resizable | ||
|
|
||
| The Dialog can be configured to allow the end user to resize it by dragging from its edges. | ||
|
|
||
| Dialogs containing dynamic content or plenty of information, such as complex forms or Grids, may benefit from being resizable. This offers the user some flexibility with how much data is visible at once. It also gives the user control over which part of the underlying user interface is obscured. | ||
|
|
||
| Dialogs that contain very little or compact information don't need to be resizable. | ||
|
|
||
| [.example] | ||
| -- | ||
|
|
@@ -282,13 +345,10 @@ include::{root}/frontend/demo/component/dialog/react/dialog-resizable.tsx[render | |
| endif::[] | ||
| -- | ||
|
|
||
| == Closing | ||
|
|
||
| Modal dialogs are closable in three ways: | ||
| == Closing | ||
|
|
||
| . Pressing the kbd:[Esc] key | ||
| . Clicking outside the Dialog | ||
| . Programmatically, for example through the click of a Button | ||
| Modal dialogs are closable in three ways: by pressing the kbd:[Esc] key; clicking outside the Dialog; or programmatically, for example through the click of a Button. | ||
|
|
||
| Providing an explicit button for closing a Dialog is recommended. | ||
|
|
||
|
|
@@ -317,18 +377,19 @@ include::{root}/frontend/demo/component/dialog/react/dialog-closing.tsx[render,t | |
| endif::[] | ||
| -- | ||
|
|
||
|
|
||
| == Best Practices | ||
|
|
||
| === Use Sparingly | ||
|
|
||
| Dialogs are disruptive by nature and should be used sparingly. | ||
| Don't use them to communicate non-essential information, such as success messages like “Logged in”, “Copied”, and so on. | ||
| Instead, use <<../notification#,Notifications>> when appropriate. | ||
| Dialogs are disruptive by nature and should be used sparingly. Don't use them to communicate non-essential information, such as success messages like "Logged in", "Copied", and so on. Instead, use <<../notification#,Notifications>> when appropriate. | ||
|
|
||
|
|
||
| === Button Placement | ||
|
|
||
| See <<../button#buttons-in-dialogs, Buttons in Dialogs>>. | ||
|
|
||
|
|
||
| == Related Components | ||
|
|
||
| |=== | ||
|
|
@@ -341,6 +402,7 @@ See <<../button#buttons-in-dialogs, Buttons in Dialogs>>. | |
|
|
||
| |=== | ||
|
|
||
|
|
||
| ifdef::flow[] | ||
| == Technical | ||
|
|
||
|
|
||