Improve plugins and drop '_backend.py'

.vscode/launch.json

@@ -24,7 +24,7 @@
       "justMyCode": false
     },
     {
-      "name": "Ipylab backend",
+      "name": "Ipylab",
       "type": "debugpy",
       "request": "launch",
       "args": [
@@ -61,7 +61,7 @@
   "compounds": [
     {
       "name": "Debug IPylab with firefox",
-      "configurations": ["Ipylab backend", "IPylab frontend with Firefox"]
+      "configurations": ["Ipylab", "IPylab frontend with Firefox"]
     }
   ]
 }

examples/generic.ipynb

@@ -15,33 +15,25 @@
    "source": [
     "# Generic methods\n",
     "\n",
-    "`AsyncWidgetBase` is the Python class that provides a set of methods that are associated with a `base` object in the Frontend. The `base` is specified on the object as part of its creation process and is fixed for the life of the object. The following methods are provided to interact with the `base`: \n",
+    "`AsyncWidgetBase` is the Python class that provides a set of methods that are associated with a `base` object in the Frontend. The `base` is specified on the object registered by its `cid`. The following methods are provided to interact with the `base`: \n",
     "\n",
     "* execute_method\n",
     "* get_property\n",
     "* set_property\n",
     "* update_property\n",
     "* list_properties\n",
-    "* list_properties (list_properties tweaked to list only the methods)\n",
-    "\n",
     "\n",
     "# Connection\n",
     "\n",
     "A disposable connection is subclassed from `AsyncWidgetBase` and is associated to a disposable object in the Frontend. Disposable connections are created when the transform is specified as `Transform.connection`. The generic methods apply directly to the disposable object. \n",
     "\n",
-    "Subclasses of `Connection` add additional features specific to the disposable. For example, `CommandConnection` is provided for commands. The type of subclass is specified by the prefix. To return \n",
-    "\n",
-    "|  Prefix                    |  Class                             |\n",
-    "| ---------------------------| ---------------------------------- |\n",
-    "|ipylab command \t         | CommandConnection                  |\n",
-    "|ipylab command pallet       | \t\t\t CommandPalletConnection  |\n",
-    "|ipylab launcher \t\t\t | LauncherConnection                 |\n",
+    "Subclasses of `Connection` add additional features specific to the disposable. For example, `CommandConnection` is provided for commands. \n",
     "\n",
     "## Making a connection\n",
     "\n",
     "The easiest way to create a connection is to specify the `transform` as a `Transform.connection`. Examples:\n",
     "\n",
-    "* [Autostart](autostart.ipynb#Example-launching-a-small-app)\n",
+    "* [Autostart](plugins.ipynb#Example-launching-a-small-app)\n",
     "* [Console](http://localhost:9999/lab/tree/commands.ipynb#Create-a-new-console)\n",
     "* [Notebook](sessions.ipynb#Create-a-new-Notebook)"
    ]
@@ -78,16 +70,22 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Some of the methods above have already been implemented in 'app.shell' on the Python object. And if you look at the code you'll see these methods use the *generic* method.\n",
+    "Some of the methods above have already been implemented in 'app.shell' on the Python object. And if you look at the code you'll see these methods use the *generic* method `execute_method`.\n",
     "\n",
-    "In case you're interested, the content of the custom message sent to the frontend looks like this:\n",
+    "In case you're interested, the custom message sent to the frontend looks like this:\n",
     "\n",
     "```python\n",
-    "{'ipylab_BE': '8f59e3d7-413e-4186-9831-09be92456997',\n",
-    " 'operation': 'listProperties',\n",
-    " 'kwgs': {'path': 'shell', 'type': 'function', 'depth': 2},\n",
-    " 'transform': 'raw'}\n",
-    "```"
+    "{\n",
+    "    \"method\": \"custom\",\n",
+    "    \"content\": '{\"ipylab_PY\": \"353695a0-1754-4d53-b758-291f70058f41\", \"operation\": \"listProperties\", \"kwgs\": {\"dottedname\": \"shell\", \"depth\": 2, \"omitHidden\": true}, \"transform\": \"raw\"}',\n",
+    "}\n",
+    "```\n",
+    "\n",
+    "Note the *content* is always JSON string. This is because we convert every message to JSON prior to sending making it possible to replace widgets and code objects with string representations. For widgets, it is necessary to instruct the frontend what to do with the widget. Currently there are the following additional options:\n",
+    "1. `toLuminoWidget`: Replace with a widget in the frontend.\n",
+    "2. `toObject`: Replace with an object in the frontend.\n",
+    "\n",
+    "These options are lists of attributes as they appear in the frontend that should be transformed/extracted."
    ]
   },
   {
@@ -145,7 +143,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.14"
+   "version": "3.10.15"
   }
  },
  "nbformat": 4,