Opened 6 weeks ago

#15292 new feature

consistency on return types for "instance invocation" compared with "plugin invocation"

Reported by: Hendra Gunawan Owned by:
Priority: minor Milestone: none
Component: ui.widget Version: git (not yet released)
Keywords: Cc:
Blocked by: Blocking:

Description

currently (JUI-1.12), "instance invocation" still does not have same luxury on return types compared with "plugin invocation" (http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/#return-types).

"Most methods invoked through the widget's plugin will return a jQuery object so the method call can be chained with additional jQuery methods. This is even true of methods that return undefined when invoked on the instance."

Instance invocation produce verbose statement. The more additional statements added, the more ugly they look. For me, this is the main barrier why i decided not to use instance invocation. Beside this weakness, i recognize the potential advantage on using instance invocation: a better IDE recognition and error inspection.

This inconsistency (instance and plugin return type) is caused by how we declare return statement inside the method. If we declare it as jQuery object, we get same condition as before: we still can't do method chaining with "instance invocation". If we declare it as instance object, we can do method chaining on "instance invocation" but it breaks method chaining on "plugin invocation".

Another determining factor is if ( methodValue !== instance && methodValue !== undefined ) statement inside $.widget.bridge body. It is the source of magical chaining on "plugin invocation". We expect the same magic for "instance invocation".

What we expect is if the method returns instance object (return statement declaration), the bridge automatically converts it as jQuery object so the chaining can be applied on both kind.

The implication of this are:

  1. We can't obtain instance object anymore using "plugin invocation" other than "instance" keyword.
$.widget("ns.mywidget", {
    myMethod: function(){
        return this;
    },
    otherMethod: function(){
        // nothing to return
    }
});

// now, these statement is magically returning jQuery:
$elm.mywidget("myMethod");
$elm.mywidget("otherMethod"); // nothing new on this one

// this method is still returning instance:
$elm.mywidget("instance");
  1. The consummer of "plugin invocation" must explicitly call "instance" method if it really want to obtain instance object.
// before
$elm.mywidget("method1") // method1 returns jQuery
    .mywidget("method2") // method2 returns instance
    .method3()           // see the style switching

// after
$elm.mywidget("method1")
    .mywidget("method2")  // now, method2 returns jQuery
    .mywidget("instance") // explicitly
    .method3()
  1. The only problem (if any) is on the custom user widget, whether it is modified/derived version of standard JUI or brand new. If user declare the public method returns instance than this will breaks the widget.

As far as i know, most of (if not all) public instance methods on the standard JUI widget are not returns instance. This mean the consumer of that widget is always get anything other than instance object. I thing this is save to add the missing return statement (which is returning instance).

Change History (0)

Note: See TracTickets for help on using tickets.