API for local files (up|down)loading

[johnd0e]

• Implement local file(s) loading/saving helpers for non-IITCm environment
• Provide environment-independent API (utils_file.js):
  • window.saveFile (subject to change, follow webview input file / download file #244)
  • IITCm: thanks to IITC-Mobile: better handling of uploads #250 for file(s) uploading it's now possible to use html input (like in full-featured browsers).
    Some additional helpers implemented (L.FileReader/L.FileListLoader)
    window.requestFile deprecated (switched to use L.FileListLoader internally)

• Make use of mentioned enhancements, to unify files import/export in draw-tools and bookmarks.
  (Previously import/export was implemented for IITCm only)

[johnd0e]

Some functions are (by their nature) strictly specific to environment.

• Load/Save file
• Copy to clipboard
• Share

There are no Web api to make that directly, but it's possible using some techniques.
But that techniques cannot be applied in IITCm's WebView (as it's not full-featured browser).
So for IITCm it's developers have implemented own functions (placed in android namespace).

This fragmentation is bad.
Most plugins developers are lazy, and do not bother to implement actions missing in some environment.
E.g. till now it was not possible to use file import/export in bookmarks/draw-tools on desktop.

So I'm going to implement some new environment-independent api functions.

[johnd0e]

// @function saveFile(data: String, filename?: String, dataType? String)
// Save data to file with given filename, using IITCm file chooser, or generic browser routine.
// `dataType` can be set to filter IITCm file chooser filetypes.

Edit
I've just realized, that more proper way'd be #244 - implement relevant parts in IITCm (and then just add simple helper functions).

But we have ho Java developer at the moment..

[johnd0e]

// @function loadFiles(options: Object): Object (L.Evented instance)
// Instantiates a `L.Evented` object, and initiates file chooser dialog,
// using methods, depending on environment:
// - desktop: simulating click on hidden `input` HTML element, created using specified `options`
// - IITCm (android): using `window.requestFile` (`options` ignored).

// @event init: Event
// Fired before file is read.
// `Event` object has additional property `file`: contains processed [`File`](https://w3c.github.io/FileAPI/#dfn-file) object.
// Note: in order to stop further processing of the file
// handler may throw error (is's safe as errors are caught)

// @event init:error: Event
// Fired on errors arised in 'init' handler(s).
// `Event` object has following additional properties:
// `file`: contains processed [`File`](https://w3c.github.io/FileAPI/#dfn-file) object.
// `error`: `Error` object.
// Note: if no handlers found for `error:init` then default one will be attached (`console.warn`)

// @event load: Event
// `Event` object has following additional properties:
// `reader`: raw instance of [`FileReader`](https://w3c.github.io/FileAPI/#APIASynch) interface
// `file`: raw instance of [`File`/`Blob`](https://w3c.github.io/FileAPI/#dfn-file)
// `originalEvent`: raw [event](https://w3c.github.io/FileAPI/#events)

// @event loaded: Event
// Fired after all files are processed (either with success or with error).

[HubertZhang]

For load file part, what’s the problem with default input button? I think using input button and implementing proper methods in IITCm are more safe.

Also I suggest we separate file apis with Leaflet. It’s weird that we put file reader under L namespace.

[johnd0e]

1. It is input internally.
   Yes, I wait you to enhance IITCm, so some things in this PR is temporary.
   It's draft, you see.

[johnd0e]

2. At first I've made some custom homebrew helper utilities.
   Then I've thrown away it, and rewrite as clean and simple classes. And yes, based on leaflet.

So let's talk about leaflet. Our project in general is closely connected with leaflet already.
It has event system powerful enough, and flexible class system.
So why not reuse it for our purposes?

But we can put some high-level function (or two) into other namespace, if you find it less confusing.

[AlfonsoML]

I second the opinion that placing any IITC functions under L. is quite strange.
There are issues opened about removing stuff from window. and providing a better API, and instead of starting here with for example a global IITC. you're placing this functions under L. so they will be very hard to notice for anyone trying to find out the API provided by IITC,
At least in window. we're used about the common properties and we can notice things that are out of place, but very few people will be notice a modified L.

[johnd0e]

Those are not IITC-specific functions. And those are exactly Leaflet classes.
As for naming you can read what is concerned as best practises here: https://leafletjs.com/examples/extending/extending-1-classes.html#naming-conventions

Actually in the same manner we already use a lot of other 3rd-party Leaflet plugins - check externals subdirectory.

[johnd0e]

Another example: see master branch, boot.js:616.
There is L.DivIcon.ColoredSvg defined, also our Leaflet class.
And there are more in pending PRs.

But you are right, we should document all these things.