[MapQuery] starting a widget API is wrong

[Volker Mische]

On 06/30/2011 11:13 AM, Steven M. Ottens wrote:
>  On 6/30/2011 12:37 AM, Volker Mische wrote:
>> On 06/29/2011 10:27 PM, Steven Ottens wrote:
>>> I'm cleaning up the widgets in my fork and am trying to make them all
>>> in the same style. I noticed that Volkers widgets start like this:
>>>    $('#featureinfo').mqFeatureInfo({
>>>          map: $('#map'),
>>>          contents: function(feature) {
>>>              return '<p>' + feature.data.id +'</p>';
>>>          }
>>>      });
>>> Where mine start like this:
>>>   $('#overview').mqOverviewMap($('#map'));
>>>
>>> I don't have a big preference*) on which way to follow, but we have
>>> to be consistent. By the looks of it neither of our methods are
>>> following the API specs. Since both methods are invalid to the API we
>>> can do three things: fix our code to follow API or to fix the API to
>>> follow Volker or me (and fix code accordingly).
>>>
>>> *) I've got the slightest of preferences for the API way: the map
>>> should always be passed and options are optional.
>>>
>>> What are your opinions?
>> Hi Steven,
>>
>> good discovery. I actually like the API docs way most.
> Unfortunately we don't have much of a choice; using the widget factory
> we can only pass in an options object. As such the API docs are wrong. 
> Currently most of the widgets use the forgiving approach of:
> if (this.options.jquery === $().jquery) {
>     map = this.options.data('mapQuery');
>     this.options = {};        }
> else { map = this.options.map.data('mapQuery'); }
> 
> Which means you can call them either with
> 
>  $(selector).mqWidget($("mapselector"));
> or
>  $(selector).mqWidget({options});
> 
> where options has to contain at least {map: $("mapselector")}
> 
> So we've to choose to either allow for both methods or just the last one.

I guess it would be more consistent to allow only the passing in of
objects ({map: ...}). Though for simple widgets where you have no
options or very good default ones, a shortcut would be nice.

I'm undecided, I hope to hear opinions from other people :)

Cheers,
  Volker