Update data grid/table row selection docs (#143)

* Update data grid/table row selection docs

* Update instructions

* Add links to data frame API docs

* Update py-shiny for API docs

components/outputs/data-grid/app-variation-select-rows-core.py

@@ -13,11 +13,11 @@
 def server(input, output, session):
     @render.data_frame
     def penguins_df():
-        return render.DataGrid(penguins, row_selection_mode="multiple")  # <<
+        return render.DataGrid(penguins, selection_mode="rows")  # <<
 
-    @render.ui()
+    @render.ui
     def rows():
-        rows = input.penguins_df_selected_rows()  # <<
+        rows = penguins_df.input_cell_selection()["rows"]  # <<
         selected = ", ".join(str(i) for i in sorted(rows)) if rows else "None"
         return f"Rows selected: {selected}"
 

components/outputs/data-grid/app-variation-select-rows-express.py

@@ -9,11 +9,11 @@
 
 @render.ui()
 def rows():
-    rows = input.penguins_df_selected_rows()  # <<
+    rows = penguins_df.input_cell_selection()["rows"]  # <<
     selected = ", ".join(str(i) for i in sorted(rows)) if rows else "None"
     return f"Rows selected: {selected}"
 
 
 @render.data_frame
 def penguins_df():
-    return render.DataGrid(penguins, row_selection_mode="multiple")  # <<
+    return render.DataGrid(penguins, selection_mode="rows")  # <<

components/outputs/data-grid/index.qmd

@@ -45,9 +45,10 @@ listing:
     dir: components/outputs/data-grid/
   contents:
   - title: Select Rows
-    description: Set `row_selection_mode` in `render.DataGrid()` to `"single"` to
-      allow the user to select one row at a time. Set it to `"multiple"` to allow
-      the user to select multiple rows at a time. Access the selection(s) as `input.<id>_selected_rows()`.
+    description: Set `selection_mode` in `render.DataGrid()` to `"row"` to
+      allow the user to select one row at a time. Set it to `"rows"` to allow
+      the user to select multiple rows at a time. Access the selection(s) as
+      `<id>.input_cell_selection()["rows"]`.
     apps:
     - title: Preview
       file: app-variation-select-rows-core.py
@@ -126,13 +127,15 @@ To make a reactive Data Grid, follow three steps:
 
   2. Within the server function, define a new function whose name matches the id used above. The function should assemble the table to display and then return the table wrapped in `render.DataGrid()`. Shiny will rerun this function whenever it needs to build or update the output that has the matching id.
 
-  3. Decorate the function with `@render.data_frame`
+  3. Decorate the function with `@render.data_frame`.
 
-A Data Grid can also collect input from the user. To allow this, set `render.DataGrid(row_selection_mode="single")` or `render.DataGrid(row_selection_mode="multiple")` to allow the user to select one or more rows of the Data Grid.
+A Data Grid can also collect input from the user. To allow this, set `render.DataGrid(selection_mode="row")` or `render.DataGrid(selection_mode="rows")` to allow the user to select one or more rows of the Data Grid.
 
-The indices of the selected rows will be accessible within the server function as a reactive variable returned by `input.<id>_selected_rows()`, where <id> is the id of the `ui.output_data_frame()` associated with the table.
+The indices of the selected rows will be accessible within the server function as a reactive variable returned by `<name>.input_cell_selection()["rows"]`, where <name> is the name of the function decorated with `@render.data_frame`.
 
-The value returned will be `None` if no rows are selected, or a tuple of integers representing the indices of the selected rows. To filter a pandas data frame down to the selected rows, use `df.iloc[list(input.<id>_selected_rows())]`.
+The value returned will be an empty tuple if no rows are selected, or a tuple of integers representing the indices of the selected rows. To filter a pandas data frame down to the selected rows, use `df.iloc[list(<name>.input_cell_selection()["rows"])]`.
+
+For more information about interacting with data frames, see the API documentation for [Express](../../../api/express/express.render.data_frame.qmd) or [Core](../../../api/core/render.data_frame.qmd) syntax.
 
 If your table is a data frame that uses the pandas styler, replace `ui.output_data_frame()` with `ui.output_table()` and `@render.data_frame` with `@render.table`.
 

components/outputs/datatable/app-variation-select-rows-core.py

@@ -13,11 +13,11 @@
 def server(input, output, session):
     @render.data_frame
     def penguins_df():
-        return render.DataTable(penguins, row_selection_mode="single")  # <<
+        return render.DataTable(penguins, selection_mode="rows")  # <<
 
     @render.ui
     def rows():
-        rows = input.penguins_df_selected_rows()  # <<
+        rows = penguins_df.input_cell_selection()["rows"]  # <<
         selected = ", ".join(str(i) for i in sorted(rows)) if rows else "None"
         return f"Rows selected: {selected}"
 

components/outputs/datatable/app-variation-select-rows-express.py

@@ -9,11 +9,11 @@
 
 @render.ui
 def rows():
-    rows = input.penguins_df_selected_rows()  # <<
+    rows = penguins_df.input_cell_selection()["rows"]  # <<
     selected = ", ".join(str(i) for i in sorted(rows)) if rows else "None"
     return f"Rows selected: {selected}"
 
 
 @render.data_frame
 def penguins_df():
-    return render.DataTable(penguins, row_selection_mode="single")  # <<
+    return render.DataTable(penguins, selection_mode="rows")  # <<

components/outputs/datatable/index.qmd

@@ -45,9 +45,10 @@ listing:
     dir: components/outputs/datatable/
   contents:
   - title: Select Rows
-    description: Set `row_selection_mode` in `render.DataTable()` to `"single"` to
-      allow the user to select one row at a time. Set it to `"multiple"` to allow
-      the user to select multiple rows at a time. Access the selection(s) as `input.<id>_selected_rows()`.
+    description: Set `selection_mode` in `render.DataTable()` to `"row"` to
+      allow the user to select one row at a time. Set it to `"rows"` to allow
+      the user to select multiple rows at a time. Access the selection(s) as
+      `<id>.input_cell_selection()["rows"]`.
     apps:
     - title: Preview
       file: app-variation-select-rows-core.py
@@ -126,16 +127,15 @@ To make a reactive Data Table, follow three steps:
 
   2. Within the server function, define a new function whose name matches the id used above. The function should assemble the table to display and then return the table wrapped in `render.DataTable()`. Shiny will rerun this function whenever it needs to build or update the output that has the matching id.
 
-  3. Decorate the function with two decorators:
+  3. Decorate the function with `@render.data_frame`.
 
-      1. `@output`
-      2. `@render.data_frame`
+A Data Table can also collect input from the user. To allow this, set `render.DataTable(selection_mode="row")` or `render.DataTable(selection_mode="rows")` to allow the user to select one or more rows of the Data Table.
 
-A DataTable can also collect input from the user. To allow this, set `render.DataTable(row_selection_mode="single")` or `render.DataTable(row_selection_mode="multiple")` to allow the user to select one or more rows of the DataTable.
+The indices of the selected rows will be accessible within the server function as a reactive variable returned by `<name>.input_cell_selection()["rows"]`, where <name> is the name of the function decorated with `@render.data_frame`.
 
-The indices of the selected rows will be accessible within the server function as a reactive variable returned by `input.<id>_selected_rows()`, where <id> is the id of the `ui.output_data_frame()` associated with the table.
+The value returned will be an empty tuple if no rows are selected, or a tuple of integers representing the indices of the selected rows. To filter a pandas data frame down to the selected rows, use `df.iloc[list(<name>.input_cell_selection()["rows"])]`.
 
-The value returned will be `None` if no rows are selected, or a tuple of integers representing the indices of the selected rows. To filter a pandas data frame down to the selected rows, use `df.iloc[list(input.<id>_selected_rows())]`.
+For more information about interacting with data frames, see the API documentation for [Express](../../../api/express/express.render.data_frame.qmd) or [Core](../../../api/core/render.data_frame.qmd) syntax.
 
 If your table is a data frame that uses the pandas styler, replace `ui.output_data_frame()` with `ui.output_table()` and `@render.data_frame` with `@render.table`.