Skip to content

Commit 01693d7

Browse files
arman-ddlmargaretkennedydsmmcken
authored
docs: Apply miscellaneous fixes to deephaven.ui docs (#1162)
Co-authored-by: margaretkennedy <[email protected]> Co-authored-by: Don <[email protected]>
1 parent 9ba7f2c commit 01693d7

13 files changed

+37
-34
lines changed
13 KB
Loading

plugins/ui/docs/add-interactivity/render-cycle.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,11 @@ Think of your components as chefs in a kitchen, preparing delicious meals from v
1313
There are two reasons for a component to render:
1414

1515
1. It is the component’s initial render.
16-
2. The component’s state has been updated or one of it's ancestor's state has been updated.
16+
2. The component’s state has been updated or one of its ancestors' state has been updated.
1717

1818
### Initial Render
1919

20-
Opening a component to view it causes the component to be mounted, which means adding nodes to the DOM. When your component first mounts, it triggers an initial render. It is rendered with it's props and initial state.
20+
Opening a component to view it causes the component to be mounted, which means adding nodes to the DOM. When your component first mounts, it triggers an initial render. It is rendered with its props and initial state.
2121

2222
```python
2323
from deephaven import ui
@@ -75,8 +75,8 @@ Otherwise, you can encounter confusing bugs and unpredictable behavior as your c
7575

7676
After rendering your components, `deephaven.ui` sends the components to client and React renders and will modify the DOM.
7777

78-
-For the initial render, React will use the `appendChild()` DOM API to put all the DOM nodes it has created on screen.
79-
-For re-renders, React will apply the minimal necessary operations (calculated while rendering!) to make the DOM match the latest rendering output.
78+
- For the initial render, React will use the `appendChild()` DOM API to put all the DOM nodes it has created on screen.
79+
- For re-renders, React will apply the minimal necessary operations (calculated while rendering!) to make the DOM match the latest rendering output.
8080

8181
React only changes the DOM nodes if there’s a difference between renders. For example, here is a component that re-renders with different props passed from its parent every second. Notice how you can add some text into the `ui.text_field`, updating its value, but the text doesn’t disappear when the component re-renders:
8282

plugins/ui/docs/add-interactivity/respond-to-events.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ This lets these two buttons show different messages. Try changing the messages p
119119

120120
Often, you’ll want the parent component to specify a child’s event handler. Consider buttons: depending on where you’re using a button component, you might want to execute a different function — perhaps one plays a movie and another uploads an image.
121121

122-
To do this, pass a prop the component receives from its parent as the event handler like so:
122+
To do this, pass a prop that the component receives as the event handler from its parent like so:
123123

124124
```python
125125
from deephaven import ui

plugins/ui/docs/add-interactivity/state-as-a-snapshot.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -88,21 +88,21 @@ Setting state only changes it for the next render. During the first render, `num
8888

8989
Here is what `handle_press` tells `deephaven.ui` to do:
9090

91-
1. `set_number(number + 1)`: number is 0 so `set_number(0 + 1)`.
91+
1. `set_number(number + 1)`: `number` is 0 so `set_number(0 + 1)`.
9292

93-
- `deephaven.ui` prepares to change number to 1 on the next render.
93+
- `deephaven.ui` prepares to change `number` to 1 on the next render.
9494

95-
2. `set_number(number + 1)`: number is 0 so `set_number(0 + 1)`.
95+
2. `set_number(number + 1)`: `number` is 0 so `set_number(0 + 1)`.
9696

97-
- `deephaven.ui` prepares to change number to 1 on the next render.
97+
- `deephaven.ui` prepares to change `number` to 1 on the next render.
9898

99-
3. `set_number(number + 1)`: number is 0 so `set_number(0 + 1)`.
99+
3. `set_number(number + 1)`: `number` is 0 so `set_number(0 + 1)`.
100100

101-
- `deephaven.ui` prepares to change number to 1 on the next render.
101+
- `deephaven.ui` prepares to change `number` to 1 on the next render.
102102

103-
Even though you called `set_number(number + 1)` three times, in this render’s event handler, `number` is always `0`, so you set the state to `1` three times. This is why, after your event handler finishes, React re-renders the component with number equal to `1` rather than `3`.
103+
Even though you called `set_number(number + 1)` three times, in this render’s event handler, `number` is always `0`, so you set the state to `1` three times. This is why, after your event handler finishes, React re-renders the component with `number` equal to `1` rather than `3`.
104104

105-
You can also visualize this by mentally substituting state variables with their values in your code. Since the number state variable is 0 for this render, its event handler looks like this:
105+
You can also visualize this by mentally substituting state variables with their values in your code. Since the `number` state variable is 0 for this render, its event handler looks like this:
106106

107107
```python
108108
def handle_press():
@@ -183,7 +183,7 @@ def handle_press():
183183

184184
The state stored in `deephaven.ui` may have changed by the time the alert runs, but it was scheduled using a snapshot of the state at the time the user interacted with it.
185185

186-
A state variable’s value never changes within a render, even if its event handler’s code is asynchronous. Inside that render’s `on_press`, the value of number continues to be 0 even after `set_number(number + 5)` was called. Its value was “fixed” when `deephaven.ui` “took the snapshot” of the UI by calling your component.
186+
A state variable’s value never changes within a render, even if its event handler’s code is asynchronous. Inside that render’s `on_press`, the value of `number` continues to be 0 even after `set_number(number + 5)` was called. Its value was “fixed” when `deephaven.ui` “took the snapshot” of the UI by calling your component.
187187

188188
Here is an example of how that makes your event handlers less prone to timing mistakes. Below is a form that sends a message with a five-second delay. Imagine this scenario:
189189

plugins/ui/docs/add-interactivity/update-tables-in-state.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ The error states that "this manager or referent is no longer live". This is a li
3232

3333
## The `use_liveness_scope` hook
3434

35-
The first way to fix this error is the [`use_liveness_scope`](../hooks/use_liveness_scope.md) hook. This hook allows you to manage the liveness of table to prevent it being garbage collected before your component is done using it. With this change, we can reset the table:
35+
The first way to fix this error is the [`use_liveness_scope`](../hooks/use_liveness_scope.md) hook. This hook allows you to manage the liveness of a table to prevent it being garbage collected before your component is done using it. With this change, we can reset the table:
3636

3737
```python
3838
from deephaven import ui, time_table

plugins/ui/docs/describing/importing_and_exporting_components.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ my_multiple_contents = multiple_contents()
5353

5454
## Exporting and Importing in Deephaven Enterprise
5555

56-
In Deephaven Enterprise, notebook files are stored in a secure file system which prevents importing by default. In order to import from another script, you can use the `deephaven_enterprise.notebook` module to do either an `exec_notebook` or a `meta_import`. For details on how to do this, see [Modularizing Queries](/enterprise/docs/development/modularizing-queries).
56+
In Deephaven Enterprise, notebook files are stored in a secure file system which prevents importing by default. In order to import from another script, you can use the `deephaven_enterprise.notebook` module to do either an `exec_notebook` or a `meta_import`. For details on how to do this, see [Modularizing Queries](/enterprise/docs/query-management/modularizing-queries-python/).
5757

5858
### Example Export in Deephaven Enterprise
5959

plugins/ui/docs/describing/ui_with_tables.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,6 @@ You can display a Deephaven table in a component by doing one of the following:
1919
from deephaven import new_table, ui
2020
from deephaven.column import int_col
2121

22-
# Prepend name with an underscore to avoid displaying the source table
2322
_source = new_table([int_col("IntegerColumn", [1, 2, 3])])
2423

2524

@@ -246,7 +245,7 @@ picker_item_table_source_example = ui.picker(item_table_source, label="User Pick
246245

247246
## Update tables and plots from user input
248247

249-
Tables and plots can update in response to user input. The following examples allows a user to pick two dates on a [`date_range_picker](../components/date_range_picker.md). This updates a state variable which causes the component to re-render with a filtered table and plot.
248+
Tables and plots can update in response to user input. The following examples allows a user to pick two dates on a [`date_range_picker`](../components/date_range_picker.md). This updates a state variable which causes the component to re-render with a filtered table and plot.
250249

