diff options
author | Daniel Narvaez <dwnarvaez@gmail.com> | 2013-02-06 12:33:34 (GMT) |
---|---|---|
committer | Daniel Narvaez <dwnarvaez@gmail.com> | 2013-02-06 12:33:34 (GMT) |
commit | c110fb485b3af0066c6df7aeac8c055e9d767efa (patch) | |
tree | c5f6ecfcf022ad15e27c2d28150c7e4ec8884353 /docs/README.md | |
parent | b4216422fa628adc23f4f472975915196f694432 (diff) |
Move docs to their own dir
Diffstat (limited to 'docs/README.md')
-rw-r--r-- | docs/README.md | 92 |
1 files changed, 92 insertions, 0 deletions
diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..6192f64 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,92 @@ +# 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. |