# HTML activities - Draft 1

## Premise

XXX Improve the Sugar OS developer experience

XXX Cross platform sugar activities -> future

XXX What is Sugar.

## Modules

The framework is composed of various libraries, initially

* activity
* graphics
* datastore
* collaboration

### Interface description

Each module provides one or more interface descriptions which are language
independent. A subset of object-oriented languages should be chosen, so that
it's possible to implement these from all the languages we are interested
to support. The description uses the Java syntax because unlike, for example,
python and JavaScript it's explicit about types.

For example, the datastore interface could look like

    class Datastore {
        DatastoreObject load();
        void save(DatastoreObject object);
    }

XXX The interface is totally made up!

XXX What about IDL? Even if we don't use them initially the tools might be
useful at some point.

### Implementation

The implementation should be written as much as possible using web languages.
But of course we will have the necessity to interact with native system
components. The multi language nature of the interfaces will be useful here
because it will allow to provide system specific implementation of certain
interfaces and generically bridge to them from JavaScript. All the modules
should provide a web fallback, which will allow to run the activity everywhere
even if with degraded functionality.

### Code style

View source is a core part of the sugar experience, so any kind of code
obfuscation should be avoided. This includes languages that compiles to
JavaScript, like CoffeeScript.

### Namespacing and package management

We are using [volo](http://volojs.org) for namespacing and package management,
both in the libraries and in the documentation.

## Activities

Activities are [open web apps](https://developer.mozilla.org/en-US/docs/Apps),
their only specificity is that can make use of our libraries framework. On some
platforms (Sugar OS for example) it might be necessary to generate boilerplate
code, configuration or to package the app in a certain way to have it integrate
with the system flawlessly. We will provide scripts to fully automate those
tasks.

## Implementation notes

### Sugar OS

* We should probably use firefox, as provided by upstream, to run activities.
Chrome would probably be an equally good alternative. At some point we could
just support both.
* We should be able to customize it to look like a native activity without
patching the code. We need to avoid showing any chrome UI (toolbar, menubar,
etc) and to provide the X properties Sugar expects from an activity.
* We can generate activity.info from the webapp manifest  when building a .xo.
* The svg icon might be provided in a native/sugar-os directory of the web
activity or something.
* Communication between JavaScript and native code will be handled by a firefox
extension and it will most likely go through DBus. pythonext might be an
alternative but I'm not convinced we should get into pyxpcom again. We can use
dom events to communicate between content and extension.
* Icons should be shipped as part of the graphics library, we can write a
script to sync them with the sugar-artwork repository.
* The datastore interface should probably make use of HTML files support. I
hope using local paths will work in a web activity.
* To get full permission I suspect a web app needs to be installed. We will
have to figure out if/how we can avoid that.