Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DRAFT] chore: Revisions to the List Articles #402

Draft
wants to merge 1 commit into
base: website
Choose a base branch
from
Draft

[DRAFT] chore: Revisions to the List Articles #402

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 11 additions & 33 deletions docs/components/lists/choice-box.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,51 +2,34 @@
sidebar_position: 1
title: ChoiceBox
slug: choicebox
description: A component that provides a dropdown list of predefined options, allowing users to select one option from the list.
---

<DocChip chip='shadow' />

<DocChip chip='name' label="dwc-choicebox" />

<JavadocLink type="foundation" location="com/webforj/component/list/ChoiceBox" top='true'/>

<ParentLink parent="List" />

The `ChoiceBox` component is a user interface element designed to present users with a list of options or choices. Users can select a single option from this list, typically by clicking the `ChoiceBox`, which triggers the display of a dropdown list containing available choices. Users can also interact with the `ChoiceBox` with the arrow keys. When a user makes a selection, the chosen option is then displayed in the `ChoiceBox` button.

## Usages
`ChoiceBox` components are used for various purposes, such as selecting items from a menu, choosing from a list of categories, or picking options from predefined sets. They provide an organized and visually pleasing way for users to make selections, particularly when there are multiple options available. Common usages include:
<ParentLink parent="list" />

1. **User Selection of Options**: The primary purpose of a `ChoiceBox` is to allow users to select a single option from a list. This is valuable in applications that require users to make choices, such as:
- Choosing from a list of categories
- Picking options from predefined sets
The `ChoiceBox` component simplifies form inputs, allows users to adjust preferences from a list of settings, and can be employed for filtering and sorting in apps. It provides an organized and visually pleasing way to make selections when multiple options are available.

2. **Form Inputs**: When designing forms that require users to input specific options, the `ChoiceBox` simplifies the selection process. Whether it's selecting a country, state, or any other option from a predefined list, the `ChoiceBox` streamlines the input process.

3. **Filtering and Sorting**: `ChoiceBox` can be employed for filtering and sorting tasks in applications. Users can choose filter criteria or sorting preferences from a list, facilitating the organization and navigation of data.

4. **Configuration and Settings**: When your application includes settings or configuration options, the `ChoiceBox` provides an intuitive way for users to adjust preferences. Users can pick settings from a list, making it easy to tailor the application to their needs.
The `ChoiceBox` component presents users with a list of options, allowing them to click to display a dropdown of available choices or use arrow keys when the component is in focus. When a user makes a selection, that option is displayed in the `ChoiceBox`.

:::tip
The `ChoiceBox` is intended for use when a preset number of options are available, and custom options should not be allowed or included. If allowing users to enter custom values is desired, use a [`ComboBox`](./combo-box.md) instead
The `ChoiceBox` is designed to provide users with a convenient selection of preset options, ensuring a straightforward decision-making process. For instances where custom values are desired, use a [`ComboBox`](./combo-box.md). If you want to allow users to choose multiple selections, use a [`ListBox`](./list-box.md)
:::

## Dropdown type

Using the <JavadocLink type="foundation" location="com/webforj/component/list/DwcSelectDropdown" code='true' suffix='#setDropdownType(java.lang.String)'>setDropdownType()</JavadocLink> method will assign a value to the `type` attribute of a `ChoiceBox`, and a corresponding value for the `data-dropdown-for` attribute in the dropdown of the `ChoiceBox`. This is helpful for styling, as the dropdown is taken out of its current position in the DOM and relocated to the end of the page body when opened.

<!-- ![example type](../_images/choicebox/type.png)
![example type](../_images/choicebox/type_zoomed.png) -->
This detachment creates a situation where directly targeting the dropdown using CSS or shadow part selectors from the parent component becomes challenging, unless you make use of the dropdown type attribute.

This detachment creates a situation where directly targeting the
dropdown using CSS or shadow part selectors from the parent component becomes challenging, unless you make use of the dropdown type attribute.

