Work in progress commit of API.md.

API.md

 API: Client / Server
 ====================
 
+
 Form initial call
 -----------------
 
@@ -13,8 +14,8 @@ data-hidden:    'yes'|'no'  - yes: The element is not visible yet, maybe later.
 data-disabled:  'yes'|'no'  - yes: The element is visible, but the user can't interact with it. 
 data-required:  'yes'|'no'  - yes: The element is required. The form can't be submitted if any required element is empty.
 
-General
--------
+## General
+
 
 Asynchronous request (read AJAX) initiated by the client receive a JSON Response from the server containing at least:
 
@@ -26,6 +27,66 @@ Asynchronous request (read AJAX) initiated by the client receive a JSON Response
 `status` indicates whether or not the request has been fullfiled by the server (`"success"`) or encountered an error (`"error"`).
 On `"error"` the client must display `"<message>"` to the user. On `"success"`, the client may display `"<message>"` to the user.
  
+### Form Group Configuration
+
+As part of the server response, the JSON stream may contain a key
+`form-update`. It contains an array of objects having following
+structure
+
+    {
+     ...
+     "form-update" : [
+       {
+          "form-element": "<element_name>",
+          "hidden": true | false,
+          "disabled": true | false,
+          "required": true | false,
+          "value": <value>
+       },
+       ...
+     ],
+     ...
+    }
+
+
+`"form-element"`
+:   the name of the HTML Form Element as it appears in the `name`
+	attribute.
+
+`"hidden"`
+:   whether the Form Group is visible (value: `false`) or
+    invisible (value: `true`).
+	
+`"disabled"`
+:   whether or not the Form Element is disabled HTML-wise.
+
+`"required"`
+:   whether or not the Form Element receives the HTML5 `required`
+    attribute.
+
+`"value"`
+:   For textual HTML Form Input elements, it is supposed to be a
+    scalar value, which is set on the element.
+	
+	When `"form-element"` references a `<select>` element, a scalar value
+    selects the corresponding value from the option list. In order to replace
+    the option list, use an array of objects, having this format
+	   
+	    [
+          {
+            "value": 100,
+            "text": "a",
+            "selected": true
+          },
+          {
+            "value": 200,
+            "text": "b",
+            "selected": false
+          }
+        ]
+		
+	`"select"` is optional, as is `"text"`. If `"text"` is omitted, it
+    will be derived from value.
 
 
 Form load (update)
@@ -48,7 +109,10 @@ POST
 none
 
 ##### POST
-HTML Form without `<input>` elements of type `file`. The HTML Form is required to have a HTML Form Element named `s`, which must contain the SIP.
+
+HTML Form without `<input>` elements of type `file`. The HTML Form is
+required to have a HTML Form Element named `s`, which must contain the
+SIP.
 
 ### Response
 
@@ -71,14 +135,25 @@ JSON Stream
      ]
     }
     
-Name    | Description
-------- | -----------
-status  | see General
-message | see General
-redirect | not used
-field-name | HTML Form Element Name which raised error on server side. Requires status to be `"error"`
-field-message | reason of error. Requires status to be `"error"`.
-form-update  | Array of Objects. Each object describes the state and value of a HTML Form Element identfied by its `name` attribute.
+status
+:   see [General]
+
+message 
+:   see [General]
+
+redirect 
+:   not used
+
+field-name 
+:   HTML Form Element Name which raised error on server side. Requires
+	status to be `"error"`
+
+field-message
+:   reason of error. Requires status to be `"error"`.
+
+form-update
+:   Array of Objects. Each object describes the state and value of a
+    HTML Form Element identfied by its `name` attribute.
 
 
 Form save
@@ -199,3 +274,14 @@ Delete failed: Show message.
  message = <message>
  redirect = 'no'
 
+## Glossary
+
+SIP
+:   tbd
+
+HTML Form Element
+:   Any `<input>` or `<select>` HTML tag. Synonymous to *Form Element*.
+
+Form Group
+:   The sourrounding `<div>` containing the `.control-label`,
+    `.form-control` `<div>`s, and `.help-block` `<p>`.