Expose more REPL options via query string parameters (#1573)

* Expose more REPL options via query string parameters

* fix clearCodeContentOnExecute

* Document the new REPL options

* improvements

Author: jtpio

docs/quickstart/embed-repl.md

@@ -98,3 +98,68 @@ pip install jupyterlab-gt-coar-theme
 
 See the [how-to guides](../howto/index.md) for more details on how to customize the
 environment and add more themes and extensions.
+
+### Clear cells on execute
+
+To automatically clear the previously executed cells on execute, set the
+`clearCellsOnExecute` parameter to `1`:
+
+```html
+<iframe
+  src="https://jupyterlite.github.io/demo/repl/index.html?clearCellsOnExecute=1"
+  width="100%"
+  height="100%"
+></iframe>
+```
+
+### Clear code content on execute
+
+To automatically clear the code content in the prompt cell on execute, set the
+`clearCodeContentOnExecute` parameter to `1`:
+
+```html
+<iframe
+  src="https://jupyterlite.github.io/demo/repl/index.html?clearCodeContentOnExecute=1"
+  width="100%"
+  height="100%"
+></iframe>
+```
+
+### Hide code input
+
+To hide the input cell of the executed cells, set the `hideCodeInput` parameter to `1`:
+
+```html
+<iframe
+  src="https://jupyterlite.github.io/demo/repl/index.html?hideCodeInput=1"
+  width="100%"
+  height="100%"
+></iframe>
+```
+
+### Prompt cell position
+
+To change where the prompt cell is placed, set the `promptCellPosition` parameter to
+`top`, `bottom`, `left`, or `right`:
+
+```html
+<iframe
+  src="https://jupyterlite.github.io/demo/repl/index.html?promptCellPosition=left"
+  width="100%"
+  height="100%"
+></iframe>
+```
+
+### Show or hide the kernel banner
+
+By default the REPL shows the kernel banner.
+
+To hide the banner, set the `showBanner` parameter to `0`:
+
+```html
+<iframe
+  src="https://jupyterlite.github.io/demo/repl/index.html?showBanner=0"
+  width="100%"
+  height="100%"
+></iframe>
+```

packages/repl-extension/src/index.ts

@@ -11,7 +11,7 @@ import {
 
 import { IThemeManager, IToolbarWidgetRegistry } from '@jupyterlab/apputils';
 
-import { ConsolePanel, IConsoleTracker } from '@jupyterlab/console';
+import { CodeConsole, ConsolePanel, IConsoleTracker } from '@jupyterlab/console';
 
 import { ITranslator } from '@jupyterlab/translation';
 
@@ -81,7 +81,7 @@ const consolePlugin: JupyterFrontEndPlugin<void> = {
     if (!tracker) {
       return;
     }
-    const { commands, serviceManager, started } = app;
+    const { commands, started } = app;
 
     const search = window.location.search;
     const urlParams = new URLSearchParams(search);
@@ -91,33 +91,62 @@ const consolePlugin: JupyterFrontEndPlugin<void> = {
     const theme = urlParams.get('theme')?.trim();
     const toolbar = urlParams.get('toolbar');
 
-    Promise.all([started, serviceManager.ready]).then(async () => {
-      commands.execute('console:create', { kernelPreference: { name: kernel } });
+    // normalize config options
+    const clearCellsOnExecute =
+      urlParams.get('clearCellsOnExecute') === '1' || undefined;
+    const clearCodeContentOnExecute =
+      urlParams.get('clearCodeContentOnExecute') === '0' ? false : undefined;
+    const hideCodeInput = urlParams.get('hideCodeInput') === '1' || undefined;
+    const showBanner = urlParams.get('showBanner') === '0' ? false : undefined;
+
+    const position = urlParams.get('promptCellPosition') ?? '';
+    const validPositions = ['top', 'bottom', 'left', 'right'];
+    const promptCellPosition = validPositions.includes(position)
+      ? (position as CodeConsole.PromptCellPosition)
+      : undefined;
+
+    started.then(async () => {
+      // create a new console at application startup
+      void commands.execute('console:create', {
+        kernelPreference: { name: kernel },
+      });
     });
 
-    if (theme && themeManager) {
-      const themeName = decodeURIComponent(theme);
-      themeManager.setTheme(themeName);
-    }
-
-    tracker.widgetAdded.connect(async (_, widget) => {
-      const { console } = widget;
-
+    tracker.widgetAdded.connect(async (_, panel) => {
       if (!toolbar) {
         // hide the toolbar by default if not specified
-        widget.toolbar.dispose();
+        panel.toolbar.dispose();
       }
 
-      if (code) {
-        await console.sessionContext.ready;
+      const { console: widget } = panel;
+      const { sessionContext } = widget;
+
+      await sessionContext.ready;
+      if (code.length > 0) {
         if (execute === '0') {
           const codeContent = code.join('\n');
-          console.replaceSelection(codeContent);
+          widget.replaceSelection(codeContent);
         } else {
-          code.forEach((line) => console.inject(line));
+          code.forEach((line) => widget.inject(line));
         }
       }
+
+      widget.setConfig({
+        clearCellsOnExecute,
+        clearCodeContentOnExecute,
+        hideCodeInput,
+        promptCellPosition,
+        // TODO: handling of the showBanner may not work as expected for now
+        // due to the assumption there should be a banner upstream:
+        // https://github.com/jupyterlab/jupyterlab/pull/17322
+        showBanner,
+      });
     });
+
+    if (theme && themeManager) {
+      const themeName = decodeURIComponent(theme);
+      themeManager.setTheme(themeName);
+    }
   },
 };