A utility function, for Greasemonkey scripts, that detects and handles AJAXed content.

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.
                    */
) {
    var targetNodes, btargetsFound;

    if (typeof iframeSelector == "undefined")
        targetNodes     = $(selectorTxt);
    else
        targetNodes     = $(iframeSelector).contents ()
                                           .find (selectorTxt);

    if (targetNodes  &&  targetNodes.length > 0) {
        btargetsFound   = true;
        /*--- Found target node(s).  Go through each and act if they
            are new.
        */
        targetNodes.each ( function () {
            var jThis        = $(this);
            var alreadyFound = jThis.data ('alreadyFound')  ||  false;

            if (!alreadyFound) {
                //--- Call the payload function.
                var cancelFound     = actionFunction (jThis);
                if (cancelFound)
                    btargetsFound   = false;
                else
                    jThis.data ('alreadyFound', true);
            }
        } );
    }
    else {
        btargetsFound   = false;
    }

    //--- Get the timer-control variable for this selector.
    var controlObj      = waitForKeyElements.controlObj  ||  {};
    var controlKey      = selectorTxt.replace (/[^\w]/g, "_");
    var 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;
}

@BrockA I am using vite-plugin-monkey this package to do the hmr deployment in Chrome, I never tested in Firefox.

@peanutive00 If you're just trying to benefit from static typing while using this script as a dependency in a TypeScript project, you only need to have the JavaScript annotated with JSDoc type hints. See JSDoc Reference for TypeScript. For example, see my fork of this script. Or, you could produce a .d.ts file for the original version and avoid modifying the .js file altogether.

@peanutive00 Thanks, I'll check that out but I don't do much TM coding these days so it may be a long while. Meanwhile CoeJoder seems to have a workaround.

@BrockA

Could you convert the following code into waitForKeyElements, please? When I use it as is, it only works on some of the span.rightActionButton elements on each page, but not all of them. So I want to see if it will work if I use wFKE, but I don't know the proper format. Hope you don't mind. Thanks.

$(document).ready(function(){
$('span.rightActionButton').each(function(){
$(this).css("background-color", "red");
var oldUrl = $(this).attr("onclick");
var newUrl = oldUrl.replace("window.location='", "window.open('https://www.somewebsite.com");
$(this).attr("onclick", newUrl + ", target='_blank')");
});});

@gaveitatry2 ,

That entire code block would be replaced with:

waitForKeyElements ("span.rightActionButton", rewriteSpanLinks);

function rewriteSpanLinks (jNode) {
    jNode.css ("background-color", "red");
    var oldUrl = jNode.attr ("onclick");
    var newUrl = oldUrl.replace ("window.location='", "window.open('https://www.somewebsite.com");
    jNode.attr ("onclick", newUrl + ", target='_blank')");
}

Thank you.

This code is so bad. It should be using a MutationObserver or DOM/script load events instead of running a jQuery selector on the entire document every 300 ms.

@cow1337killer3 by all means, rewrite it :)

bug report:
cant't wait the same element, the callback can't be called

// ==UserScript==
// @name         New Userscript
// @namespace    http://tampermonkey.net/
// @version      2025-02-21
// @description  try to take over the world!
// @author       You
// @match        http://127.0.0.1:5500/playground.html
// @icon         https://www.google.com/s2/favicons?sz=64&domain=0.1
// @require      https://z.chaoxing.com/js/jquery-3.5.0.min.js
// @grant        none
// ==/UserScript==

(function() {
  'use strict';

  waitForKeyElements(".child", (item) => {
    console.log(item[0]); // Will be executed
  });

  waitForKeyElements(".child", (item) => {
      console.log(item[0]); // Never be executed
  });


})();

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>playground</title>
</head>
<body>
  <button onclick="addComment()">addComment</button>

  <ul class="comments">
    <li class="comment">第1条评论</li>
  </ul>

  <div class="app"></div>

  <script>
    setTimeout(() => {
      const appElement = document.querySelector('.app');

      const pElement = document.createElement('p');

      pElement.className = 'child';

      pElement.textContent = 'child';

      appElement.appendChild(pElement);
    }, 1000);

    function addComment() {
      const commentsEl = document.querySelector('.comments');

      const liElement = document.createElement('li');

      liElement.className = 'comment';

      liElement.textContent = `第${commentsEl.children.length + 1}条评论`;
      
      commentsEl.appendChild(liElement);
    }
  </script>
</body>
</html>

@HHsomeHand , This is not really a bug. It's an artifact of the purpose and expected use of WFKE. This version of the function marks nodes with a flag that can be cleared with $(".child").removeData('alreadyFound'); IF-AND-ONLY-IF you understand and use the asynchronous timing correctly.

Anyway, there are workarounds depending on the exact details of what you're attempting, but the easiest is to just put all code for ".child" into only one waitForKeyElements call.

bug report: cant't wait the same element, the callback can't be called

No one's bothered to link the mystical rumored fork that uses MutationObserver so here's the link: https://gist.github.com/double-beep/c4d4ec3866e5e54ae514c0aab60af242

No one's bothered to link the mystical rumored fork that uses MutationObserver so here's the link: https://gist.github.com/double-beep/c4d4ec3866e5e54ae514c0aab60af242

Thanks, it's interesting to compare the two approaches. Maybe this is out of the scope of this page, but...what would be the advantage of using this script over Mutation Observer (and vice versa)?

For a modern dynamic webpage, you normally wouldn't want to naively attach a MutationObserver to the root of the document body (callback thrashing!). It's often a good idea to first poll for a particular parent element e.g. comment section container, and then attach a MO to that element. I like using ViolentMonkey's utility instead of MutationObserver directly. Here is an example userscript: Turn rumble comment timestamps into clickable links (here I'm using GM_wrench.wait() for more general purpose polling, not WFKE)

No one's bothered to link the mystical rumored fork that uses MutationObserver so here's the link: https://gist.github.com/double-beep/c4d4ec3866e5e54ae514c0aab60af242

Thanks, it's interesting to compare the two approaches. Maybe this is out of the scope of this page, but...what would be the advantage of using this script over Mutation Observer (and vice versa)?

Properly implemented, MutationObserver is now faster, more efficient, and more responsive. I do not think that linked script is the best example and it is not as flexible or robust as this WFKE. Nor is it a drop-in replacement. But if it, or any of the thousands of now available alternatives, works for you, then awesome. ;)

To be fair to me, this WFKE was written before MutationObserver was widely available and while it was particularly buggy and resource intensive. It performs well enough that I almost never need anything else and haven't felt a pressing need to refactor it yet.