Added output type argument to $ function.

CHANGELOG.md

@@ -37,7 +37,6 @@ Please see the documentation for archived changelogs - a new archive is produced
 
 ### Ideas
 
-* Consider adding 2nd parameter to `$` and `$$` to allow returning something other than the found element. [Ref](https://www.npmjs.com/package/x-ray#xrayurl-selectorfn) - e.g. `text`, `html`, `attributes`
 * Change runtime parameter passes of `uib` to `globalThis['ti-uibuilder'].uib`
 * Consider moving all handling of uib's package.json into a single lib. Only allow a single function to read/write/update
 * Add Vue-style dynamic attributes: [ref1](https://claude.ai/chat/0c494f54-758c-4f14-a8c7-90dbe6b2c5d7), [ref2](https://chatgpt.com/c/7b797547-4e7e-455d-927b-926de42171aa).
@@ -320,6 +319,8 @@ Most of these changes will *not* impact most people but you should check through
     *  `<uib-meta>` Display's facts about the current page such as its file size, when it was created and when it was last updated.
     *  `<apply-template>` Takes the content of a `<template>` HTML tag and appends that content as children of itself. Allowing you to re-use standard, repeatable HTML without the need for JavaScript coding and without the need of sending potentially lengthy HTML from Node-RED every time it is needed.
 
+  * The `$` function now allows a second parameter to change the output. Previously the output would always be the DOM Element. Now you can return the inner text, inner HTML or a list of attributes of the element. e.g. `$('.myelement', 'text')`
+
   * Lots of extensions and improvements to the `uibrouter` front-end routing library in this release:
 
     * You can now define a set of external html files (that can include scripts and css just like routes) that are immediately loaded to the page. These can be defined in the initial router config when they will be loaded immediately (before routes) or can be manually loaded later. Use these for things like menu's or other fixed parts of the UI.
@@ -438,6 +439,8 @@ The `URL Output?` setting will change the output from a folder/file list to a re
 
 ### uibuilder front-end library
 
+* The `$` function now allows a second parameter to change the output. Previously the output would always be the DOM Element. Now you can return the inner text, inner HTML or a list of attributes of the element. e.g. `$('.myelement', 'text')`
+
 * **BUG FIX** - `uib-topic` attribute processing was not working for routes added with `uib-router`. Now fixed.
 
 * **NEW FEATURE** - The library now actively monitors for `uib-topic` or `data-uib-topic` attributes on **ANY** HTML tag. Where present, a message listener is set up. Messages from Node-RED that match the topic will have their `msg.payload` inserted as the content of the tag (replacing any previous content) and any `msg.attributes` (key/value object) will add/replace attributes on the tag.

front-end/ui.esm.js

@@ -516,9 +516,10 @@ var require_ui = __commonJS({
        * If the selected element is a <template>, returns the first child element.
        * type {HTMLElement}
        * @param {string} cssSelector A CSS Selector that identifies the element to return
-       * @returns {HTMLElement|null} Selected HTML element or null
+       * @param {"el"|"text"|"html"|"attributes"|"attr"} [output] Optional. What type of output to return. Defaults to "el", the DOM element reference
+       * @returns {HTMLElement|string|InnerHTML|array|null} Selected HTML DOM element, innerText, innerHTML, attribute list or null
        */
-      $(cssSelector) {
+      $(cssSelector, output) {
         let el = _a.doc.querySelector(cssSelector);
         if (!el) {
           _a.log(1, "Uib:$", `No element found for CSS selector ${cssSelector}`)();
@@ -531,7 +532,36 @@ var require_ui = __commonJS({
             return null;
           }
         }
-        return el;
+        if (!output) output = "el";
+        let out;
+        try {
+          switch (output.toLowerCase()) {
+            case "text": {
+              out = el.innerText;
+              break;
+            }
+            case "html": {
+              out = el.innerHTML;
+              break;
+            }
+            case "attr":
+            case "attributes": {
+              out = {};
+              for (const attr of el.attributes) {
+                out[attr.name] = attr.value;
+              }
+              break;
+            }
+            default: {
+              out = el;
+              break;
+            }
+          }
+        } catch (e) {
+          out = el;
+          _a.log(1, "Uib:$", `Could not process output type "${output}" for CSS selector ${cssSelector}, returned the DOM element. ${e.message}`, e)();
+        }
+        return out;
       }
       /** CSS query selector that returns ALL found selections. Matches the Chromium DevTools feature of the same name.
        * NOTE that this fn returns an array showing the PROPERTIES of the elements whereas $ returns the element itself

front-end/ui.iife.js

@@ -517,9 +517,10 @@
          * If the selected element is a <template>, returns the first child element.
          * type {HTMLElement}
          * @param {string} cssSelector A CSS Selector that identifies the element to return
-         * @returns {HTMLElement|null} Selected HTML element or null
+         * @param {"el"|"text"|"html"|"attributes"|"attr"} [output] Optional. What type of output to return. Defaults to "el", the DOM element reference
+         * @returns {HTMLElement|string|InnerHTML|array|null} Selected HTML DOM element, innerText, innerHTML, attribute list or null
          */
-        $(cssSelector) {
+        $(cssSelector, output) {
           let el = _a.doc.querySelector(cssSelector);
           if (!el) {
             _a.log(1, "Uib:$", `No element found for CSS selector ${cssSelector}`)();
@@ -532,7 +533,36 @@
               return null;
             }
           }
-          return el;
+          if (!output) output = "el";
+          let out;
+          try {
+            switch (output.toLowerCase()) {
+              case "text": {
+                out = el.innerText;
+                break;
+              }
+              case "html": {
+                out = el.innerHTML;
+                break;
+              }
+              case "attr":
+              case "attributes": {
+                out = {};
+                for (const attr of el.attributes) {
+                  out[attr.name] = attr.value;
+                }
+                break;
+              }
+              default: {
+                out = el;
+                break;
+              }
+            }
+          } catch (e) {
+            out = el;
+            _a.log(1, "Uib:$", `Could not process output type "${output}" for CSS selector ${cssSelector}, returned the DOM element. ${e.message}`, e)();
+          }
+          return out;
         }
         /** CSS query selector that returns ALL found selections. Matches the Chromium DevTools feature of the same name.
          * NOTE that this fn returns an array showing the PROPERTIES of the elements whereas $ returns the element itself

front-end/uibuilder.esm.js

@@ -555,9 +555,10 @@ var require_ui = __commonJS({
        * If the selected element is a <template>, returns the first child element.
        * type {HTMLElement}
        * @param {string} cssSelector A CSS Selector that identifies the element to return
-       * @returns {HTMLElement|null} Selected HTML element or null
+       * @param {"el"|"text"|"html"|"attributes"|"attr"} [output] Optional. What type of output to return. Defaults to "el", the DOM element reference
+       * @returns {HTMLElement|string|InnerHTML|array|null} Selected HTML DOM element, innerText, innerHTML, attribute list or null
        */
-      $(cssSelector) {
+      $(cssSelector, output) {
         let el = _a2.doc.querySelector(cssSelector);
         if (!el) {
           _a2.log(1, "Uib:$", `No element found for CSS selector ${cssSelector}`)();
@@ -570,7 +571,36 @@ var require_ui = __commonJS({
             return null;
           }
         }
-        return el;
+        if (!output) output = "el";
+        let out;
+        try {
+          switch (output.toLowerCase()) {
+            case "text": {
+              out = el.innerText;
+              break;
+            }
+            case "html": {
+              out = el.innerHTML;
+              break;
+            }
+            case "attr":
+            case "attributes": {
+              out = {};
+              for (const attr of el.attributes) {
+                out[attr.name] = attr.value;
+              }
+              break;
+            }
+            default: {
+              out = el;
+              break;
+            }
+          }
+        } catch (e) {
+          out = el;
+          _a2.log(1, "Uib:$", `Could not process output type "${output}" for CSS selector ${cssSelector}, returned the DOM element. ${e.message}`, e)();
+        }
+        return out;
       }
       /** CSS query selector that returns ALL found selections. Matches the Chromium DevTools feature of the same name.
        * NOTE that this fn returns an array showing the PROPERTIES of the elements whereas $ returns the element itself

front-end/uibuilder.iife.js

@@ -556,9 +556,10 @@
          * If the selected element is a <template>, returns the first child element.
          * type {HTMLElement}
          * @param {string} cssSelector A CSS Selector that identifies the element to return
-         * @returns {HTMLElement|null} Selected HTML element or null
+         * @param {"el"|"text"|"html"|"attributes"|"attr"} [output] Optional. What type of output to return. Defaults to "el", the DOM element reference
+         * @returns {HTMLElement|string|InnerHTML|array|null} Selected HTML DOM element, innerText, innerHTML, attribute list or null
          */
-        $(cssSelector) {
+        $(cssSelector, output) {
           let el = _a2.doc.querySelector(cssSelector);
           if (!el) {
             _a2.log(1, "Uib:$", `No element found for CSS selector ${cssSelector}`)();
@@ -571,7 +572,36 @@
               return null;
             }
           }
-          return el;
+          if (!output) output = "el";
+          let out;
+          try {
+            switch (output.toLowerCase()) {
+              case "text": {
+                out = el.innerText;
+                break;
+              }
+              case "html": {
+                out = el.innerHTML;
+                break;
+              }
+              case "attr":
+              case "attributes": {
+                out = {};
+                for (const attr of el.attributes) {
+                  out[attr.name] = attr.value;
+                }
+                break;
+              }
+              default: {
+                out = el;
+                break;
+              }
+            }
+          } catch (e) {
+            out = el;
+            _a2.log(1, "Uib:$", `Could not process output type "${output}" for CSS selector ${cssSelector}, returned the DOM element. ${e.message}`, e)();
+          }
+          return out;
         }
         /** CSS query selector that returns ALL found selections. Matches the Chromium DevTools feature of the same name.
          * NOTE that this fn returns an array showing the PROPERTIES of the elements whereas $ returns the element itself

nodes/libs/ui.js

@@ -519,9 +519,10 @@ const Ui = class Ui2 {
    * If the selected element is a <template>, returns the first child element.
    * type {HTMLElement}
    * @param {string} cssSelector A CSS Selector that identifies the element to return
-   * @returns {HTMLElement|null} Selected HTML element or null
+   * @param {"el"|"text"|"html"|"attributes"|"attr"} [output] Optional. What type of output to return. Defaults to "el", the DOM element reference
+   * @returns {HTMLElement|string|InnerHTML|array|null} Selected HTML DOM element, innerText, innerHTML, attribute list or null
    */
-  $(cssSelector) {
+  $(cssSelector, output) {
     let el = Ui2.doc.querySelector(cssSelector);
     if (!el) {
       Ui2.log(1, "Uib:$", `No element found for CSS selector ${cssSelector}`)();
@@ -534,7 +535,36 @@ const Ui = class Ui2 {
         return null;
       }
     }
-    return el;
+    if (!output) output = "el";
+    let out;
+    try {
+      switch (output.toLowerCase()) {
+        case "text": {
+          out = el.innerText;
+          break;
+        }
+        case "html": {
+          out = el.innerHTML;
+          break;
+        }
+        case "attr":
+        case "attributes": {
+          out = {};
+          for (const attr of el.attributes) {
+            out[attr.name] = attr.value;
+          }
+          break;
+        }
+        default: {
+          out = el;
+          break;
+        }
+      }
+    } catch (e) {
+      out = el;
+      Ui2.log(1, "Uib:$", `Could not process output type "${output}" for CSS selector ${cssSelector}, returned the DOM element. ${e.message}`, e)();
+    }
+    return out;
   }
   /** CSS query selector that returns ALL found selections. Matches the Chromium DevTools feature of the same name.
    * NOTE that this fn returns an array showing the PROPERTIES of the elements whereas $ returns the element itself

src/front-end-module/ui.js

@@ -738,9 +738,10 @@ const Ui = class Ui {
      * If the selected element is a <template>, returns the first child element.
      * type {HTMLElement}
      * @param {string} cssSelector A CSS Selector that identifies the element to return
-     * @returns {HTMLElement|null} Selected HTML element or null
+     * @param {"el"|"text"|"html"|"attributes"|"attr"} [output] Optional. What type of output to return. Defaults to "el", the DOM element reference
+     * @returns {HTMLElement|string|InnerHTML|array|null} Selected HTML DOM element, innerText, innerHTML, attribute list or null
      */
-    $(cssSelector) {
+    $(cssSelector, output) {
         /** @type {*} Some kind of HTML element */
         let el = Ui.doc.querySelector(cssSelector)
 
@@ -757,7 +758,41 @@ const Ui = class Ui {
             }
         }
 
-        return el
+        if (!output) output = 'el'
+        let out
+
+        try {
+            switch (output.toLowerCase()) {
+                case 'text': {
+                    out = el.innerText
+                    break
+                }
+
+                case 'html': {
+                    out = el.innerHTML
+                    break
+                }
+
+                case 'attr':
+                case 'attributes': {
+                    out = {}
+                    for (const attr of el.attributes) {
+                        out[attr.name] = attr.value
+                    }
+                    break
+                }
+
+                default: {
+                    out = el
+                    break
+                }
+            }
+        } catch (e) {
+            out = el
+            Ui.log(1, 'Uib:$', `Could not process output type "${output}" for CSS selector ${cssSelector}, returned the DOM element. ${e.message}`, e)()
+        }
+
+        return out
     }
 
     /** CSS query selector that returns ALL found selections. Matches the Chromium DevTools feature of the same name.