Planned Webxdc APIs for processing files

webxdc
1

This post outlines two Webxdc APIs to export and import files or data. “files” in this sense may be any kind of binary blobs (this includes plain text files) that are identified by a name; this may or may not have a direct relation to the operating system’s file system.

This will enable webxdc-apps to eg.

  • handle file formats typical to an app category - eg. an calendar could allow importing exiting .ics files - and could also exports its own state that way
  • define their own file format to make migration easier and to allow a simple form of updates
  • act as an data processor (eg. import a file, let it modify by the webxdc-app, export the file

Existing APIs: Currently, webxdc-apps can export/import data only by sending/receiving updates to other peers.

Scope of the new APIs: Exporting/Importing any blob to/from a local File object. Using files as additional storage or having permanent access to them is out of scope of the planned APIs.

Dealing with files do not always offer a great UX across platforms and also sometimes not even on a single device. Therefore, the API and the integration is designed closer to the chat/message metaphers that are already in use anyway.

webxdc.export()


promise = window.webxdc.export({file: File, text: "This file contains …"})
  • file is a js File object containing a Blob and a name
  • text is any message that should be shown beside the exported file
  • returns a promise that is resolved to true once export is completed or false on error/abort

It is up to the UI where to store the file, it should not be sent out to other users, however (this may come in the future).

Concrete implementation plans for Delta Chat is to write the file to the “Saved Messages” chat - from where it can be handled as any other file and also easily being accessed for import

webxdc.import()


array = window.webxdc.importFiles(extensions)
  • extensions array of extensions that may be shown to the user (details have to be figured out, i suggest to be close to what js is using here for their file selectord)
  • returns a promise with an with File objects (same as the js file selector)

Concrete implentation plans for Delta Chat is to show sth. as the “All Media” view and let the user select a single file. the view is filtered by the extensions, however, with the option to access all files. later, this may be enhanced to multiple files.

Other implementations may just show the system’s file selector (which, depending on the system Delta Chat is running, may become and additional option to)

the goal of the API is also to make non-Delta-Chat-implemtations easy, so no part is bound to things only Delta Chat has, cc @singpolyma

ftr: corresponding github issue: Add import/export API to WebXDC · Issue #4350 · deltachat/deltachat-core-rust · GitHub

3 Likes
2

Rather than extensions I suggest using mime types and patterns. This would also allow for eg “image/*”

2 Likes
3

I think it makes sense to provide similar API to what the HTML <input> tag supports:

For instance, there are a number of ways Microsoft Word files can be identified, so a site that accepts Word files might use an <input> like this:

<input
  type="file"
  id="docpicker"
  accept=".doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document" />

so you can specify a comma-separated list of extensions and/or mime types (including image/*, video/*, audio/*, etc)

mime-type-only is not enough for some apps-generated data that have custom extensions and are not widely known

4

my questions about using mime types instead of file extensions:

A: How to detect the mime type given a filename and the bytes of a file?
B: How to accept custom files that don’t have an official mime type (like data files for a specific webxdc that has no official mime type?)

5

i’d think that starting with extensions makes sense, can be extended with ability to specify mime-types later. We are currently discussing the first neccessary steps to things working in a sensible manner, especially looking at needs for our little GitHub - webxdc/calendar: a nice webxdc calendar example app (ingesting an invite, exporting an invite or a full calendar)

6

Sure, allowing both could be fine. I’m especially interested in android where all APIs are mime type based and one often doesn’t even have access to extensions or filenames.

1 Like
7

after some discussions, we’ll probably upgrade export() to sendToChat():

  • if sendToChat() is called, control is given back to the app
  • the user will be prompted for a destination chat - this may be “saved messages”, the current chat - or any other chat
  • once a destination chat is selected, a draft with the file and message will be set up - the user has to hit the send-button explicitly for confirmation

this allows hugely improved UX, eg. for the idea of editing and sending an image, an calendar invite etc. no need to forward messages, no need to deal with “wrong text” attached to files.

we assume, that some components as forward/share UI and the draft area already exist anyway and can be reused. however, for rapid prototyping, the concrete implementations can still decide to always “just” send to saved messages without asking the user.

the function signature would be unchanged:

promise = webxdc.sendToChat({file: File, text: "This file contains …"})

details (as the return value), need to be figured out, in the future, one can maybe also define some preselected chat (eg. backups will go to saved-messages)

1 Like
8

I started realising the api signature we discussed here in export-chat: initial draft based on forum post by Simon-Laux · Pull Request #44 · webxdc/webxdc_docs · GitHub
let’s discuss the api over there further

9

hi @all, so the new specs are available at: Webxdc Specification - Webxdc

Direct links:

hi @singpolyma, for the Cheogram app, the DC Android implementation might be useful:

to add support for the HTML file input on android webview: implement onShowFileChooser based on AdvancedWebView by r10s · Pull Request #2575 · deltachat/deltachat-android · GitHub