Version 3.5.1

DOM Lifecycle Events

Jump to Table of Contents

The event-base module includes three special events that can be used to execute code as soon as the DOM, or certain elements in the DOM tree, are ready to be scripted.

Because all of these events are designed to target elements that aren't present or parsed yet, you must use Y.on(...) to subscribe to them. Y.one('#notHereYet') will return null, and you can't do much with null.

Be sure to read the final note on this page about performance.

domready

<!doctype html>
<html>
<head>
    <meta charset="utf-8">
    <title>domready</title>
    <script src="...yui-min.js"></script>
    <script>
    YUI().use('event-base', function (Y) {
        var notHereYet = Y.one('#readygo'); // null

        Y.on('domready', function () {
            Y.one('#readygo').on('click', function () {
                Y.log('This works fine, before the images are loaded');
            });
        });
    });
    </script>
</head>
<body>
    ... lots of markup including images and stuff
    <button id="readygo">Go!</button>
</body>
</html>

Modern browsers support an event that signals when the markup has been completely parsed and the DOM tree is built. This event happens before the window's load event, which fires when all images and other resources have been fetched. For setting up event subscriptions and core page interactivity, it's usually enough that all DOM elements are available, regardless of their loading state.

The domready event abstracts over the patchwork necessary for browsers without a native "domready" event.

Note the subscription signature does not include a target, only the event name and callback.

contentready

<!doctype html>
<html>
<head>
    <meta charset="utf-8">
    <title>contentready</title>
    <script src="...yui-min.js"></script>
    <script>
    YUI().use('event-base', function (Y) {
        var notHereYet = Y.one('#list'); // null

        function addItem() {
            // children of #todo are in the DOM tree
            this.one('ul').append('<li>This will be four</li>');
        }

        Y.on('contentready', addItem, '#todo');
    });
    </script>
</head>
<body>
    ... lots of markup including images and stuff
    <div id="todos">
        <ul>
            <li>one</li>
            <li>two</li>
            <li>three</li>
        </ul>
    </div>
    ... more markup
</body>
</html>

You may want to script some nodes that are in the middle of the page markup inside a specific containing element. You just need to know that the container and its children have been parsed from markup and added to the DOM tree. But you don't want to wait for the entire DOM tree to finish. That's what the contentready event is for.

YUI will check the DOM periodically, looking for an element matching the selector passed as the the third argument. When it finds one and can verify that that element's children are also in the DOM tree, it will execute the callback.

Callbacks will be executed with this assigned to the Node matching the selector.

available

<!doctype html>
<html>
<head>
    <meta charset="utf-8">
    <title>available</title>
    <script src="...yui-min.js"></script>
    <script>
    YUI().use('event-hover', function (Y) {
        var notHereYet = Y.one('#highlight-me'); // null

        function over() {
            this.addClass("over");
        }
        function out() {
            this.removeClass("over");
        }

        function addSubscribers() {
            this.on('hover', over, out);
        }

        Y.on('available', addSubscribers, '#highlight-me');
    });
    </script>
</head>
<body>
    ... lots of markup including images and stuff
    <div id="highlight-me">
        ... stuff that doesn't need to be ready
    </div>
    ... more markup
</body>
</html>

The available event is almost identical to contentready except it does not wait for children of the matching element to be ready. If your code only needs to reference the targeted Node, not any of its children, use available instead of contentready.

Just put your <script> tags at the bottom

You might not need to use any of these events, and maybe you shouldn't.

It is always safe to script nodes defined in the markup above the JavaScript that references it. In practice, if you have the option, it is preferable to move <script> tags below the markup that it needs in place, and often it is best to simply move scripts to the bottom of the page.

<div id="stuff-i-need">
    ...
</div>
<script>
// Scripts below markup can access the DOM elements above
YUI().use('node', function (Y) {
    Y.one('#stuff-i-need', function () {
        Y.log('This will always work');
    });
});
</script>