251250
```python
252251
from deephaven.time import dh_now

plugins/ui/docs/describing/use_hooks.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,20 +8,20 @@ Hooks are Python functions, but you need to follow two rules when using them.
88

99
1. Only call hooks at the top level.
1010

11-
Don’t call hooks inside loops, conditions, or nested functions. Instead, always use hooks at the top level of your `deephaven.ui` component function, before any early returns. By following this rule, you ensure that hooks are called in the same order each time a component renders.
11+
Don’t call hooks inside loops, conditions, or nested functions. Instead, always use hooks at the top level of your `deephaven.ui` component function, before any early returns. By following this rule, you ensure that hooks are called in the same order each time a component renders.
1212

1313
2. Only call hooks from components and custom hooks
1414

15-
Don’t call hooks from regular Python functions. Instead, you can:
15+
Don’t call hooks from regular Python functions. Instead, you can:
1616

17-
- Call Hooks from `@ui.component` decorated functions.
18-
- Call hooks from custom hooks.
17+
- Call Hooks from `@ui.component` decorated functions.
18+
- Call hooks from custom hooks.
1919

20-
Following this rule ensures that all stateful logic in a component is clearly visible from its source code.
20+
Following this rule ensures that all stateful logic in a component is clearly visible from its source code.
2121

2222
## Built-in Hooks
2323

24-
`deephaven.ui` has a large number of built-in hooks to help with the development of components. More details can be found in the [`hooks` section](../hooks/overview.md) of the documentation.
24+
`deephaven.ui` has a large number of built-in hooks to help with the development of components. More details can be found in the [hooks section](../hooks/overview.md) of the documentation.
2525

2626
### Use State Hook
2727

@@ -65,7 +65,7 @@ def ui_todo_list(todos: list[str], filter: str):
6565
result = ui_todo_list(["Do grocery shopping", "Walk the dog", "Do laundry"], "Do")
6666
```
6767

