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

Jump to bottom

PR: Improvements on Existing Field Articles #318

Merged
merged 3 commits into from
Nov 28, 2024
Merged

PR: Improvements on Existing Field Articles #318

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
007d7ab
Field Articles Overhaul
bbrennanbasis Nov 25, 2024
1093610
Updated TextField Types Section
bbrennanbasis Nov 27, 2024
eb47502
Minor Grammar Corrections
bbrennanbasis Nov 27, 2024
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: 21 additions & 23 deletions docs/components/fields/color-field.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,64 +1,62 @@
---
sidebar_position: 1
sidebar_position: 11
title: ColorField
slug: colorfield
description: A component that provides a default browser-based color picker, allowing users to select a color from an input field.
---


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

<DocChip chip='name' label="dwc-color-chooser" />
<JavadocLink type="foundation" location="com/webforj/component/field/ColorField" top='true'/>

<ParentLink parent="Field" />

The `ColorField` component is a powerful and versatile tool designed to provide an intuitive and interactive way to explore and select colors within your application. Whether you're designing a user interface, creating visualizations, or enhancing user experience, the `ColorField` component offers a seamless and efficient approach to working with colors.
The `ColorField` component is a powerful and versatile tool that provides an intuitive and interactive way to explore and select colors within your app. Whether you're designing a user interface or creating visualizations, the `ColorField` component offers a seamless and efficient approach to working with colors.

With a simple drag-and-hover interface, users can effortlessly navigate through the color space to find the exact hue, saturation, and brightness that matches their creative vision. Users can also input color values directly, ensuring precision.


<ComponentDemo
path='https://demo.webforj.com/webapp/controlsamples/colorfielddemo?'
javaE='https://raw.githubusercontent.com/webforj/webforj-docs-samples/refs/heads/main/src/main/java/com/webforj/samples/views/fields/colorfield/ColorFieldDemoView.java'
path='https://demo.webforj.com/webapp/controlsamples/colorfield?'
javaE='https://raw.githubusercontent.com/webforj/webforj-docs-samples/refs/heads/main/src/main/java/com/webforj/samples/views/fields/colorfield/ColorFieldView.java'
cssURL='https://raw.githubusercontent.com/webforj/ControlSamples/main/src/main/resources/css/fields/colorfield/colorFieldDemo.css'
height='300px'
/>

## Usages

The `ColorField` is best used in scenarios where color selection is a crucial part of the user interface or application functionality. This section outlines the best practices and scenarios for using the color field component effectively.
The `ColorField` is best used in scenarios where color selection is a crucial part of the user interface or app interface. Here are some scenarios where you can use a `ColorField` effectively:

1. **Graphic Design and Image Editing Tools**: Color fields are essential in applications that involve:
>- Graphic design elements or functionality
>- Image editing and customization
>- Tasks that require selecting or modifying colors
1. **Graphic Design and Image Editing Tools**: Color fields are essential in apps that involve customization via color selection.

2. **Theme Customization**: If your application allows users to customize themes, using a color field enables them to choose colors for different UI elements, such as backgrounds, text, buttons, etc.
2. **Theme Customization**: If your app allows users to customize themes, using a color field enables them to choose colors for different UI elements, such as backgrounds, text, buttons, etc.

3. **Data Visualization**: Color fields are valuable in applications that involve data visualization, as they allow users to select colors for charts, graphs, heatmaps, and other visual representations.

4. **Form Inputs**: When designing forms that require color inputs, using a color field simplifies the color selection process for users.
3. **Data Visualization**: Provide users a color field to select colors for charts, graphs, heatmaps, and other visual representations.

## Color code format

Currently, the `ColorField` supports `#RRGGBB` hexadecimal format. Only simple colors (without alpha channel) are allowed in the picker interface. Additionally, the `ColorField` comes along with a various methods that interact with the `java.awt.Color` class to add flexibility.
The `ColorField` works seamlessly with the `java.awt.Color` class for setting the color and retrieving colors the user picks with the `setValue()` and `getValue()` methods. The `ColorField` only allows basic colors, which means that it will ignore any provided alpha value for a `Color`.
Alternatively, you use the #RRGGBB hexadecimal format by using the `setText()` and `getText()` methods.

:::info
:::note
The component's presentation may vary substantially from one browser and/or platform to another. It might be a simple textual field that automatically validates to ensure that the color information is entered in the proper format, a platform-standard color picker, or some kind of custom color picker window.
:::

## Static utilities

The `ColorField` class also provides the following static utility methods:

- `Color fromHex(String hex)`: Convert a color string in hex format to a `Color` object which can then be utilized with this class, or elsewhere.
- `fromHex(String hex)`: Convert a color string in hex format to a `Color` object which can then be utilized with this class, or elsewhere.

- `String toHex(Color color)`: Convert the given value to the corresponding hex representation.
- `toHex(Color color)`: Convert the given value to the corresponding hex representation.

- `boolean isValidHexColor(String hex)`: Check if the given value is a valid 7 character hex color.
- `isValidHexColor(String hex)`: Check if the given value is a valid 7 character hex color.

## Best practices

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

**Consider Contextual Assistance**: Provide contextual assistance, such as tooltips or inline help, to guide users in understanding the purpose and usage of the color field component.
- **Contextual Assistance**: Provide contextual assistance, such as tooltips or a label, to clarify that users can select a color and understand its purpose.

- **Provide a Default Color**: Have a default color that makes sense for your app's context.

