jQuery attr method can set click handler and inner text

Question

Reading jQueryUI dialog code, I've found out, jQuery .attr() method has some undocumented behavior:

<button id="btn1">1</button>
<button id="btn2">2</button>

$(function() {
    var props = {
        text: 'Click it!',
        click: function () {
            console.log('Clicked btn:', this);
        }
    };

    $('#btn1').attr(props, true);    // Changes #btn1 inner text to 'Click it!' 
                                     // and adds click handler
    $('#btn2').attr(props);          // Leaves #btn2 inner text as it is and fires 
                                     // click function on document ready
});

• Can you explain me how it works? Why should I set true as the second argument after map of attribute-value pairs?
• Can I use this feature in my projects safely?

Answer 1

I'm guessing slightly here because I'm unfamiliar with the jQuery source. jQuery.attr calls jQuery.access, and the comment above the jQuery.access function reads:

// Multifunctional method to get and set values of a collection
// The value/s can optionally be executed if it's a function

Upon further investigation, the text() function also calls jQuery.access:

    attr: function( name, value ) {
        return jQuery.access( this, jQuery.attr, name, value, arguments.length > 1 );
    },
    .........
    text: function( value ) {
        return jQuery.access( this, function( value ) {
        ......
    },

You're using attr to set text and event handlers, which is not what attr is for. However they all seem to be using the same function to get the job done, so the use of undocumented parameters is just incidentally giving you the expected behavior.

I would consider it unreliable to rely on undocumented behavior to accomplish what you're trying to do here, as any future upgrade of jQuery could break your code.

Answer 2

Looking at the jQuery 1.8.2 code, the true parameter eventually arrives in the variable pass at a line that says:

exec = pass === undefined && jQuery.isFunction( value );

which if set, tells jQuery to check the check the value belonging to the key, and if it's a function, call it immediately. Hence click: function(...) will call that function, not register that function.

This appears to be how the .method(function() { ... } versions of various jQuery functions work, i.e. those where instead of passing a specific value for a property, you pass a function which is itself passed the original value, and whose return value is assigned to the relevant property.

Can I use this feature in my projects safely?

I wouldn't, not until it's documented.