68-
The `use_memo` hook takes two parameters: a `callable` that returns a value and a list of dependencies. When dependencies are changed, the value is computed once and then stored in the memoized value. The memoized value is returned on subsequent renders until the dependencies change. The memoized value is returned on subsequent renders until the dependencies change.
68+
The `use_memo` hook takes two parameters: a `callable` that returns a value and a list of dependencies. When dependencies are changed, the value is computed once and then stored in the memoized value. The memoized value is returned on subsequent renders until the dependencies change.
6969

7070
### Use Effect Hook
7171

plugins/ui/docs/describing/your_first_component.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ On the Web, HTML lets us create rich structured documents with its built-in set
1919

2020
This markup represents an article `<div>`, its heading `<h1>`, and an (abbreviated) table of contents as an ordered list `<ol>`. Markup like this, combined with CSS for style, and JavaScript for interactivity, lies behind every sidebar, avatar, modal, dropdown—every piece of UI you see on the Web.
2121

22-
`Deephaven.ui` lets you use Python code to write custom "components", reusable UI elements for your app. The table of contents code you saw above could be turned into a `table_of_contents` component you could render in the UI.
22+
`deephaven.ui` lets you use Python code to write custom "components", reusable UI elements for your app. The table of contents code you saw above could be turned into a `table_of_contents` component you could render in the UI.
2323

2424
As your project grows, you will notice that many of your designs can be composed by reusing components you already wrote, speeding up your development.
2525

@@ -69,7 +69,7 @@ The component returns a `ui.flex` component with child components `ui.heading` a
6969

7070
## Using a component
7171

72-
Now that you’ve defined your `table_of_contents` component, you can nest it inside other components. You can export an `multiple_contents` component that uses multiple `table_of_contents` components:
72+
Now that you’ve defined your `table_of_contents` component, you can nest it inside other components. You can export a `multiple_contents` component that uses multiple `table_of_contents` components:
7373

