Proposed API changes for 1.3: feedback requested!

[jamietre]

There are a number of changes I have been thinking about to simplify the API. Some of these are already in progress.

• 'areas' option: instead of an array, use an object where the properties identify the area key. (Building an array is much harder, more error prone, and offers no advantages internally. It was just a bad decision). To allow an option to target more than once key, we will still have a "keys" property of the object you assign to each areas.key= {.. } value.
• standardize the properties of the objects returned from events, and standardize handling of return values (e.g. false to cancel whatever event)
• (feature, but affects API for rendering options) allow an arbitrary number of selected states (e.g that cycle between off, 1,2,3) with associated options. render_select and render_highlight become

 opts = {
    fillColor: '123344',
    render: [ { highlight-opts, select-opts, alt-select-1-opts, ...} ]
 }

Yes... I am adding a new array :) but here, I think it makes more sense than the awkwardly named render_xxx options.

• allow changing selected state by changing value in object returned from event
• change 'set', true | false to set, unset, and toggle so that you don't need to always pass a parameter to identify the state, reducing the # of parms for common operations.

You can already pass rendering options as a 4th parm, this would become the 3rd parm e.g.

map.mapster('set',keys, {fillColor: '123456'});

Expose a real API

• return a "mapster" object instead of jQuery object: many operations require a series of operations. This gets redundant when staying within the context of a jquery object. I plan to create (well, really, expose - it already exists internally) a "mapster" object that exposes the API which can optionally be returned. The standard "mapster()" would just return a jquery object so it remains backward compatible.

  var map = $('img').mapster('api');

Could also be returned like this

var map = $.mapster('img');

// once accessed, map.mapster('method',opts) becomes 'map.method(opts)`

map.select('keys').set();

map.options('onClick',function(e) {
   ...
});

// all operations can be targeted to a set of selected map keys, Calling mapster('api') against a jQuery selector that
// contains area tags will create a key selection set (like the "keys" option now) that will source the next method instead
// of passing key lists around

// select some areas using jQuery, then apply "render" options to those areas, then select them

$('.some-selector')
  .mapster('api')
  .options('render',{ 
      fillColor: '#123456'
   }).set();

// use classes to identify supergroups. classes set on a single area will automatically grab all areas with same map key

$('.supergroup')
    .mapster('api')
    .set({
        stroke: true;
    });

map.select('keys').toggle(options);

Please leave any thoughts or comments here

[ruhley]

Hi jamietre,

The change to using an object instead of an array would be great! Exposing the API is also a great move. Keep up the good work.

For the visuals of the area you currently have three states: Normal (no styles unless you use snapshot), Highlighted, Selected with code something like this -

fill: true,
fillColor: '000000',
fillColorMask: 'FFFFFF',
fillOpacity: 0.5,
stroke: false,
strokeColor: 'FF0000,
strokeOpacity: 1,
strokeWidth: 1,
render_highlight: {
fillOpacity: 0.2
},
render_select: {
fillOpacity: 0.8
}

you could use another set of objects. You can have normal, highlight and select inside each of the fill/stroke objects each with their own values. Using the global object you can set values for all 3 (or just inside like in stroke).

fill: {
global: {
show: false,
color: '000',
mask: 'FFF',
opacity: 0.5
},
highlight: {
show: true,
opacity: 0.2
},
select: {
show: true,
opacity: 0.8
}
},
stroke: {
show: false,
color: 'F00',
opacity: 0.5,
width: 2,
normal: {
show: true
}
}