QFQ Design / API Definition

API.md

+API: Client / Server
+====================
+
+Form initial call
+-----------------
+
+Request: index.php  (QuickFormQuery.php, included by Typo3 extension)
+
+Response:
+Form attributes:
+
+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
+-------
+
+Asynchronous request (read AJAX) initiated by the client receive a JSON Response from the server containing at least:
+
+    {
+      "status": "success"|"error",
+      "message": "<message>"
+    }
+   
+`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 load (update)
+------------------
+
+### Trigger
+
+Form Element with attribute `data-load="data-load"`.
+
+The client side JavaScript installs on change handlers for all HTML Form Elements having the `data-load` attribute.
+
+### Request: api/load.php
+
+#### Type
+POST
+
+#### Parameters
+
+##### URL
+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.
+
+### Response
+
+JSON Stream
+
+    {
+     "status": "success"|"error",
+     "message": "<message>",
+     "redirect": "client"|"url"|"no",
+     "field-name": "<field name>",
+     "field-message": "<message>",
+     "form-update": [ 
+        {
+          "form-element": "<element_name>",
+          "hidden": true | false,
+          "disabled": true | false,
+          "required": true | false,
+          "value": <value>
+        }
+     ]
+    }
+    
+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.
+
+
+Form save
+---------
+
+### Trigger
+none
+
+### Request: api/save.php
+
+#### Type
+POST
+
+#### Parameters
+
+##### URL
+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.
+
+### Response
+
+JSON Stream
+
+    {
+     "status": "success"|"error",
+     "message": "<message>",
+     "redirect": "client"|"url"|"no",
+     "field-name": "<field name>",
+     "field-message": "<message>",
+     "form-update": [ 
+        {
+          "form-element": "<element_name>",
+          "hidden": true | false,
+          "disabled": true | false,
+          "required": true | false,
+          "value": <value>
+        }
+     ]
+    }
+
+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.
+
+
+File (upload)
+-------------
+
+### Trigger
+none
+
+### Request: api/file.php
+
+#### Type
+POST
+
+#### Parameters
+
+##### URL
+`action=upload`
+
+##### POST
+Multi part form with file content, parameter `s` containing SIP, and parameter `name` containing the name of the HTML Form Element. 
+
+### Response
+
+JSON Stream
+
+    {
+      "status": "success"|"error",
+      "message": "<message>"
+    }
+
+
+Name    | Description
+------- | -----------
+status  | see General
+message | see General
+
+
+Record delete
+-------------
+
+Request: api/delete.php
+
+
+Return JSON encoded answer
+
+status: success|error
+message: <message>
+redirect: client|url|no
+redirect-url: <url>
+field-name:<field name>
+field-message: <message>
+
+Description:
+
+Delete successfull.
+ status = 'success'
+ message = <message>
+ redirect = 'client'
+
+Delete successfull.
+ status = 'success'
+ message = <message>
+ redirect = 'url'
+ redirect-url = <URL>
+
+Delete failed: Show message.
+ status = 'error'
+ message = <message>
+ redirect = 'no'
+

CODING.md

-Notes / Best Practices for Coding
-=================================
+Design / Notes / Best Practices for Coding
+==========================================
 
 General
 =======
@@ -88,6 +88,7 @@ Button status
 
 Save Button 
 -----------
+
 * User presses the button
   * Reset all validation states
   * Client validates HTML Form