7474
```python
7575
from deephaven import ui
@@ -102,6 +102,6 @@ my_multiple_contents = multiple_contents()
102102

103103
## Nesting and organizing components
104104

105-
Components are regular Python functions, so you can keep multiple components in the same file. This is convenient when components are relatively small or tightly related to each other. If this file gets crowded, you can always move a component to a separate file. See [How do I import one Python script into another in the Deephaven IDE?](/core/docs/reference/community-questions/import-python-script) and [Modularizing Queries](/enterprise/docs/development/modularizing-queries)
105+
Components are regular Python functions, so you can keep multiple components in the same file. This is convenient when components are relatively small or tightly related to each other. If this file gets crowded, you can always move a component to a separate file. See [How do I import one Python script into another in the Deephaven IDE?](/core/docs/reference/community-questions/import-python-script) and [Modularizing Queries](/enterprise/docs/query-management/modularizing-queries-python/).
106106

107107
Because the `table_of_contents` components are rendered inside `multiple_contents` we can say that `multiple_contents` is a parent component, rendering each `table_of_contents` as a "child". You can define a component once, and then use it in as many places and as many times as you like.

plugins/ui/docs/hooks/overview.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ _Data_ hooks let you use data from within a Deephaven table in your component.
6565

6666
## Create custom hooks
6767

68-
You can create your own hooks to reuse stateful logic between components. A custom hook is a JavaScript function whose name starts with `use` and that may call other hooks. For example, let's say you want to create a custom hook that checks whether a table cell is odd. You can create a custom hook called `use_is_cell_odd`:
68+
You can create your own hooks to reuse stateful logic between components. A custom hook is a function whose name starts with `use` and that may call other hooks. For example, let's say you want to create a custom hook that checks whether a table cell is odd. You can create a custom hook called `use_is_cell_odd`:
6969

7070
```python
7171
from deephaven import time_table, ui

plugins/ui/docs/installation.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
deephaven.ui is a plugin that works with [Deephaven](https://deephaven.io/core/docs/). Use the deephaven.ui plugin to build dynamic components and layouts using Deephaven.
44

5+
## Enterprise
6+
7+
Enterprise installations come packaged with `deephaven.ui` and therefore don't require additional steps. The rest of the document pertains to Core installations.
8+
59
## New installation
610

711
If you don't already have Deephaven installed, you can install via Docker or pip.

plugins/ui/docs/managing-state/react-to-input-with-state.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -83,11 +83,11 @@ In `deephaven.ui`, you do not manipulate the UI directly. Instead, you declare w
8383

8484
You’ve seen how to implement a form imperatively above. To better understand how to think declaratively, let's walk through reimplementing this UI using `deephaven.ui` below:
8585

86-
1. **Identify** your component’s different visual states
87-
2. **Determine** what triggers those state changes
86+
1. **Identify** your component’s different visual states.
87+
2. **Determine** what triggers those state changes.
8888
3. **Represent** the state in memory using `useState`.
89-
4. **Remove** any non-essential state variables
90-
5. **Connect** the event handlers to set the state
89+
4. **Remove** any non-essential state variables.
90+
5. **Connect** the event handlers to set the state.
9191

9292
### Step 1: Identify your component’s different visual states
9393

plugins/ui/docs/tutorial.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -285,7 +285,7 @@ picker_panel = species_panel()
285285

286286
### Table-backed `ui.picker`
287287

288-
`ui.pickers` can pull directly from a table so they update automatically based on a column in the table. Modify your `ui.picker` to pass in a table instead, which is recommended for dynamic data.
288+
A `ui.picker` can pull directly from a table so they update automatically based on a column in the table. Modify your `ui.picker` to pass in a table instead, which is recommended for dynamic data.
289289

290290
> [!NOTE]
291291
> It’s important to filter your table down to the distinct values you want. The `ui.picker` does not do this for you.

0 commit comments

Comments
 (0)