Follow links (#34)

Refactors the click handling, and adds built in functionality to follow http(s) links. Users will be able to extend with their own click handlers.

Author: MichaelDoyle

projects/demo/src/app/app.component.html

@@ -2,17 +2,20 @@ <h2>ngx-json-treeview</h2>
 
 <h3>Collapsed</h3>
 <div class="json-container">
-  <ngx-json-treeview [json]="json" [expanded]="false" />
+  <ngx-json-treeview
+    [json]="json"
+    [expanded]="false"
+    [enableClickableValues]="true" />
 </div>
 
 <h3>Max Depth (1)</h3>
 <div class="json-container">
-  <ngx-json-treeview [json]="json" [depth]="1" />
+  <ngx-json-treeview [json]="json" [depth]="1" [enableClickableValues]="true" />
 </div>
 
 <h3>Fully Expanded</h3>
 <div class="json-container">
-  <ngx-json-treeview [json]="json" />
+  <ngx-json-treeview [json]="json" [enableClickableValues]="true" />
 </div>
 
 <h3>Clickable Nodes</h3>
@@ -22,16 +25,14 @@ <h4>Object</h4>
     <ngx-json-treeview
       [json]="json"
       [expanded]="false"
-      [isClickableValue]="isClickablePrimitiveValue"
-      [enableClickableValues]="true"
-      (onValueClick)="onValueClick($event)" />
+      [valueClickHandlers]="clickHandlers"
+      [enableClickableValues]="true" />
     <h4>Primitives</h4>
     @for (primitive of primitives; track $index) {
       <ngx-json-treeview
         [json]="primitive"
-        [isClickableValue]="isClickablePrimitiveValue"
-        [enableClickableValues]="true"
-        (onValueClick)="onValueClick($event)" />
+        [valueClickHandlers]="primitiveClickHandlers"
+        [enableClickableValues]="true" />
     }
   </div>
   @let segment = currentSegment();

projects/demo/src/app/app.component.ts

@@ -1,5 +1,9 @@
 import { Component, signal } from '@angular/core';
-import { NgxJsonTreeviewComponent, Segment } from 'ngx-json-treeview';
+import {
+  NgxJsonTreeviewComponent,
+  Segment,
+  ValueClickHandler,
+} from 'ngx-json-treeview';
 
 @Component({
   selector: 'app-root',
@@ -45,17 +49,27 @@ export class AppComponent {
     },
   };
 
-  isClickableValue(segment: Segment) {
-    return ['object', 'array', 'string'].includes(segment.type ?? '');
-  }
-
-  isClickablePrimitiveValue(segment: Segment) {
-    return ['string'].includes(segment.type ?? '');
-  }
+  clickHandlers: ValueClickHandler[] = [
+    {
+      canHandle: (segment: Segment) => {
+        return ['object', 'array', 'string'].includes(segment.type ?? '');
+      },
+      handler: (segment: Segment) => {
+        this.currentSegment.set(segment);
+      },
+    },
+  ];
 
-  onValueClick(segment: Segment) {
-    this.currentSegment.set(segment);
-  }
+  primitiveClickHandlers: ValueClickHandler[] = [
+    {
+      canHandle: (segment: Segment) => {
+        return ['string'].includes(segment.type ?? '');
+      },
+      handler: (segment: Segment) => {
+        this.currentSegment.set(segment);
+      },
+    },
+  ];
 
   stringify(obj: any) {
     if (typeof obj === 'function') {

projects/ngx-json-treeview/src/lib/handlers.ts

@@ -0,0 +1,38 @@
+import { ValueClickHandler } from './types';
+
+/**
+ * A handler that checks if a segment's value is a string that looks like an
+ * HTTP/HTTPS link. If it is, it opens the link in a new tab.
+ */
+export const followLinkHandler: ValueClickHandler = {
+  canHandle: (segment) => {
+    if (typeof segment.value === 'string' && segment.value.startsWith('http')) {
+      try {
+        const url = new URL(segment.value); // Validate the URL.
+        return url.protocol === 'http:' || url.protocol === 'https:';
+      } catch (e) {
+        // Invalid URL.
+      }
+    }
+    return false;
+  },
+  handler: (segment) => {
+    window.open(segment.value, '_blank', 'noopener,noreferrer');
+  },
+};
+
+/**
+ * A collection of built-in value click handlers.
+ * This array can be used to easily apply all default handlers.
+ */
+export const VALUE_CLICK_HANDLERS: readonly ValueClickHandler[] = [
+  followLinkHandler,
+];
+
+/**
+ * A namespace for individual value click handlers.
+ * This allows for easy discovery and individual import of handlers.
+ */
+export const ValueClickHandlers = {
+  followLinkHandler,
+};

projects/ngx-json-treeview/src/lib/ngx-json-treeview/ngx-json-treeview.component.html

@@ -88,11 +88,9 @@
               [json]="segment.value"
               [expanded]="expanded()"
               [depth]="depth()"
-              [isClickableValue]="isClickableValue()"
               [enableClickableValues]="enableClickableValues()"
               [_parent]="segment"
-              [_currentDepth]="_currentDepth() + 1"
-              (onValueClick)="onValueClickHandler($event)" />
+              [_currentDepth]="_currentDepth() + 1" />
             <span class="punctuation">
               {{ closingBrace }}{{ needsComma ? ',' : '' }}
             </span>

projects/ngx-json-treeview/src/lib/ngx-json-treeview/ngx-json-treeview.component.ts

@@ -1,6 +1,7 @@
 import { Component, computed, inject, input, output } from '@angular/core';
+import { VALUE_CLICK_HANDLERS } from '../handlers';
 import { ID_GENERATOR } from '../services/id-generator';
-import { IsClickableValueFn, Segment } from '../types';
+import { IsClickableValueFn, Segment, ValueClickHandler } from '../types';
 import { decycle, previewString } from '../util';
 
 /**
@@ -40,16 +41,21 @@ export class NgxJsonTreeviewComponent {
   depth = input<number>(-1);
 
   /**
-   * If `true`, value nodes will emit an `onValueClick` event when clicked. This
-   * allows for some interesting use cases, such as:
-   * - Rendering preformatted text, html, markdown, etc in another component.
+   * If `true`, values are clickable when there is a corresponding handler
+   * in the `valueClickHandlers` array that can process it.
+   *
+   * This allows for use cases such as:
+   * - Following hyperlinks.
    * - Copying a value to the clipboard.
-   * - Following hyperlinks, etc
+   * - Triggering custom actions based on the value's content or type.
    * @default false
    */
   enableClickableValues = input<boolean>(false);
 
   /**
+   * @deprecated Use `valueClickHandlers` instead. This input will be removed
+   * in a future version.
+   *
    * A function that determines if a specific value node should be considered
    * clickable. This provides more granular control than the global
    * `enableClickableValues` flag.
@@ -61,18 +67,29 @@ export class NgxJsonTreeviewComponent {
    * @param segment - The segment being evaluated.
    * @returns `true` if the segment's value should be clickable, `false`
    * otherwise.
-   * @default () => true - By default, all values are considered clickable if
-   *   `enableClickableValues` is true.
    */
-  isClickableValue = input<IsClickableValueFn>(() => true);
+  isClickableValue = input<IsClickableValueFn>();
 
   /**
+   * @deprecated Use `valueClickHandlers` instead. This output will be removed
+   * in a future version.
+   *
    * If `enableClickableValues` is set to `true`, emits a `Segment` object when
    * a value node is clicked. The emitted `Segment` contains details about the
    * clicked node (key, value, type, path, etc.).
    */
   onValueClick = output<Segment>();
 
+  /**
+   * An array of handler functions to be executed when a value node is clicked.
+   * Only the first handler in the array for which `isClickable` returns `true`
+   * will be executed.
+   *
+   * If `enableClickableValues` is set to true, but `valueClickHandlers` is
+   * omitted, the built-in `VALUE_CLICK_HANDLERS` will be used as the default.
+   */
+  valueClickHandlers = input<ValueClickHandler[]>();
+
   /**
    * *Internal* input representing the parent segment in the tree hierarchy.
    * Primrily used for calculating paths.
@@ -87,6 +104,21 @@ export class NgxJsonTreeviewComponent {
    */
   _currentDepth = input<number>(0);
 
+  private internalValueClickHandlers = computed<ValueClickHandler[]>(() => {
+    const handlers: ValueClickHandler[] = [];
+    const legacyIsClickableFn = this.isClickableValue();
+
+    if (legacyIsClickableFn) {
+      handlers.push({
+        canHandle: legacyIsClickableFn,
+        handler: (segment) => this.onValueClick.emit(segment),
+      });
+    }
+
+    handlers.push(...(this.valueClickHandlers() ?? VALUE_CLICK_HANDLERS));
+    return handlers;
+  });
+
   rootType = computed<string>(() => {
     if (this.json() === null) {
       return 'null';
@@ -160,8 +192,18 @@ export class NgxJsonTreeviewComponent {
     );
   }
 
-  isClickable(segment: Segment) {
-    return this.enableClickableValues() && this.isClickableValue()(segment);
+  isClickable(segment: Segment): boolean {
+    if (!this.enableClickableValues()) {
+      return false;
+    }
+
+    return this.internalValueClickHandlers().some((handler) => {
+      try {
+        return handler.canHandle(segment);
+      } catch (e) {
+        return false;
+      }
+    });
   }
 
   toggle(segment: Segment) {
@@ -178,8 +220,19 @@ export class NgxJsonTreeviewComponent {
   }
 
   onValueClickHandler(segment: Segment) {
-    if (this.isClickable(segment)) {
-      this.onValueClick.emit(segment);
+    for (const handler of this.internalValueClickHandlers()) {
+      try {
+        if (handler.canHandle(segment)) {
+          try {
+            handler.handler(segment);
+          } catch (e) {
+            console.error('Error executing click handler:', e);
+          }
+          return; // Stop after the first handler is executed.
+        }
+      } catch (e) {
+        // in case of any error, continue to the next handler
+      }
     }
   }
 

projects/ngx-json-treeview/src/lib/types.ts

@@ -30,3 +30,27 @@ export interface Segment {
  * @returns `true` if the value is clickable, `false` otherwise.
  */
 export type IsClickableValueFn = (segment: Segment) => boolean;
+
+/**
+ * Represents a handler for value click events, containing both the logic to
+ * determine if a value is clickable and the handler function itself.
+ *
+ * This approach allows for a more modular and self-contained way to define
+ * click behaviors. Each handler can specify its own criteria for being active
+ * and the action to take, making it easier to manage and extend different
+ * click functionalities.
+ */
+export interface ValueClickHandler {
+  /**
+   * A function that determines whether this handler should be active for a
+   * given segment.
+   * @param segment The segment to evaluate.
+   * @returns `true` if the handler is applicable, `false` otherwise.
+   */
+  canHandle: IsClickableValueFn;
+  /**
+   * The function to execute when a clickable value is clicked.
+   * @param segment The segment that was clicked.
+   */
+  handler: (segment: Segment) => void;
+}

projects/ngx-json-treeview/src/public-api.ts

@@ -2,5 +2,10 @@
  * Public API Surface of ngx-json-treeview
  */
 
+export {
+  VALUE_CLICK_HANDLERS,
+  ValueClickHandlers,
+  followLinkHandler,
+} from './lib/handlers';
 export * from './lib/ngx-json-treeview/ngx-json-treeview.component';
 export * from './lib/types';