Skip to content

Commit

Permalink
Address docs comments
Browse files Browse the repository at this point in the history
  • Loading branch information
mattrunyon committed Nov 4, 2024
1 parent e18becc commit 778ee38
Showing 1 changed file with 18 additions and 18 deletions.
36 changes: 18 additions & 18 deletions plugins/ui/docs/components/table.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ _t = empty_table(10).update("X=i")
t = ui.table(_t)
```

## UI Recommendations
## UI recommendations

1. It is not necessary to use a UI table if you do not need any of its properties. You can just use the Deephaven table directly.
2. Use a UI table to show properties like filters as if the user had created them in the UI. Users can change the default values provided by the UI table, such as filters.
Expand All @@ -21,12 +21,12 @@ t = ui.table(_t)

You can format the table using the `format_` prop. This prop takes a list of `ui.TableFormat` objects. `ui.TableFormat` is a dataclass that encapsulates the formatting options for a table. The full list of formatting options can be found in the [API Reference](#tableformat).

### Formatting Rows and Columns
### Formatting rows and columns

Every formatting rule may optionally specify `cols` and `if_` properties. The `cols` property is a column name or list of column names to apply the formatting rule to. If `cols` is omitted, then the rule will be applied to the entire row. The `if_` property is a Deephaven formula to apply the formatting rule to. The `if_` property _must_ evaluate to a boolean. If `if_` is omitted, then the rule will be applied to every row. These may be combined to apply formatting to specific columns only when a condition is met.
Every formatting rule may optionally specify `cols` and `if_` properties. The `cols` property is a column name or list of column names to which the formatting rule applies. If `cols` is omitted, then the rule will be applied to the entire row. The `if_` property is a Deephaven formula that indicates a formatting rule should be applied conditionally. The `if_` property _must_ evaluate to a boolean. If `if_` is omitted, then the rule will be applied to every row. These may be combined to apply formatting to specific columns only when a condition is met.

> [!NOTE]
> The `if_` property is a Deephaven formula evaluated in the engine. You can think of it like adding a new boolean column using [`update_view`](https://deephaven.io/core/docs/reference/table-operations/select/update-view/)
> The `if_` property is a Deephaven formula evaluated in the engine. You can think of it like adding a new boolean column using [`update_view`](https://deephaven.io/core/docs/reference/table-operations/select/update-view/).
The following example shows how to format the `Sym` and `Exchange` columns with a red background and white text when the `Sym` is `DOG`.

Expand All @@ -47,7 +47,7 @@ t = ui.table(
)
```

### Formatting Rule Priority
### Formatting rule priority

The last matching formatting rule for each property will be applied. This means the lowest priority rules should be first in the list with higher priority rules at the end.

Expand All @@ -66,15 +66,15 @@ t = ui.table(
)
```

### Formatting Color
### Formatting color

Formatting rules for colors support Deephaven theme colors, hex colors, or any valid CSS color (e.g., `red`, `#ff0000`, `rgb(255, 0, 0)`). It is **recommended to use Deephaven theme colors** when possible to maintain a consistent look and feel across the UI. Theme colors will also automatically update if the user changes the theme.

#### Formatting Text Color
#### Formatting text color

The `color` property sets the text color of the cell. If a cell has a `background_color`, but no `color` set, the text color will be set to black or white depending on which contrasts better with the background color. Setting the `color` property will override this behavior.

The following example will make all text the foreground color except the `Sym` column, which will be white. In dark mode the foreground color is white, and in light mode the foreground color is black. In light mode, the `Sym` column will be nearly invisible because it is not a theme color
The following example will make all text the foreground color except the `Sym` column, which will be white. In dark mode, the foreground color is white, and in light mode, it is black. In light mode, the `Sym` column will be nearly invisible because it is not a theme color.

```py
from deephaven import ui
Expand All @@ -89,7 +89,7 @@ t = ui.table(
)
```

#### Formatting Background Color
#### Formatting background color

