[MapQuery] starting a widget API is wrong

[Steven M. Ottens]

  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.

Regards,
Steven