[MapQuery] starting a widget API is wrong

[Anne Blankert]

On 30-6-2011 11:30, Volker Mische wrote:
> 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
For sake of simplicity and readability shortcuts could be nice, but in 
this case the shortcut is not a simple string parameter but must be a 
jquery object: $("selector"). For this reason such a shortcut does not 
add much for intuitive (versus RTFM) use of the API, does it?

On the other hand, I don't like the non-intuitive use of 
{map:'selector'} very much either, because options should be optional, 
by definition.

A completely different approach would be to instantiate the widget on 
the map like this:
$(mapselector).mqWidget({options}) where one of the options could be the 
DOM element to render the widget into:
$(mapselector).mqWidget({element: '#mywidget"})
and if no 'element' option were given, the widget could render itself on 
a newly created element inside the map.

But until now, the idea of MapQuery is that it modifies the look and 
behaviour of DOM elements instead of the look and behaviour of the map 
element. For this reason I would stay with
  $("domselector").mqWidget(options)
and
$("domselector").mqWidget($("mapselector"))

Anne