- **Offer Preset Colors**: Include a palette of commonly used or on-brand colors alongside the color field for quick selection.
40 changes: 18 additions & 22 deletions docs/components/fields/date-field.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,61 +1,57 @@
---
sidebar_position: 2
sidebar_position: 6
title: DateField
slug: datefield
description: A component that provides a default browser-based date picker for selecting a date through an input field.
---

<DocChip chip='shadow' />

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

<JavadocLink type="foundation" location="com/webforj/component/field/DateField" top='true'/>

<ParentLink parent="Field" />

The `DateField` is a user interface component that allows users to input or select dates. It provides an intuitive and efficient way to handle date-related information in various applications. This section outlines the best practices for using the `DateField` component effectively.
The `DateField` is a field component that allows users to input or select dates by the year, month, and day. It provides an intuitive and efficient way to handle date-related information in various apps, and offers the flexibility to validate a user's input.

<ComponentDemo
path='https://demo.webforj.com/webapp/controlsamples/datefielddemo?'
javaE='https://raw.githubusercontent.com/webforj/webforj-docs-samples/refs/heads/main/src/main/java/com/webforj/samples/views/fields/datefield/DateFieldDemoView.java'
cssURL='https://raw.githubusercontent.com/webforj/ControlSamples/main/src/main/resources/css/fields/datefield/dateFieldDemo.css'
path='https://demo.webforj.com/webapp/controlsamples/datefield?'
javaE='https://raw.githubusercontent.com/webforj/webforj-docs-samples/refs/heads/main/src/main/java/com/webforj/samples/views/fields/datefield/DateFieldView.java'
/>

## Usages

The `DateField` is best used in scenarios where capturing or displaying dates is a crucial part of the user interface or application functionality. Here are some examples of when to use the date field

1. **Event Scheduling and Calendars**: Date fields are essential in applications that involve event scheduling, appointment booking, or managing calendars. They enable users to select specific dates accurately.
The `DateField` is ideal for choosing and displaying dates in your app. Here are some examples of when to use the `DateField`:

2. **Form Inputs**: When designing forms that require date inputs, using a date field simplifies the date selection process for users. This is particularly useful for applications that collect user data or require date-based inputs.
1. **Event Scheduling and Calendars**: Date fields are essential in apps that involve scheduling events, booking appointments, or keeping track of important dates.

3. **Booking and Reservation Systems**: Applications that involve booking and reservation systems often require users to input specific dates. A date field simplifies the process and ensures accurate date selection.
2. **Form Inputs**: Simplify the date selection process for a user filling out a form that requires a date, like a birthday.

4. **Task Management and Deadlines**: Date fields are valuable in applications that involve task management or setting deadlines. Users can easily specify due dates, start dates, or other time-sensitive information.
3. **Booking and Reservation Systems**: Apps that involve booking and reservation systems often require users to input specific dates. A date field streamlines the process and ensures accurate date selection.

The `DateField` class provides a user interface component that allows the user to enter a date, including the year, month, and day. It offers the flexibility to validate the input or use a special date picker interface.
4. **Task Management and Deadlines**: Date fields are valuable in apps that involve task management or setting deadlines. Users can easily specify due dates, start dates, or other time-sensitive information.

## Maximum and minimum

You can use the `setMax()` and `setMin()` methods to specify the acceptable range of dates. If the value entered into the component is outside of the specified value, the component fails constraint validation. Also, if there is already a maximum or minimum set, the value given to the other method must be lower or higher respectively.
With the `setMax()` and `setMin()` methods, you can specify a range of acceptable dates. If a user manually enters a value into the date field outside the specified range, the component will let the user know what's acceptable. Also, if a maximum or minimum is already set, the value for the other method must be lower or higher respectively.

## Display
## Localized display

The `DateField` will, by default, display its information within the UI element based on the locale the browser is configured to. For example, users with United States configurations will see the date displayed with the month preceding the day, whereas European users will see the day before the month. This does not inhibit manipulation of the `LocalDate` object returned by methods from the class, however.
By default, the `DateField` displays information within the UI element based on the locale the browser is configured to. For example, users with United States configurations will see MM/dd/yyyy, whereas European users will see dd/MM/yyyy. Still, this doesn't stop you from manipulating the `LocalDate` object returned by the methods from the `DataField` class.

## Static utilities

The `DateField` class also provides the following static utility methods:

- `fromDate(String dateAsString)`: Convert a date string in yyyy-MM-dd format to a LocalDate object which can then be utilized with this class, or elsewhere.
- `fromDate(String dateAsString)`: Convert a date string in yyyy-MM-dd format to a `LocalDate` object which can then be utilized with this field, or elsewhere.

- `toDate(LocalDate date)`: Convert a LocalDate object to a date string in yyyy-MM-dd format.
- `toDate(LocalDate date)`: Convert a `LocalDate` object to a date string in yyyy-MM-dd format.

- `isValidDate(String dateAsString)`: Checks to see if the given string is a valid yyyy-MM-dd date. This will return a boolean value true if so, false otherwise.
- `isValidDate(String dateAsString)`: Checks to see if the given string is a valid yyyy-MM-dd date.

## Best practices

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

1. **Consider Accessibility**: Ensure that your utilization of the `DateField` meets accessibility standards, using proper labels, and being compatible with assistive technologies.
- **Accessibility**: Utilize appropriate labels to ensure users with assistive technologies can easily navigate to and use the date fields in your app.

2. **Auto-Populate Current Date**: Consider providing an option to auto-populate the current date as a default value in the date field, if appropriate for your application's use case.
- **Auto-Populate Current Date**: If appropriate for your app's use case, auto-populate with the date field with the current date.
Loading
Loading