The `background_color` property sets the background color of the cell. Setting the `background_color` without setting `color` will result in the text color automatically being set to black or white based on the contrast with the `background_color`.

Expand All @@ -108,7 +108,7 @@ t = ui.table(
)
```

### Formatting Numeric Values
### Formatting numeric values

> [!WARNING]
> Datetime values are considered numeric. If you provide a default format for numeric values, it will also apply to datetime values. It is recommended to specify `cols` when applying value formats.
Expand All @@ -130,9 +130,9 @@ t = ui.table(
)
```

### Formatting Datetime Values
### Formatting datetime and timestamp values

Datetime values can be formatted using the `value` property. The `value` property is a string that follows [the GWT Java DateTimeFormat syntax](https://www.gwtproject.org/javadoc/latest/com/google/gwt/i18n/client/DateTimeFormat.html) with additional support for nanoseconds. You may provide up to 9 `S` characters after the decimal to represent partial seconds down to nanoseconds.
Datetime and timestamp values can be formatted using the `value` property. The `value` property is a string that follows [the GWT Java DateTimeFormat syntax](https://www.gwtproject.org/javadoc/latest/com/google/gwt/i18n/client/DateTimeFormat.html) with additional support for nanoseconds. You may provide up to 9 `S` characters after the decimal to represent partial seconds down to nanoseconds.

The following example formats the `Timestamp` column to show the short date of the week, day of the month, short month name, full year, hours, minutes, seconds, and microseconds with the user selected timezone.

Expand Down Expand Up @@ -173,7 +173,7 @@ t = ui.table(
)
```

## Context Menu
## Context menu

Items can be added to the bottom of the `ui.table` context menu (right-click menu) by using the `context_menu` or `context_header_menu` props. The `context_menu` prop adds items to the cell context menu, while the `context_header_menu` prop adds items to the column header context menu. You can pass either a single dictionary for a single item or a list of dictionaries for multiple items.

Expand Down Expand Up @@ -237,7 +237,7 @@ t = ui.table(
)
```

### Dynamic Menu Items
### Dynamic menu items

Menu items can be dynamically created by passing a function as the context item. The function will be called with the data of the cell that was clicked when the menu was opened, and must return the menu items or None if you do not want to add context menu items based on the cell info.

Expand All @@ -261,7 +261,7 @@ t = ui.table(
)
```

## Column Order and Visibility
## Column order and visibility

You can freeze columns to the front of the table using the `frozen_columns` prop. Frozen columns will always be visible on the left side of the table, even when the user scrolls horizontally. The `frozen_columns` prop takes a list of column names to freeze.

Expand All @@ -284,7 +284,7 @@ t = ui.table(

![Example of column order and visibility](../_assets/table_column_order.png)

## Grouping Columns
## Grouping columns

Columns can be grouped visually using the `column_groups` prop. Columns in a column group are moved so they are next to each other, and a header spanning all columns in the group is added. Columns can be rearranged within a group, but they cannot be moved outside of the group without using the table sidebar menu.

Expand Down Expand Up @@ -326,7 +326,7 @@ t = ui.table(

![Example of column groups](../_assets/table_column_groups.png)

## Always Fetching Some Columns
## Always fetching some columns

Deephaven only fetches data for visible rows and columns within a window around the viewport (typically the viewport plus 1 page in all directions). This reduces the amount of data transferred between the server and client and allows displaying tables with billions of rows. Sometimes you may need to always fetch columns, such as a key column for a row press event. You can use the `always_fetch_columns` prop to specify columns that should always be fetched regardless of their visibility.

Expand All @@ -349,7 +349,7 @@ t = ui.table(
)
```

## Quick Filters
## Quick filters

Quick filters are an easy way to filter the table while also showing the user what filters are currently applied. These filters are applied on the server via request from the client, so users may change the filters without affecting other users. Unlike a `where` statement to filter a table on the server, quick filters can be easily changed by the user.

Expand Down

0 comments on commit 778ee38

Please sign in to comment.