Add documentation to nested editor

examples/reference/widgets/Tabulator.ipynb

@@ -265,6 +265,62 @@
     "edit_table.on_edit(lambda e: print(e.column, e.row, e.old, e.value))"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Nested editor\n",
+    "Suppose you want an editor to depend on values in another cell. The `nested` type can be used. The `nested` type needs two arguments, `options` and `lookup_order`; the latter describes how the `options` should be looked up. \n",
+    "\n",
+    "Let's create a simple DataFrame with three columns, the `2` column now depends on the values in the `0` and `1` column. If the `0` is `A`, the `2` column should always be between 1 and 5. If the `0` column is `B`, the `2` column will now also depend on the `1` column. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "options = {\n",
+    "    \"A\": [1, 2, 3, 4, 5],\n",
+    "    \"B\": {\"1\": [6, 7, 8, 9, 10], \"2\": [11, 12, 13, 14, 15]},\n",
+    "}\n",
+    "tabulator_editors = {\n",
+    "    \"0\": {\"type\": \"list\", \"values\": [\"A\", \"B\"]},\n",
+    "    \"1\": {\"type\": \"list\", \"values\": [1, 2]},\n",
+    "    \"2\": {\"type\": \"nested\", \"options\": options, \"lookup_order\": [\"0\", \"1\"]},\n",
+    "}\n",
+    "\n",
+    "nested_df = pd.DataFrame({\"0\": [\"A\", \"B\"], \"1\": [1, 2], \"2\": [None, None]})\n",
+    "nested_table = pn.widgets.Tabulator(nested_df, editors=tabulator_editors, show_index=False)\n",
+    "nested_table"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Some things to note about the `nested` editor:\n",
+    "- Only string keys can be used in `options` dictionary. \n",
+    "- Care must be taken so there is always a valid option for the `nested` editor.\n",
+    "- No guarantee is made that the value shown is a `nested` editor is a valid option.\n",
+    "\n",
+    "For the last point, you can use an `on_edit` callback, which either change the value or clear it. Below is an example of how to clear it."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def clear_nested_column(event):\n",
+    "    if event.column in [\"0\", \"1\"]:\n",
+    "        nested_table.patch({\"2\": [(event.row, None)]})\n",
+    "\n",
+    "nested_table.on_edit(clear_nested_column)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},