waitForKeyElements.js

/*--- waitForKeyElements():  A utility function, for Greasemonkey scripts,
    that detects and handles AJAXed content.

    Usage example:

        waitForKeyElements (
            "div.comments"
            , commentCallbackFunction
        );

        //--- Page-specific function to do what we want when the node is found.
        function commentCallbackFunction (jNode) {
            jNode.text ("This comment changed by waitForKeyElements().");
        }

    IMPORTANT: This function requires your script to have loaded jQuery.
*/
function waitForKeyElements(
  selectorTxt /* Required: The jQuery selector string that
                        specifies the desired element(s).
                    */,
  actionFunction /* Required: The code to run when elements are
                        found. It is passed a jNode to the matched
                        element.
                    */,
  bWaitOnce /* Optional: If false, will continue to scan for
                        new elements even after the first match is
                        found.
                    */,
  iframeSelector /* Optional: If set, identifies the iframe to
                        search.
                    */
) {
  let btargetsFound;

  const targetNodes =
    iframeSelector === undefined
      ? Array.from(document.querySelectorAll(selectorTxt))
      : Array.from(document.querySelectorAll(iframeSelector)).flatMap(
          (iframe) =>
            Array.from(iframe.contentWindow.document).querySelectorAll(
              selectorTxt
            )
        );

  if (targetNodes && targetNodes.length > 0) {
    btargetsFound = true;
    /*--- Found target node(s).  Go through each and act if they
            are new.
        */
    targetNodes.forEach((node) => {
      const alreadyFound = node.dataset.alreadyFound ?? false;

      if (!alreadyFound) {
        //--- Call the payload function.
        const cancelFound = actionFunction(node);
        if (cancelFound) {
          btargetsFound = false;
        } else {
          node.dataset.alreadyFound = true;
        }
      }
    });
  } else {
    btargetsFound = false;
  }

  //--- Get the timer-control variable for this selector.
  const controlObj = waitForKeyElements.controlObj || {};
  const controlKey = selectorTxt.replace(/[^\w]/g, "_");
  let timeControl = controlObj[controlKey];

  //--- Now set or clear the timer as appropriate.
  if (btargetsFound && bWaitOnce && timeControl) {
    //--- The only condition where we need to clear the timer.
    clearInterval(timeControl);
    delete controlObj[controlKey];
  } else {
    //--- Set a timer, if needed.
    if (!timeControl) {
      timeControl = setInterval(function () {
        waitForKeyElements(
          selectorTxt,
          actionFunction,
          bWaitOnce,
          iframeSelector
        );
      }, 300);
      controlObj[controlKey] = timeControl;
    }
  }
  waitForKeyElements.controlObj = controlObj;
}