wire webview messaging test and document basic table view setup parts (#8)

Author: RandomFractals

src/utils/fileUtils.ts

@@ -1,5 +1,16 @@
 import { Uri, Webview } from 'vscode';
 
+/**
+ * Gets webview Uri for a given file or resource.
+ *
+ * @remarks This Uri can be used within a webview's HTML as a link to the
+ * given file or resource.
+ *
+ * @param webview Reference to the extension webview
+ * @param extensionUri Extension directory Uri
+ * @param pathList File or resource path parts
+ * @returns Webview Uri for requested file or resource
+ */
 export function getUri(webview: Webview, extensionUri: Uri, pathList: string[]): Uri {
   return webview.asWebviewUri(Uri.joinPath(extensionUri, ...pathList));
 }

src/views/tableView.ts

@@ -12,34 +12,63 @@ import {
 
 import { getUri } from '../utils/fileUtils';
 
+/**
+ * Defines Table view class for managing state and behaviour of Table webview panels.
+ */
 export class TableView {
   public static currentView: TableView | undefined;
   private readonly _webviewPanel: WebviewPanel;
   private _disposables: Disposable[] = [];
 
+  /**
+   * Creates new TableView instance for the initial table data rendering.
+   * 
+   * @param webviewPanel Reference to the webview panel
+   * @param extensionUri Extension directory Uri
+   */
   private constructor(webviewPanel: WebviewPanel, extensionUri: Uri) {
     this._webviewPanel = webviewPanel;
+
+    // dispose table view resources when table view panel is closed by the user or via vscode apis
     this._webviewPanel.onDidDispose(this.dispose, null, this._disposables);
+
+    // set table view html content for the webview panel
     this._webviewPanel.webview.html = this.getWebviewContent(this._webviewPanel.webview, extensionUri);
+
+    // add webview messaging and commands handler
+    this.addWebviewMessageListener(this._webviewPanel.webview);
   }
 
+  /**
+   * Reveals current table view or creates new table webview panel for table data display.
+   * 
+   * @param extensionUri Extension directory Uri
+   */
   public static render(extensionUri: Uri) {
     if (TableView.currentView) {
+      // show current table webview panel
       TableView.currentView._webviewPanel.reveal(ViewColumn.Active);
     }
     else {
-      const webviewPanel = window.createWebviewPanel('tableView', 'Table View', {
-          viewColumn: ViewColumn.Active,
+      const webviewPanel = window.createWebviewPanel(
+        'tableView', // webview panel type
+        'Table View', // webview panel title
+        {
+          viewColumn: ViewColumn.Active, // use active view column for display
           preserveFocus: true
-        }, { // weview panel options
-          enableScripts: true,
-          enableCommandUris: true
+        }, 
+        { // weview panel options
+          enableScripts: true, // enable JavaScript in webview
+          enableCommandUris: true // ???
         }
       );
       TableView.currentView = new TableView(webviewPanel, extensionUri);
     }
   }
 
+  /**
+   * Disposes table view resources when webview panel is closed.
+   */
   public dispose() {
     TableView.currentView = undefined;
     this._webviewPanel.dispose();
@@ -51,22 +80,34 @@ export class TableView {
     }
   }
 
-  private getWebviewContent(webview: Webview, extensionUri: Uri) {
-    const toolkitUri: Uri = getUri(webview, extensionUri, [
+  /**
+   * Creates webview html content for the webview panel display.
+   * 
+   * @param webview Reference to the extensions webview
+   * @param extensionUri Extension directory Uri
+   * @returns Html string for the webview content
+   */
+  private getWebviewContent(webview: Webview, extensionUri: Uri): string {
+    const webviewUiToolkitUri: Uri = getUri(webview, extensionUri, [
       'node_modules',
       '@vscode',
       'webview-ui-toolkit',
       'dist',
       'toolkit.js',
     ]);
 
+    const tableViewUri: Uri = getUri(webview, extensionUri, ['web', 'scripts', 'tableView.js']);
+
+    // Tip: Install the es6-string-html VS Code extension 
+    // to enable html code highlighting below
     return /*html*/ `
       <!DOCTYPE html>
       <html lang="en">
         <head>
           <meta charset="UTF-8">
           <meta name="viewport" content="width=device-width, initial-scale=1.0">
-          <script type="module" src="${toolkitUri}"></script>
+          <script type="module" src="${webviewUiToolkitUri}"></script>
+          <script type="module" src="${tableViewUri}"></script>
           <title>Table View</title>
         </head>
         <body>
@@ -76,4 +117,25 @@ export class TableView {
       </html>
     `;
   }
-}
+
+  /**
+  * Adds webivew messaging support and executes commands
+  * based on the message command received.
+  *
+  * @param webview Reference to the extension webview
+  */
+  private addWebviewMessageListener(webview: Webview) {
+    webview.onDidReceiveMessage((message: any) => {
+        const command: string = message.command;
+        const text = message.text;
+        switch (command) {
+          case 'hello':
+            window.showInformationMessage(text);
+            break;
+        }
+      }, 
+      undefined, // args
+      this._disposables
+    );
+  }
+}

web/scripts/tableView.js

@@ -0,0 +1,25 @@
+// initialize vscode api
+const vscode = acquireVsCodeApi();
+
+// add page load handler
+window.addEventListener('load', initializeView);
+
+/**
+ * Initializes table webview.
+ */
+function initializeView() {
+  const testButton = document.getElementById('test-button');
+  testButton.addEventListener('click', onTestClick);
+}
+
+/**
+ * Handles test button click.
+ * 
+ * @see https://code.visualstudio.com/api/extension-guides/webview#passing-messages-from-an-extension-to-a-webview
+ */
+function onTestClick() {
+  vscode.postMessage({
+    command: 'hello',
+    text: 'Hey there partner! 🤠'
+  });
+}