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

docs: More specs for ui.table functionality #198

Merged
merged 7 commits into from
Feb 16, 2024
Merged

docs: More specs for ui.table functionality #198

Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
80b2397
wip design
jnumainville Jan 9, 2024
5b813ce
a couple minor details
jnumainville Jan 9, 2024
b402b69
comments
jnumainville Jan 24, 2024
1e7d546
comments
jnumainville Feb 5, 2024
1bc3bb1
comment
jnumainville Feb 8, 2024
e0c668a
prop refactor
jnumainville Feb 13, 2024
3dfc479
remove can_search
jnumainville Feb 14, 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
304 changes: 298 additions & 6 deletions plugins/ui/DESIGN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1371,19 +1371,23 @@ ui_table.quick_filter(filter: dict[ColumnName, QuickFilterExpression]) -> UITabl

##### selection_mode

Set the selection mode for the table.
Set the selection mode for the table and whether or not multiple selections are the default

###### Syntax

```py
ui_table.selection_mode(mode: SelectionMode) -> UITable
ui_table.selection_mode(
mode: SelectionMode,
multi_select: bool = True
) -> UITable
```

###### Parameters

| Parameter | Type | Description |
| --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode` | `SelectionMode` | The selection mode to use. Must be one of `"ROW"`, `"COLUMN"`, or `"CELL"`:<li>`"ROW"` selects the entire row of the cell you click on.</li><li>`"COLUMN"` selects the entire column of the cell you click on.</li><li>`"CELL"` selects only the cells you click on.</li> |
| Parameter | Type | Description |
|----------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `mode` | `SelectionMode` | The selection mode to use. Must be one of `"ROW"`, `"COLUMN"`, or `"CELL"`:<li>`"ROW"` selects the entire row of the cell you click on.</li><li>`"COLUMN"` selects the entire column of the cell you click on.</li><li>`"CELL"` selects only the cells you click on.</li> |
jnumainville marked this conversation as resolved.
Show resolved Hide resolved
| `multi_select` | `bool` | True if always multiple select on press. `True` by default. |

##### sort

Expand All @@ -1407,6 +1411,278 @@ ui_table.sort(
| `by` | `str \| Sequence[str]` | The column(s) to sort by. May be a single column name, or a list of column names. |
| `direction` | `TableSortDirection \| Sequence[TableSortDirection] \| None` | The sort direction(s) to use. If provided, that must match up with the columns provided. Defaults to "ASC". |

##### column_display_names

Set the display names for columns in the table. If a sequence of column names is provided for a column, the display name will be set to the longest column name that can be fully displayed.

###### Syntax

```py
ui_table.column_display_names(
display_names: dict[ColumnName, ColumnNameCombination]
) -> UITable
```

##### Parameters
jnumainville marked this conversation as resolved.
Show resolved Hide resolved

| Parameter | Type | Description |
|-----------------|-------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `display_names` | `dict[ColumnName, ColumnNameCombination]` | The display names. If a sequence of column names is provided for a column, the display name will be set to the longest column name that can be fully displayed. |

##### show_column_headers

Set the column headers for the table to be visible or not visible.

###### Syntax

```py
ui_table.show_column_headers(
visible: bool | None
) -> UITable
```

##### Parameters
jnumainville marked this conversation as resolved.
Show resolved Hide resolved

| Parameter | Type | Description |
|-----------|----------------|--------------------------------------------------------|
| `visible` | `bool \| None` | `True` to show the quick filters, `False` to hide them |

##### show_quick_filters

Set the quick filters for the table to be visible, hidden, or use the system default.

###### Syntax

```py
ui_table.show_quick_filters(
visible: bool | None
) -> UITable
```

##### Parameters
jnumainville marked this conversation as resolved.
Show resolved Hide resolved

| Parameter | Type | Description |
|-----------|----------------|--------------------------------------------------------|
| `visible` | `bool \| None` | `True` to show the quick filters, `False` to hide them |

##### selected

Set the selected rows, columns, or cells in the table. This must match the mode set by [selection_mode](#selection_mode).
Only one of `rows`, `columns`, or `cells` may be provided.

###### Syntax

```py
ui_table.selected(
rows: RowIndexCombination | None = None,
columns: ColumnIndexCombination | None = None,
cells: CellIndexCombination | None = None
) -> UITable
```
##### Parameters
jnumainville marked this conversation as resolved.
Show resolved Hide resolved

| Parameter | Type | Description |
|-----------|----------------------------------------------|---------------------------------|
| `rows` | `RowIndex \| Sequence[RowIndex] \| None` | The selected row or rows. |
| `columns` | `ColumnName \| Sequence[ColumnName] \| None` | The selected column or columns. |
| `cells` | `CellIndex \| Sequence[CellIndex] \| None` | The selected cell or cells. |

##### selection_style

Specify the style that is used to show that data is selected. This can by `"HIGHLIGHT"`, `"CHECKBOX"`, a combination of those, or `"DEFAULT"` to use the system default.
dsmmcken marked this conversation as resolved.
Show resolved Hide resolved

###### Syntax

```py
ui_table.selection_style(
modes: SelectionStyleModeCombination
) -> UITable
```

##### Parameters
jnumainville marked this conversation as resolved.
Show resolved Hide resolved

| Parameter | Type | Description |
|-----------|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `mode` | `SelectionStyleMode` | `"HIGHLIGHT"` to highlight the selected data, `"CHECKBOX"` to show checkboxes for the selected data, a combination of those, or `"DEFAULT"` to use the system default |

##### density

Set the density of the table to be `"COMPACT"`, `"REGULAR"`, `"SPACIOUS"`, or `"DEFAULT"`, the system default.

###### Syntax

```py
ui_table.density(
mode: DensityMode
) -> UITable
```

##### Parameters
jnumainville marked this conversation as resolved.
Show resolved Hide resolved

| Parameter | Type | Description |
|-----------|---------------|-------------------------------------------------------|
| `mode` | `DensityMode` | `"COMPACT"`, `"REGULAR"`, `"SPACIOUS"`, or `"DEFAULT"`|

##### on_search

Add a callback for when the search bar is used.

###### Syntax

```py
ui_table.on_search(
callback: Callable[[str], None]
) -> UITable
```

##### Parameters
jnumainville marked this conversation as resolved.
Show resolved Hide resolved
| Parameter | Type | Description |
|------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| `callback` | `Callable[[str], None]` | The callback function to run when the search bar is used. The only parameter of the callback is the string in the search bar. |


##### on_quick_filter

Add a callback for when a quick filter is used.

###### Syntax

```py
ui_table.on_quick_filter(
callback: Callable[[ColumnName, QuickFilterExpression], None]
) -> UITable
```

##### Parameters
jnumainville marked this conversation as resolved.
Show resolved Hide resolved
| Parameter | Type | Description |
|------------|-------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `callback` | `Callable[[ColumnName, QuickFilterExpression], None]` | The callback function to run when a quick filter is made. The first parameter is the column name the quick filter was added to and the second is the quick filter itself. |

##### on_freeze_column

Add a callback for when a column is frozen.

###### Syntax

```py
ui_table.on_freeze_column(
callback: Callable[[ColumnName], None]
) -> UITable
```

##### Parameters
jnumainville marked this conversation as resolved.
Show resolved Hide resolved
| Parameter | Type | Description |
|------------|--------------------------------|------------------------------------------------------------------------------------------------------------|
| `callback` | `Callable[[ColumnName], None]` | The callback function to run when a column is frozen. The only parameter is the name of the frozen column. |

##### on_hide_column

Add a callback for when a column is hidden.

###### Syntax

```py
ui_table.on_hide_column(
callback: Callable[[ColumnName], None]
) -> UITable
```

##### Parameters
jnumainville marked this conversation as resolved.
Show resolved Hide resolved
| Parameter | Type | Description |
|------------|--------------------------------|------------------------------------------------------------------------------------------------------------|
| `callback` | `Callable[[ColumnName], None]` | The callback function to run when a column is hidden. The only parameter is the name of the hidden column. |

##### on_cell_press

Add a callback for when a cell is pressed. Only valid if the selection mode is `"CELL"`.
jnumainville marked this conversation as resolved.
Show resolved Hide resolved

###### Syntax

```py
ui_table.on_cell_press(
callback: Callable[[CellIndex, Any], None]
) -> UITable
```

##### Parameters
jnumainville marked this conversation as resolved.
Show resolved Hide resolved
| Parameter | Type | Description |
| ---------- |------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
| `callback` | `Callable[[CellIndex, Any], None]` | The callback function to run when a cell is clicked. The first parameter is the cell index, and the second is the cell data. |

##### on_cell_double_press

Add a callback for when a cell is double pressed. Only valid if the selection mode is `"CELL"`.

###### Syntax

```py
ui_table.on_cell_double_press(
callback: Callable[[CellIndex, Any], None]
) -> UITable
```

##### Parameters
jnumainville marked this conversation as resolved.
Show resolved Hide resolved
| Parameter | Type | Description |
| ---------- |------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| `callback` | `Callable[[CellIndex, Any], None]` | The callback function to run when a cell is double clicked. The first parameter is the cell index, and the second is the cell data. |

##### on_column_press

Add a callback for when a column is pressed.
jnumainville marked this conversation as resolved.
Show resolved Hide resolved

##### Parameters
| Parameter | Type | Description |
| ---------- |------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| `callback` | `Callable[[CellIndex, Any], None]` | The callback function to run when a cell is double clicked. The first parameter is the cell index, and the second is the cell data. |

jnumainville marked this conversation as resolved.
Show resolved Hide resolved
###### Syntax

```py
ui_table.on_column_press(
callback: Callable[[ColumnName, ColumnData], None]
) -> UITable
```

##### Parameters
jnumainville marked this conversation as resolved.
Show resolved Hide resolved
| Parameter | Type | Description |
| ---------- |------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `callback` | `Callable[[CellIndex, Any], None]` | The callback function to run when a column is clicked. The first parameter is the column name, and the second is the column data, which is a list of the data in the column. |
jnumainville marked this conversation as resolved.
Show resolved Hide resolved

##### on_column_double_press

Add a callback for when a column is double pressed.

###### Syntax

```py
ui_table.on_column_double_press(
callback: Callable[[ColumnName, ColumnData], None]
) -> UITable
```

##### Parameters
jnumainville marked this conversation as resolved.
Show resolved Hide resolved
| Parameter | Type | Description |
| ---------- |--------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `callback` | `Callable[[ColumnName, ColumnData], None]` | The callback function to run when a column is double clicked. The first parameter is the column name, and the second is the column data, which is a list of the data in the column. |


##### on_sort

Add a callback for when a column is sorted.

###### Syntax

```py
ui_table.on_sort(
callback: Callable[[ColumnName, LiteralSortDirection], None]
) -> UITable
```

##### Parameters
jnumainville marked this conversation as resolved.
Show resolved Hide resolved
| Parameter | Type | Description |
| ---------- |------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| `callback` | `Callable[[ColumnName, LiteralSortDirection], None]` | The callback function to run when a column is sorted. The first parameter is the column name, and the second is the sort direction. |

#### ui.fragment

A fragment maps to a [React.Fragment](https://react.dev/reference/react/Fragment). This lets you group elements without using a wrapper node. It only takes children, and does not take any additional props.
Expand Down Expand Up @@ -1576,6 +1852,8 @@ use_cell_data(
| `table` | `Table` | The table to create a viewport on. |
| `sentinel` | `Sentinel` | A sentinel value to return if the cell is still loading. Default `None`. |



#### Custom Types

Below are some of the custom types that are used in the above API definitions:
Expand Down Expand Up @@ -1605,12 +1883,26 @@ RowData = dict[ColumnName, Any]
# A RowIndex of None indicates a header column
RowIndex = int | None
SearchMode = Literal["SHOW", "HIDE", "DEFAULT"]
SelectionStyleMode = Literal["HIGHLIGHT", "CHECKBOX", "DEFAULT"]
SelectionMode = Literal["CELL", "ROW", "COLUMN"]
DensityMode = Literal["COMPACT", "REGULAR", "SPACIOUS", "DEFAULT"]
Sentinel = Any
TableSortDirection = Union[Literal["ASC", "DESC"], SortDirection]
LiteralSortDirection = Literal["ASC", "DESC"]
TableSortDirection = Union[LiteralSortDirection, SortDirection]
TableData = dict[ColumnName, ColumnData]
TransformedData = Any

T = TypeVar("T")
Combination: TypeAlias = T | set[T] | Sequence[T]

RowIndexCombination = Combination[RowIndex]
ColumnNameCombination = Combination[ColumnName]
ColumnIndexCombination = Combination[ColumnIndex]
CellIndexCombination = Combination[CellIndex]
SelectionStyleModeCombination = Combination[SelectionStyleMode]

```

# Set a filter for a dashboard. Filter will apply to all items with a matching column/type, except for items specified in the `exclude_ids` parameter
class DashboardFilter(TypedDict):
# Name of column to filter on
Expand Down