doc: added first documentation files

documentation/00_overview.txt

+==============================================================================
+                          App renderer Quick Documentation/API
+==============================================================================
+
+Documentation Version 0.1 - May 2014
+
+This is a quick guide on how to use the app renderer on
+http://git.erp5.org/gitweb/ecommerce-ui.git?js=1
+
+<!>
+Please note:
+- Latest branch is ecommerce-ui.git
+- All branches have minor modifications and need to be merged into master
+- This API describes the key functionalities (some elements will be missing)
+<!>
+
+------------------------------------------------------------------------------
+                                  TOC
+------------------------------------------------------------------------------
+
+0. Intro
+------------------------------------------------------------------------------
+1. API Portal Type Data
+  1. Creating a fieldlist file
+  2. Overrides & custom Fields
+  3. Field types currently supported
+  4. Rendering
+  5. Subordination
+  6. Formatting
+  7. "items" Property
+  8. Translations
+  9. Validations
+  10. Copy&Paste Examples of all fields
+------------------------------------------------------------------------------
+2. API Elements
+  1. Why generate in memory?
+  2. How does the renderer work?
+  3. Elements
+  4. Element "Logic" Options
+  5. Form Elements
+  6. JQM Widgets with Copy&Paste configuration
+  7. Dynos
+  8. Items
+------------------------------------------------------------------------------
+3. API Modules
+4. API Renderer
+5. API Navigation
+7. API Actions
+8. Tutorial Writing an App

documentation/0_intro.txt

+==============================================================================
+                                 0. Intro
+==============================================================================
+<!>
+Note upfront:
+
+The renderer is not well coded. The target was to get something working
+quickly, which has been patched, patched and patched for needs be. Time
+permitting a nicer version should be made.
+
+<!>
+
+------------------------------------------------------------------------------
+                                  Idea
+------------------------------------------------------------------------------
+The idea of the renderer was to develop a system that would perform well on
+mobile devices and scale to desktop (be responsive).
+
+Major shortcomings of current frameworks are the need for heavy DOM
+manipulation, so the approach taken here is to use the UI developed by
+frameworks such as JQM but try to render fully asynchronously and in memory,
+so that a page is only modified (= triggering repaint = slow) to inject a
+fully enhanced page or large portions of it instead of inserting code and
+then have JQM modify each element individually.
+
+Still - this is only a prototype and can be much improved.
+
+To work in memory and be able to manage the whole application through jio,
+all content is generated from JSON.
+
+------------------------------------------------------------------------------
+                          Data (Portal Type Structure)
+------------------------------------------------------------------------------
+Data (items) are stored based on portal types. Every query must specifiy a
+portal type at which point the renderer looks up the portal type field
+definitions to know how a field should be rendered.
+
+To have a working application, it is thus necessary to have a
+
+  (a) [portal_type]_fieldlist.json > explain field definitions
+  (b) [portal_type]_sample.json    > to show some sample data
+
+Also since the renderer only works with i18n, all necessary translations must
+be specified in the language specific files
+
+For details see [API Portal Type Data](www) and [API Modules > i18n](www)
+
+------------------------------------------------------------------------------
+                              Element Structure
+------------------------------------------------------------------------------
+There are five types of elements that can be generated (see [API elements](www))
+
+  (a) "elements"  > plain HTML elements
+  (b) "widgets"   > jQuery Mobile widgets (panel, list...)
+  (c) "items"     > dynamic content (queried) mapped to HTML
+  (d) "modules"   > plugins (currently not managed through renderer)
+  (e) "dynos"     > dynamic containers = query and children showing dynamic data
+
+All elements are created through a recursive asynchronous loop, which will
+start from a page fragment and recursivly build the whole page including data
+from all queries and necessary async requests.
+
+Modules are currently handled on initialization only, but should eventually be
+part of the renderer loop, too.
+
+Details see [API Elements](www)
+
+------------------------------------------------------------------------------
+                              Storage Structure
+------------------------------------------------------------------------------
+Currently the app uses two storages.
+
+  (a) "items"     > includes records of all portal types
+  (b) "settings"  > includes all pages, portal_type definitions, dynos visited.
+
+At some point, "settings" should be depreciated with all elements being
+rendered as items, but no time to do this yet.
+
+By setting it up this way, caching plugins/css via a manifest and "visting"
+all necessary pages would make the application work offline.
+
+Details see [API Modules > Storage](www)
+
+------------------------------------------------------------------------------
+                                 Renderer
+------------------------------------------------------------------------------
+The renderer will run the following steps for each element to assemble a DOM
+in memory:
+
+  (a) fetch content configuration to render
+  (b) if dyno > if sample > test for sample data, load + save if none are found
+  (c) if dyno > if total query > run total query
+  (d) if dyno > run query
+  (e) render element > call mappings and renderer on children of element
+
+Details see [API Renderer](www)
+
+------------------------------------------------------------------------------
+                                Navigation
+------------------------------------------------------------------------------
+The renderer currently uses JQMs default navigation modified to allow
+deeplinking and query parameters (used only for passing jio queries)
+
+Details see [API Navigation](www)
+
+------------------------------------------------------------------------------
+                                  Actions
+------------------------------------------------------------------------------
+All interactions inside an app should be handled through actions. Actions
+trigger on submit, click and change of elements with a class of action.
+
+Details see [API Actions](www)
+
+------------------------------------------------------------------------------
+                                Create an App
+------------------------------------------------------------------------------
+The basics to create an app are explained in a quick tutorial to be found:
+
+here [API Tutorial](www)