In the demo below, the Dropdown type is set and used in the CSS file to select the dropdown and change the background color.
Here's an example of using a Dropdown type in CSS to animate choices while hovering over them:

<ComponentDemo
path='https://demo.webforj.com/webapp/controlsamples/choiceboxdropdowntype?'
javaE='https://raw.githubusercontent.com/webforj/webforj-docs-samples/refs/heads/main/src/main/java/com/webforj/samples/views/lists/choicebox/ChoiceboxDropdownTypeView.java'
javaC='https://raw.githubusercontent.com/webforj/ControlSamples/main/src/main/code_snippets/choicebox/DropdownType.txt'
cssURL='https://raw.githubusercontent.com/webforj/ControlSamples/main/src/main/resources/css/lists/combobox/comboBoxDropDownType.css'
height='250px'
/>
Expand All @@ -56,13 +39,12 @@ height='250px'
By default, the number of rows displayed in the dropdown of a `ChoiceBox` will be increased to fit the content. However, using the <JavadocLink type="foundation" location="com/webforj/component/list/DwcSelectDropdown" code='true' suffix='#setMaxRowCount(int)'>setMaxRowCount()</JavadocLink> method allows for control over how many items are displayed.

:::tip
Using a number that is less than or equal to 0 will result in unsetting this property.
When a number less than or equal to zero is used, the number of rows will automatically adjust to accommodate the content.
:::

<ComponentDemo
path='https://demo.webforj.com/webapp/controlsamples/choiceboxmaxrow?'
javaE='https://raw.githubusercontent.com/webforj/webforj-docs-samples/refs/heads/main/src/main/java/com/webforj/samples/views/lists/choicebox/ChoiceboxMaxRowView.java'
javaC='https://raw.githubusercontent.com/webforj/ControlSamples/main/src/main/code_snippets/choicebox/MaxRow.txt'
height='450px'
/>

Expand Down Expand Up @@ -139,12 +121,8 @@ This component relies on the following components - see the related article for

To ensure an optimal user experience when using the `ChoiceBox` component, consider the following best practices:

1. **Clear and Limited Options**: Keep the list of choices concise where possible, and relevant to the user's task. A `ChoiceBox` is ideal for presenting a clear list of options.

2. **User-Friendly Labels**: Ensure that the displayed labels for each option are user-friendly and self-explanatory. Make sure users can easily understand the purpose of each choice.
- **Clear and Limited Options**: Keep the list of choices concise where possible, and relevant to the user's task. A `ChoiceBox` is ideal for presenting a clear list of options.

3. **Default Selection**: Set a default selection when the ChoiceBox is initially displayed. This ensures a pre-selected option, reducing the number of interactions required to make a choice.
- **Clear Options**: Make the text for each `ListItem` clear and simple so users immediately understand their purpose.

4. **ChoiceBox vs. Other List Components**: A `ChoiceBox` is the best choice if you need to restrict user input to a single choice from a list of predetermined options. Another list component may be better if you need the following behaviors:
- Multiple Selection and display all items at once: [`ListBox`](./list-box.md)
- Allow custom input: [`ComboBox`](./combo-box.md)
- **Default Selection**: Set a default selection when the ChoiceBox is initially displayed. This ensures a pre-selected option, reducing the number of interactions required to make a choice.
50 changes: 15 additions & 35 deletions docs/components/lists/combo-box.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,34 +2,22 @@
sidebar_position: 2
title: ComboBox
slug: combobox
description: A component that combines a dropdown list with an editable text input, allowing users to either select an option from the list or enter a custom value.
---

<DocChip chip='shadow' />

<DocChip chip='name' label="dwc-combobox" />

<JavadocLink type="foundation" location="com/webforj/component/list/ComboBox" top='true'/>

<ParentLink parent="List" />

The `ComboBox` component is a user interface element designed to present users with a list of options or choices, as well as a field for entering their own custom values. Users can select a single option from this list, typically by clicking the `ComboBox`, which triggers the display of a dropdown list containing available choices, or type in a custom value. Users can also interact with the `ComboBox` with the arrow keys. When a user makes a selection, the chosen option is then displayed in the `ComboBox`.

