[MapQuery] starting a widget API is wrong

[Volker Mische]

On 06/30/2011 12:05 PM, Anne Blankert wrote:
> 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?

That's true.

> 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.

The widget can't know if there's a map or not, hence you always need to
pass it in somehow.


> 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

Cheers,
  Volker