Add URL parameter support, enabling plugins to get and update URL parameters as long as they don't start with :

Author: ryan-sigma

.nvmrc

@@ -1 +1 @@
-v18.16.1
+v20.17.0

src/client/initialize.ts

@@ -4,6 +4,7 @@ import {
   PluginInstance,
   PluginMessageResponse,
   PluginStyle,
+  UrlParameter,
   WorkbookSelection,
   WorkbookVariable,
 } from '../types';
@@ -15,6 +16,7 @@ export function initialize<T = {}>(): PluginInstance<T> {
 
   let subscribedInteractions: Record<string, WorkbookSelection[]> = {};
   let subscribedWorkbookVars: Record<string, WorkbookVariable> = {};
+  let subscribedUrlParameters: Record<string, UrlParameter> = {};
   const registeredEffects: Record<string, () => void> = {};
 
   const listeners: {
@@ -61,6 +63,14 @@ export function initialize<T = {}>(): PluginInstance<T> {
     Object.assign(subscribedInteractions, updatedInteractions);
   });
 
+  on(
+    'wb:plugin:url-parameter:update',
+    (updatedUrlParameters: Record<string, UrlParameter>) => {
+      subscribedUrlParameters = {};
+      Object.assign(subscribedUrlParameters, updatedUrlParameters);
+    },
+  );
+
   on('wb:plugin:action-effect:invoke', (configId: string) => {
     const effect = registeredEffects[configId];
     if (!effect) {
@@ -191,6 +201,25 @@ export function initialize<T = {}>(): PluginInstance<T> {
           off('wb:plugin:selection:update', setValues);
         };
       },
+      subscribeToUrlParameter(configId, callback) {
+        validateConfigId(configId, 'url-parameter');
+        const setValues = (values: Record<string, UrlParameter>) => {
+          callback(values[configId]);
+        };
+        setValues(subscribedUrlParameters);
+        on('wb:plugin:url-parameter:update', setValues);
+        return () => {
+          off('wb:plugin:url-parameter:update', setValues);
+        };
+      },
+      getUrlParameter(configId: string) {
+        validateConfigId(configId, 'url-parameter');
+        return subscribedUrlParameters[configId];
+      },
+      setUrlParameter(configId: string, value: string) {
+        validateConfigId(configId, 'url-parameter');
+        void execPromise('wb:plugin:url-parameter:set', configId, value);
+      }
     },
     elements: {
       getElementColumns(configId) {

src/react/hooks.ts

@@ -9,6 +9,7 @@ import {
   WorkbookSelection,
   WorkbookVariable,
   PluginStyle,
+  UrlParameter,
 } from '../types';
 import { deepEqual } from '../utils/deepEqual';
 
@@ -184,6 +185,35 @@ export function useVariable(
   return [workbookVariable, setVariable];
 }
 
+/**
+ * React hook for accessing a url parameter
+ * @param {string} id ID from the config of type: 'url-parameter'
+ * @returns {[(UrlParameter | undefined), Function]} Constantly updating value of the url parameter and setter for the url parameter
+ */
+export function useUrlParameter(
+  id: string
+): [UrlParameter | undefined, (value: string) => void] {
+  const client = usePlugin();
+  const [urlParameter, setUrlParameter] = useState<UrlParameter>();
+
+  const isFirstRender = useRef<boolean>(true);
+
+  useEffect(() => {
+    if (isFirstRender.current) {
+      setUrlParameter(client.config.getUrlParameter(id));
+      isFirstRender.current = false;
+    }
+    return client.config.subscribeToUrlParameter(id, setUrlParameter);
+  }, [client, id]);
+
+  const setVariable = useCallback(
+    (value: string) => client.config.setUrlParameter(id, value),
+    [client, id],
+  );
+
+  return [urlParameter, setVariable];
+}
+
 /**
  * @deprecated Use Action API instead
  * React hook for accessing a workbook interaction selections state

src/types.ts

@@ -42,6 +42,14 @@ export interface WorkbookVariable {
   defaultValue: { type: string };
 }
 
+/**
+ * @typedef {object} UrlParameter
+ * @property {string} value Current url value
+ */
+export interface UrlParameter {
+  value: string;
+}
+
 export type WorkbookSelection = Record<string, { type: string; val?: unknown }>;
 
 export type PluginMessageResponse = MessageEvent<{
@@ -185,6 +193,10 @@ export type CustomPluginConfigOptions =
       type: 'action-effect';
       name: string;
       label?: string;
+    }
+    | {
+      type: 'url-parameter',
+      name: string
     };
 
 /**
@@ -307,6 +319,31 @@ export interface PluginInstance<T = any> {
       callback: (input: WorkbookVariable) => void,
     ): Unsubscriber;
 
+    /**
+     * Allows users to subscribe to changes in the url parameter
+     * @param {string} configId ID from config of type: 'url-parameter'
+     * @callback callback Function to be called upon receiving an updated url parameter
+     * @returns {Unsubscriber} A callable unsubscriber
+     */
+    subscribeToUrlParameter(
+      configId: string,
+      callback: (input: UrlParameter) => void,
+    ): Unsubscriber;
+
+    /**
+     * Gets the current value of a url parameter
+     * @param {string} configId ID from config of type: 'url-parameter'
+     * @returns {UrlParameter} Current value of the url parameter
+     */
+    getUrlParameter(configId: string): UrlParameter;
+
+    /**
+     * Setter for url parameter
+     * @param {string} configId ID from config of type: 'url-parameter'
+     * @param {string} value Value to assign to the url parameter
+     */
+    setUrlParameter(configId: string, value: string): void;
+
     /**
      * @deprecated Use Action API instead
      * Allows users to subscribe to changes in the passed in interaction ID