## Usages

The ComboBox component is a versatile input element that combines the features of both a dropdown list and a text input field. It allows users to select items from a predefined list or enter custom values as needed. This section explores common usages of the ComboBox component in various scenarios:
<ParentLink parent="list" />

1. **Product Search and Entry**: Use a ComboBox to implement a product search and entry feature. Users can either select a product from a predefined list or type in a custom product name. This is helpful for applications like e-commerce sites where products are vast and diverse.
The `ComboBox` component is designed to offer users a list of options along with a field for entering custom values. This versatile input seamlessly combines the functionalities of a dropdown list and a text input field, allowing users to either select a single option from the dropdown or enter in their own value as needed.

2. **Tag Selection and Entry**: In applications involving content tagging, a ComboBox can serve as an excellent choice. Users can select from a list of existing tags or add custom tags by typing them. This is useful for organizing and categorizing content. Examples of such tags include:
>- Project Labels: In a project management tool, users can select labels or tags (e.g., "Urgent," "In Progress," "Completed") to categorize tasks or projects, and they can create custom labels as needed.
>- Recipe Ingredients: In a cooking or recipe app, users can select ingredients from a list (e.g., "Tomatoes," "Onions," "Chicken") or add their own ingredients for custom recipes.
>- Location Tags: In a mapping or geotagging application, users can choose predefined location tags (e.g., "Beach," "City," "Park") or create custom tags to mark specific places on a map.
You can include a `ComboBox` in your app for various purposes, such as for selecting a tag, picking an event location, or even conducting product searches on e-commerce sites. Essentially, the `ComboBox` lets you provide users with a set of predefined values while still allowing them to enter their own input when necessary.

3. **Data Entry with Suggested Values**: In data entry forms, a ComboBox can be used to speed up input by providing a list of suggested values based on user input. This helps users enter data accurately and efficiently.

:::tip
The `ComboBox` should be used when users are allowed to enter custom values. If only preset values are desired, use a [`ChoiceBox`](./choice-box.md) instead.
:::
:::tip
The `ComboBox` should be used when users are allowed to enter custom values. If only preset values are desired, use a [`ChoiceBox`](./choice-box.md). If you want to allow users to choose multiple selections, use a [`ListBox`](./list-box.md)
:::

## Custom value

Expand All @@ -38,18 +26,16 @@ Changing the custom value property allows control over whether or not a user is
<ComponentDemo
path='https://demo.webforj.com/webapp/controlsamples/comboboxcustomvalue?'
javaE='https://raw.githubusercontent.com/webforj/webforj-docs-samples/refs/heads/main/src/main/java/com/webforj/samples/views/lists/combobox/ComboBoxCustomValueView.java'
javaC='https://raw.githubusercontent.com/webforj/ControlSamples/main/src/main/code_snippets/combobox/CustomValue.txt'
height = '200px'
/>

## Placeholder

A placeholder can be set for a `ComboBox` which will display in the text field of the component when it is empty to prompt users for the desired entry in the field. This can be done using the <JavadocLink type="foundation" location="com/webforj/component/list/ComboBox" code='true' suffix='#setPlaceholder(java.lang.String)'>setPlaceholder()</JavadocLink> method.
You can prompt users with a desired entry in a `ComboBox` by setting a placeholder in the text field of the component when it's empty. This can be done using the <JavadocLink type="foundation" location="com/webforj/component/list/ComboBox" code='true' suffix='#setPlaceholder(java.lang.String)'>setPlaceholder()</JavadocLink> method.

<ComponentDemo
path='https://demo.webforj.com/webapp/controlsamples/comboboxplaceholder?'
javaE='https://raw.githubusercontent.com/webforj/webforj-docs-samples/refs/heads/main/src/main/java/com/webforj/samples/views/lists/combobox/ComboBoxPlaceholderView.java'
javaC='https://raw.githubusercontent.com/webforj/ControlSamples/main/src/main/code_snippets/combobox/Placeholder.txt'
height = '200px'
/>

