[MapQuery] MapQuery API Proposal

[Drew Wells]

Before I get into the details of .data('mapquery'), do you agree we should
make it possible to make repeated calls to $(selector).mapQuery()?  For
example,

$(selector).mapQuery(layers: { url, layer})
$(selector).mapquery(layers: { url2, layer2}) //Both layers exist in map

I don't believe this would work currently, I would like to look into making
it work though.

Onto .data('mapquery)...

I could see adding layers via the LayerControl widget or on instantiation,
but you don't think a single user will want different access to the methods?
We would have to write a widget for every possible use case...

I wrote a second demo that the user can add a WMS layer via a form. This
requires opening up a .data('mapquery') object in order to add the layer.

On ESRI's demo site, layers are added via URL:
http://www.arcgis.com/home/webmap/viewer.html?url=http://server.arcgisonline.com/ArcGIS/rest/services/Demographics/USA_Unemployment_Rate/MapServer&source=sd
These types of behavior are not available with MapQuery, at least not in a
blazingly obvious way.  The most basic examples may work well with the
current API, but if the user requires any type of dynamic adding of
layers/controls/etc they need to dig into .data('mapquery').

I think this will be a common use case that we should cater too.  I believe
$(selector).mapQuery() should return jQuery chain as it does now, but
$.mapQuery could return the map object with all our public methods
available.

-Drew

On Fri, Jan 14, 2011 at 1:45 PM, Volker Mische <volker.mische at gmail.com>wrote:

> Hi Drew,
>
> we discussed the API quite a lot. To understand the current one, you have
> to understand the idea behind that all. MapQuery is basically two parts,
> MapQuery Core and MapQuery UI. MapQuery UI are the widgets, like the layer
> control or the popup control I'm working on. Those widgets use the MapQuery
> Core. The goal is, that people start to use the widgets and are happy with
> them as they are, they don't need to care about the internals (and also not
> about MapQuery Core).
>
> Therefore .geoMap() (which should relaly be named .mapQuery()) behaves like
> a normal jQuery plugin, and is therefore chainable. If you need some
> internal functionality (which you shouldn't care about as an end user), you
> can easily have access via data('geoMap') (which also should be
> data('mapQuery')).
>
> You might argue that you need .data() for adding new layers. Well, I expect
> that most people pass in all layers they need at the beginning in the
> mapQuery() constructor. Later they add new layers probably through some
> interface, which would again be coded as a widget.
>
> I hope this mail makes it a bit clearer, why this API is like that. Though
> I'm happy to keep discussing and changing it for the best.
>
> Cheers,
>  Volker
>
>
> On 14.01.2011 18:51, Drew Wells wrote:
>
>> MapQuery currently suffers from a little complexity, seen in the
>> following api.
>> var map = $('#map').geoMap();
>> var mapData = map.data('geoMap');
>>
>> I merged some code that eliminated this by having $("#map").geoMap()
>> return the map object instead of the jQuery collection.  This may
>> be counterintuitive to others that are normally used to chaining method
>> calls in jQuery.
>>
>> I propose the following solution
>>
>> $.geoMap([jQuery selector], [options]); //return reference to Object
>> containing all all relevant methods
>>
>> The following type of usage would be available:
>> var map = $.geoMap("#map", {
>>   layers: [
>>               { url: 'http://wms',
>>                 type: 'wms',
>>                 layers: [states,countries] } ],
>>   transparent: true //apply to all layers,
>>   ...
>>   Other options
>>   ...
>> });
>>
>> The then have the option of doing two things, either using
>> $.geoMap("#map") to add new controls and/or layers OR $.geoMap returns
>> an object which has these methods available.
>>
>> $.geoMap("#map", {transparent: false }); is the same as map.transparent(
>> false )
>>
>> Ideas for this usage are based on past experiences with $.flot
>> http://people.iola.dk/olau/flot/API.txt
>>
>> -Drew
>>
>>
>>
>> _______________________________________________
>> MapQuery mailing list
>> MapQuery at lists.osgeo.org
>> http://lists.osgeo.org/mailman/listinfo/mapquery
>>
>
>


-- 
Sent from my Chrome V8 Engine
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/mapquery/attachments/20110114/2239f1d5/attachment.html