Skip to main content

Dialog

Shadow bbj-dialog
Java API

The DWCJ's dialog component is built to allow a developer to quickly and easily display a dialog on their application, for instances such as a login menu or information box.

The component is built with three sections, each of which are Panel components: the header, the content, and the footer.

Show Code

Usages

  1. User Feedback and Confirmation: Dialog components are often used to provide feedback or ask for user confirmation. They can display various important pieces of feedback to a user, such as:
  • Success messages
  • Error alerts
  • Confirmation submissions
  1. Form Input and Editing: You can use dialogs to collect user input or allow them to edit information in a controlled and focused manner. For example, a dialog can pop up to edit user profile details or complete a multi-step form.

  2. Contextual Information: Displaying additional contextual information or tooltips in a dialog can help users understand complex features or data. Dialogs can provide in-depth explanations, charts, or help documentation.

  3. Image and Media Previews: When users need to view pieces of media, a Dialog can be used to show larger previews or galleries, such as when interacting with:

  • Images
  • Videos
  • Other media

Constructors

The Dialog can be constructed using the default Dialog() constructor. Once the object has been instantiated, call the show() method on the object itself to display the dialog.

Backdrop and Blur

By enabling the backdrop attribute of the DWCJ's Dialog component, a backdrop will be displayed behind the Dialog. Additionally, when enabled, the Dialog's blurred attribute will blur the backdrop of the Dialog. Modifying these settings can help users by providing depths, visual hierarchy, and context, leading to more clear guidance for a user.

Show Code

Closing the Dialog

The Dialog supports multiple cancellation methods for closure of the component: hitting the ESC key, clicking outside of the Dialog, or using the hide() method. The first two properties are customizable via their respective methods: setCancelOnEscKey() and setCancelOnOutsideClick(). The hide() method allows for the Dialog to be closed programmatically, such as by clicking a button on the Dialog after saving data. A method to quickly enable or disable users' ability to close the Dialog, setClosable() will prevent or allow both escape and click closure of the Dialog.

Show Code

Auto-Focus

When enabled, auto-focus will automatically give focus to the first element within the dialog that can be focused. This is useful in helping to direct the attention of users, and is customizable via the setAutoFocus() method.

Show Code

Draggable

The Dialog has built in functionality to be draggable, allowing the user to relocate the Dialog window by clicking and dragging. The position of the Dialog can be manipulated from any of the fields within it: the header, content or footer.

Snap to Edge

It is also possible to calibrate this behavior to snap to the edge of the screen, meaning the Dialog will automatically align itself with the edge of the display when released from its drag and drop date. Snapping can be changed via the setSnapToEdge() method. The setSnapThreshold() takes a number of pixels, which will set how far the Dialog should be from the sides of the screen before it will automatically snap to the edges.

Show Code

Positioning

The dialog's position can be manipulated using the built-in setPosx() and setPosy() methods. These methods take a string argument which can represent any applicable CSS unit of length, such as pixels or view height/width. A list of these measurements can be found at this link.

Show Code

Vertical Alignment

In addition to manual assignment of a dialog's X and Y position, it is possible to use the dialog's built-in enum class to align the Dialog. There are three possible values, TOP, CENTER and BOTTOM, each of which can be used with the setAlignment() method.

Show Code

Full Screen and Breakpoints

The Dialog can be set to enter full screen mode. When full screen is enabled, the Dialog cannot be moved or positioned. This mode can be manipulated with the breakpoint attribute of the Dialog. The breakpoint is a media query which components when the Dialog will automatically flip to full screen mode. When the query matches, the Dialog changes to full screen - otherwise it is positioned.

Events

The Dialog class provides methods to add and remove event listeners for the following events:

EventsDescription
An event that is fired when the Dialog is opened.
An event that is fired when the Dialog is closed.

To add an event listener, use the appropriate method:

myDialog.addOpenListener( e -> {
//Executed when the event fires
});

Additional syntactic sugar methods, or aliases, have been added to allow for alternative addition of events by using the on prefix followed by the event, such as:

myDialog.onOpen( e -> {
//Executed when the event fires
});

To remove an event listener, use the appropriate method:

myDialog.removeOpenListener(listener);

Styling

Themes

Dialog components come with

built in for quick styling without the use of CSS. These themes are pre-defined styles that can be applied to buttons to change their appearance and visual presentation. They offer a quick and consistent way to customize the look of buttons throughout an application.

While there are many use cases for each of the various themes, some examples uses are:

  • Danger: Actions with severe consequences, such as clearing filled-out information, or permanently deleting an account/data is represents a good use case for dialogs with the Danger theme.
  • Default: The default theme is appropriate for actions throughout an application that do not require special attention and that are generic, such as toggling a setting.
  • Primary: This theme is appropriate as a main "call-to-action" on a page, such as signing up, saving changes, or continuing to another page.
  • Success: Success themed dialogs are excellent for visualizing successful completion of an element in an application, such as the submission of a form or completion of a sign-up process. The success theme can by programmatically applied once a successful action has been completed.
  • Warning: Warning dialogs are useful to indicate users they are about to perform a potentially risky action, such as when navigating away from a page with unsaved changes. These actions are often less impactful than those that would use the Danger theme.
  • Gray: Good for subtle actions, such as minor settings or actions that are more supplementary to a page, and not part of the main functionality.
  • Info: The Info theme is a good choice to provide clarifying, additional information to a user when pushed.
Show Code

Shadow Parts

These are the various parts of the shadow DOM for the component, which will be required when styling via CSS is desired.

Loading...

Slots

Listed below are the slots available for utilization within the Button component. These slots act as placeholders within the component that control where the children of a customized element should be inserted within the shadow tree.

Loading...

CSS Properties

These are the various CSS properties that are used in the component, with a short description of their use.

Loading...

Reflected Attributes

The reflected attributes of a component will be shown as attributes in the rendered HTML element for the component in the DOM. This means that styling can be applied using these attributes.

Loading...