Expand All @@ -60,12 +46,11 @@ Using the <JavadocLink type="foundation" location="com/webforj/component/list/Dw
This detachment creates a situation where directly targeting the
dropdown using CSS or shadow part selectors from the parent component becomes challenging, unless you make use of the dropdown type attribute.

In the demo below, the Dropdown type is set and used in the CSS file to select the dropdown and change the background color.
Here's an example of using a Dropdown type in CSS to animate choices while hovering over them:

<ComponentDemo
path='https://demo.webforj.com/webapp/controlsamples/comboboxdropdowntype?'
javaE='https://raw.githubusercontent.com/webforj/webforj-docs-samples/refs/heads/main/src/main/java/com/webforj/samples/views/lists/combobox/ComboBoxDropdownTypeView.java'
javaC='https://raw.githubusercontent.com/webforj/ControlSamples/main/src/main/code_snippets/combobox/DropdownType.txt'
cssURL='https://raw.githubusercontent.com/webforj/ControlSamples/main/src/main/resources/css/lists/combobox/comboBoxDropDownType.css'
height='250px'
/>
Expand All @@ -74,14 +59,13 @@ height='250px'

By default, the number of rows displayed in the dropdown of a `ComboBox` will be increased to fit the content. However, using the <JavadocLink type="foundation" location="com/webforj/component/list/DwcSelectDropdown" code='true' suffix='#setMaxRowCount(int)'>setMaxRowCount()</JavadocLink> method allows for control over how many items are displayed.

:::caution
Using a number that is less than or equal to 0 will result in unsetting this property.
:::tip
When a number less than or equal to zero is used, the number of rows will automatically adjust to accommodate the content.
:::

<ComponentDemo
path='https://demo.webforj.com/webapp/controlsamples/comboboxmaxrow?'
javaE='https://raw.githubusercontent.com/webforj/webforj-docs-samples/refs/heads/main/src/main/java/com/webforj/samples/views/lists/combobox/ComboBoxMaxRowView.java'
javaC='https://raw.githubusercontent.com/webforj/ControlSamples/main/src/main/code_snippets/combobox/MaxRow.txt'
height='450px'
/>

Expand Down Expand Up @@ -178,14 +162,10 @@ This component relies on the following components - see the related article for

To ensure an optimal user experience when using the `ComboBox` component, consider the following best practices:

1. **Preload Common Values**: If there are common or frequently used items, preload them in the `ComboBox` list. This speeds up selection for commonly chosen items and encourages consistency.

2. **User-Friendly Labels**: Ensure that the displayed labels for each option are user-friendly and self-explanatory. Make sure users can easily understand the purpose of each choice.
- **Preload Common Values**: If there are common or frequently used items, preload them in the `ComboBox` list. This speeds up selection for commonly chosen items and encourages consistency.

3. **Validation**: Implement input validation to handle custom entries. Check for data accuracy and consistency. You may want to suggest corrections or confirmations for ambiguous entries.
- **Clear Options**: Make the text for each `ListItem` clear and simple so users immediately understand their purpose.

4. **Default Selection**: Set a default selection, especially if there is a common or recommended choice. This enhances the user experience by reducing the need for extra clicks.
- **Validation**: Implement input validation to handle custom entries. Check for data accuracy and consistency. You may want to suggest corrections or confirmations for ambiguous entries.

5. **ComboBox vs. Other List Components**: A `ComboBox` is the best choice if you need a single input from the user and you wish to provide them with predetermined choices and the ability to customize their input. Another list component may be better if you need the following behaviors:
- Multiple Selection and display all items at once: [ListBox](./list-box.md)
- Prevent custom input: [ChoiceBox](./choice-box.md)
- **Default Selection**: Reduce the need for extra clicks by setting a default selection, especially if there is a common or recommended choice.
Loading
Loading