Refactoring and IITC API

[johnd0e]

As said in our documentation, [iitc] 'exposes a plugin API which is rich and thoroughly undocumented.' In fact, iitc core is developed in special manner: all internal objects/functions exposed via window, in hope that it could be useful for plugins.

Actually, only a subset of all exposed function ever could be useful. And so extensive api has a number of drawbacks:

1. For plugin developer: it's hard to figure out what functions are really important. Actually there is only one way: see working plugins and try do the same (btw even iitc official plugins code is full of bad patterns).
2. For IITC developers: it's hard to document every detail.
3. It's impossible to maintain, as any refactoring could brings potential incompatibilities.

Connected issues: #52, #46, #39 etc.

[johnd0e]

I suppose that we can clean up IITC API a bit. But I'm going to remove some function only after making sure that it's not used outside of IITC core. Obviously I can't verify all existent plugins, and it's possible that removed function still used by someone. But in such case it would be easy to reintroduce it back (or fix that plugin).

Here I'm going to make the list of functions that removed from api.

[johnd0e]

• [ ] #96
  • .getGenericMarkerSvg, getGenericMarkerIcon, createGenericMarker replaced with L.DivIcon.ColoredSvg class.

[angel93ayora]

As API needs changes (and documentation) it could be useful when removing a function to maintain it for some time (3 months for example) like this: function someOldApiFunc(args...) { . alert('someOldApiFunc is deprecated and will be removed in next versions, {issue url}') . someRefactoredFunc(args...); }

[johnd0e]

Alert could be helpful, I agree, even for completely removed functions. As for maintaining, I am not sure that it worth of efforts (in most cases).

[johnd0e]

So I'm going to do (in long term):

• create single API entry point: iitc (instead of window)
• expose there all useful constants, objects and functions, and document them
• leave (dub) old functions in window, but:
  • only useful, as it makes no sense to keep every small piece of that ancient code (most of which always was meant to be internal). It can broke some plugins out there, but we'll fix it on first demand.
  • no new code will be dubbed there: all new'll go to iitc.
• rewrite all standard plugins to use new API only, to serve as sample for 3rd-party plugins.

[johnd0e]

Phase 1: stop exposing internal functions, clearly not useful for any plugin. Expect refactoring of every module in code/*..

[johnd0e]

I'm going to start removing of unused/deprecated functions. Of cause, it may appear that some plugin out there still depends on them. So to make this cleanup less painful I will transfer such functions to new 'Legacy' plugin: if anyone finds that some plugin fails in new iitc-ce - he can easily re-enable all old api with that plugin.

[McBen]

Will there be an easy way to differ IITC-ce from IITC(.me)?

(without detailed version checks)

[johnd0e]

@McBen As always, the best way is detect features, not versions.

So you can try to check api.