This page documents the work plan for upgrading the Paco Javascript api to be more useful and more well thought out.

After over a year of experience building and helping build custom experiments using Javascript in Paco, and having had real world time with the features to execute script actions we realize that there are problems in the api.

1. It is not organized well
2. It has redundancies and inconsistencies across embedded webview and headless interpretered execution environments that should be refactored.
3. It is currently synchronous-only. This works OK for Android but does not work well for iOS or the web. We need to add async(callback) apis to work well across platforms.
4. It is not documented at the api level or at the architecture level.
5. It should be debuggable and previewable in the web ui for testing and debugging without going to the phone. This should include using standard web debug tools like the Chrome/Firefox/Safari debug tools. Also, it should allow easy creation of test data objects.

##High Level work to be done

(Issue Tracker for bugs/features: https://github.com/google/paco/milestones/Javascript%20Api%20v2)

1. Factor the javascript into better modules that are provided in separate files. This reduces redundancy, inconsistency and fits our heterogenous execution environments.
2. Document the new organization and new interfaces
3. Make the interfaces asynchronous
4. Inject this new javascript library into the execution environments: Android, iOS, Web. Since it will have a new namespace, paco2, it will allow backward compatibility for old experiments using these custom apis.
5. Document the interfaces as we go along.

##File asset organization (bare minimum refactor)

1. Create a paco_core.js which contains all the headless apis
2. Create a paco_render.js which contains all the UX related apis
3. Create a paco_util.js which contains handy, but, not core apis, e.g., time manipulation, string manipulation, json preparation apis as necessary.

##Module organization within paco_core.js

• paco2.experimentService
• paco2.notificationService
• paco2.db
• paco2.events
• paco2.executor
• paco.photoservice

##Architecture documentation

Because Paco's js services are on multiple platforms, they are layered to isolate experiment-level functions from platform specific implementations of those functions.

Additionally, there are bridge objects into the various execution environments (Android, iOS) that need documentation as they do not have any higher level js api in the current files. We should add apis at the experiment-layer for these as well.