src/Linkifier.ts

   1 /**
   2  * @license MIT
   3  */
   4
   5 import { LinkMatcherOptions } from './Interfaces';
   6 import { LinkMatcher, LinkMatcherHandler, LinkMatcherValidationCallback } from './Types';
   7
   8 const INVALID_LINK_CLASS = 'xterm-invalid-link';
   9
  10 const protocolClause = '(https?:\\/\\/)';
  11 const domainCharacterSet = '[\\da-z\\.-]+';
  12 const negatedDomainCharacterSet = '[^\\da-z\\.-]+';
  13 const domainBodyClause = '(' + domainCharacterSet + ')';
  14 const tldClause = '([a-z\\.]{2,6})';
  15 const ipClause = '((\\d{1,3}\\.){3}\\d{1,3})';
  16 const localHostClause = '(localhost)';
  17 const portClause = '(:\\d{1,5})';
  18 const hostClause = '((' + domainBodyClause + '\\.' + tldClause + ')|' + ipClause + '|' + localHostClause + ')' + portClause + '?';
  19 const pathClause = '(\\/[\\/\\w\\.\\-%~]*)*';
  20 const queryStringHashFragmentCharacterSet = '[0-9\\w\\[\\]\\(\\)\\/\\?\\!#@$%&\'*+,:;~\\=\\.\\-]*';
  21 const queryStringClause = '(\\?' + queryStringHashFragmentCharacterSet + ')?';
  22 const hashFragmentClause = '(#' + queryStringHashFragmentCharacterSet + ')?';
  23 const negatedPathCharacterSet = '[^\\/\\w\\.\\-%]+';
  24 const bodyClause = hostClause + pathClause + queryStringClause + hashFragmentClause;
  25 const start = '(?:^|' + negatedDomainCharacterSet + ')(';
  26 const end = ')($|' + negatedPathCharacterSet + ')';
  27 const strictUrlRegex = new RegExp(start + protocolClause + bodyClause + end);
  28
  29 /**
  30  * The ID of the built in http(s) link matcher.
  31  */
  32 const HYPERTEXT_LINK_MATCHER_ID = 0;
  33
  34 /**
  35  * The Linkifier applies links to rows shortly after they have been refreshed.
  36  */
  37 export class Linkifier {
  38   /**
  39    * The time to wait after a row is changed before it is linkified. This prevents
  40    * the costly operation of searching every row multiple times, potentially a
  41    * huge amount of times.
  42    */
  43   protected static TIME_BEFORE_LINKIFY = 200;
  44
  45   protected _linkMatchers: LinkMatcher[];
  46
  47   private _document: Document;
  48   private _rows: HTMLElement[];
  49   private _rowTimeoutIds: number[];
  50   private _nextLinkMatcherId = HYPERTEXT_LINK_MATCHER_ID;
  51
  52   constructor() {
  53     this._rowTimeoutIds = [];
  54     this._linkMatchers = [];
  55     this.registerLinkMatcher(strictUrlRegex, null, { matchIndex: 1 });
  56   }
  57
  58   /**
  59    * Attaches the linkifier to the DOM, enabling linkification.
  60    * @param document The document object.
  61    * @param rows The array of rows to apply links to.
  62    */
  63   public attachToDom(document: Document, rows: HTMLElement[]) {
  64     this._document = document;
  65     this._rows = rows;
  66   }
  67
  68   /**
  69    * Queues a row for linkification.
  70    * @param {number} rowIndex The index of the row to linkify.
  71    */
  72   public linkifyRow(rowIndex: number): void {
  73     // Don't attempt linkify if not yet attached to DOM
  74     if (!this._document) {
  75       return;
  76     }
  77
  78     const timeoutId = this._rowTimeoutIds[rowIndex];
  79     if (timeoutId) {
  80       clearTimeout(timeoutId);
  81     }
  82     this._rowTimeoutIds[rowIndex] = setTimeout(this._linkifyRow.bind(this, rowIndex), Linkifier.TIME_BEFORE_LINKIFY);
  83   }
  84
  85   /**
  86    * Attaches a handler for hypertext links, overriding default <a> behavior
  87    * for standard http(s) links.
  88    * @param {LinkHandler} handler The handler to use, this can be cleared with
  89    * null.
  90    */
  91   public attachHypertextLinkHandler(handler: LinkMatcherHandler): void {
  92     this._linkMatchers[HYPERTEXT_LINK_MATCHER_ID].handler = handler;
  93   }
  94
  95   /**
  96    * Registers a link matcher, allowing custom link patterns to be matched and
  97    * handled.
  98    * @param {RegExp} regex The regular expression to search for, specifically
  99    * this searches the textContent of the rows. You will want to use \s to match
 100    * a space ' ' character for example.
 101    * @param {LinkHandler} handler The callback when the link is called.
 102    * @param {LinkMatcherOptions} [options] Options for the link matcher.
 103    * @return {number} The ID of the new matcher, this can be used to deregister.
 104    */
 105   public registerLinkMatcher(regex: RegExp, handler: LinkMatcherHandler, options: LinkMatcherOptions = {}): number {
 106     if (this._nextLinkMatcherId !== HYPERTEXT_LINK_MATCHER_ID && !handler) {
 107       throw new Error('handler must be defined');
 108     }
 109     const matcher: LinkMatcher = {
 110       id: this._nextLinkMatcherId++,
 111       regex,
 112       handler,
 113       matchIndex: options.matchIndex,
 114       validationCallback: options.validationCallback,
 115       priority: options.priority || 0
 116     };
 117     this._addLinkMatcherToList(matcher);
 118     return matcher.id;
 119   }
 120
 121   /**
 122    * Inserts a link matcher to the list in the correct position based on the
 123    * priority of each link matcher. New link matchers of equal priority are
 124    * considered after older link matchers.
 125    * @param matcher The link matcher to be added.
 126    */
 127   private _addLinkMatcherToList(matcher: LinkMatcher): void {
 128     if (this._linkMatchers.length === 0) {
 129       this._linkMatchers.push(matcher);
 130       return;
 131     }
 132
 133     for (let i = this._linkMatchers.length - 1; i >= 0; i--) {
 134       if (matcher.priority <= this._linkMatchers[i].priority) {
 135         this._linkMatchers.splice(i + 1, 0, matcher);
 136         return;
 137       }
 138     }
 139
 140     this._linkMatchers.splice(0, 0, matcher);
 141   }
 142
 143   /**
 144    * Deregisters a link matcher if it has been registered.
 145    * @param {number} matcherId The link matcher's ID (returned after register)
 146    * @return {boolean} Whether a link matcher was found and deregistered.
 147    */
 148   public deregisterLinkMatcher(matcherId: number): boolean {
 149     // ID 0 is the hypertext link matcher which cannot be deregistered
 150     for (let i = 1; i < this._linkMatchers.length; i++) {
 151       if (this._linkMatchers[i].id === matcherId) {
 152         this._linkMatchers.splice(i, 1);
 153         return true;
 154       }
 155     }
 156     return false;
 157   }
 158
 159   /**
 160    * Linkifies a row.
 161    * @param {number} rowIndex The index of the row to linkify.
 162    */
 163   private _linkifyRow(rowIndex: number): void {
 164     const row = this._rows[rowIndex];
 165     if (!row) {
 166       return;
 167     }
 168     const text = row.textContent;
 169     for (let i = 0; i < this._linkMatchers.length; i++) {
 170       const matcher = this._linkMatchers[i];
 171       const uri = this._findLinkMatch(text, matcher.regex, matcher.matchIndex);
 172       if (uri) {
 173         const linkElement = this._doLinkifyRow(rowIndex, uri, matcher.handler, matcher.id === HYPERTEXT_LINK_MATCHER_ID);
 174         // Fire validation callback
 175         if (linkElement && matcher.validationCallback) {
 176           matcher.validationCallback(uri, isValid => {
 177             if (!isValid) {
 178               linkElement.classList.add(INVALID_LINK_CLASS);
 179             }
 180           });
 181         }
 182         // Only allow a single LinkMatcher to trigger on any given row.
 183         return;
 184       }
 185     }
 186   }
 187
 188   /**
 189    * Linkifies a row given a specific handler.
 190    * @param {number} rowIndex The index of the row to linkify.
 191    * @param {string} uri The uri that has been found.
 192    * @param {handler} handler The handler to trigger when the link is triggered.
 193    * @return The link element if it was added, otherwise undefined.
 194    */
 195   private _doLinkifyRow(rowIndex: number, uri: string, handler: LinkMatcherHandler, isHttpLinkMatcher: boolean): HTMLElement {
 196     // Iterate over nodes as we want to consider text nodes
 197     const nodes = this._rows[rowIndex].childNodes;
 198     for (let i = 0; i < nodes.length; i++) {
 199       const node = nodes[i];
 200       const searchIndex = node.textContent.indexOf(uri);
 201       if (searchIndex >= 0) {
 202         const linkElement = this._createAnchorElement(uri, handler, isHttpLinkMatcher);
 203         if (node.textContent.length === uri.length) {
 204           // Matches entire string
 205
 206           if (node.nodeType === 3 /*Node.TEXT_NODE*/) {
 207             this._replaceNode(node, linkElement);
 208           } else {
 209             const element = (<HTMLElement>node);
 210             if (element.nodeName === 'A') {
 211               // This row has already been linkified
 212               return;
 213             }
 214             element.innerHTML = '';
 215             element.appendChild(linkElement);
 216           }
 217         } else {
 218           // Matches part of string
 219           this._replaceNodeSubstringWithNode(node, linkElement, uri, searchIndex);
 220         }
 221         return linkElement;
 222       }
 223     }
 224   }
 225
 226   /**
 227    * Finds a link match in a piece of text.
 228    * @param {string} text The text to search.
 229    * @param {number} matchIndex The regex match index of the link.
 230    * @return {string} The matching URI or null if not found.
 231    */
 232   private _findLinkMatch(text: string, regex: RegExp, matchIndex?: number): string {
 233     const match = text.match(regex);
 234     if (!match || match.length === 0) {
 235       return null;
 236     }
 237     return match[typeof matchIndex !== 'number' ? 0 : matchIndex];
 238   }
 239
 240   /**
 241    * Creates a link anchor element.
 242    * @param {string} uri The uri of the link.
 243    * @return {HTMLAnchorElement} The link.
 244    */
 245   private _createAnchorElement(uri: string, handler: LinkMatcherHandler, isHypertextLinkHandler: boolean): HTMLAnchorElement {
 246     const element = this._document.createElement('a');
 247     element.textContent = uri;
 248     element.draggable = false;
 249     if (isHypertextLinkHandler) {
 250       element.href = uri;
 251       // Force link on another tab so work is not lost
 252       element.target = '_blank';
 253       element.addEventListener('click', (event: MouseEvent) => {
 254         if (handler) {
 255           return handler(event, uri);
 256         }
 257       });
 258     } else {
 259       element.addEventListener('click', (event: MouseEvent) => {
 260         // Don't execute the handler if the link is flagged as invalid
 261         if (element.classList.contains(INVALID_LINK_CLASS)) {
 262           return;
 263         }
 264         return handler(event, uri);
 265       });
 266     }
 267     return element;
 268   }
 269
 270   /**
 271    * Replace a node with 1 or more other nodes.
 272    * @param {Node} oldNode The node to replace.
 273    * @param {Node[]} newNodes The new nodes to insert in order.
 274    */
 275   private _replaceNode(oldNode: Node, ...newNodes: Node[]): void {
 276     const parent = oldNode.parentNode;
 277     for (let i = 0; i < newNodes.length; i++) {
 278       parent.insertBefore(newNodes[i], oldNode);
 279     }
 280     parent.removeChild(oldNode);
 281   }
 282
 283   /**
 284    * Replace a substring within a node with a new node.
 285    * @param {Node} targetNode The target node; either a text node or a <span>
 286    * containing a single text node.
 287    * @param {Node} newNode The new node to insert.
 288    * @param {string} substring The substring to replace.
 289    * @param {number} substringIndex The index of the substring within the string.
 290    */
 291   private _replaceNodeSubstringWithNode(targetNode: Node, newNode: Node, substring: string, substringIndex: number): void {
 292     let node = targetNode;
 293     if (node.nodeType !== 3/*Node.TEXT_NODE*/) {
 294       node = node.childNodes[0];
 295     }
 296
 297     // The targetNode will be either a text node or a <span>. The text node
 298     // (targetNode or its only-child) needs to be replaced with newNode plus new
 299     // text nodes potentially on either side.
 300     if (node.childNodes.length === 0 && node.nodeType !== Node.TEXT_NODE) {
 301       throw new Error('targetNode must be a text node or only contain a single text node');
 302     }
 303
 304     const fullText = node.textContent;
 305
 306     if (substringIndex === 0) {
 307       // Replace with <newNode><textnode>
 308       const rightText = fullText.substring(substring.length);
 309       const rightTextNode = this._document.createTextNode(rightText);
 310       this._replaceNode(node, newNode, rightTextNode);
 311     } else if (substringIndex === targetNode.textContent.length - substring.length) {
 312       // Replace with <textnode><newNode>
 313       const leftText = fullText.substring(0, substringIndex);
 314       const leftTextNode = this._document.createTextNode(leftText);
 315       this._replaceNode(node, leftTextNode, newNode);
 316     } else {
 317       // Replace with <textnode><newNode><textnode>
 318       const leftText = fullText.substring(0, substringIndex);
 319       const leftTextNode = this._document.createTextNode(leftText);
 320       const rightText = fullText.substring(substringIndex + substring.length);
 321       const rightTextNode = this._document.createTextNode(rightText);
 322       this._replaceNode(node, leftTextNode, newNode, rightTextNode);
 323     }
 324   }
 325 }