Commit cf61161b authored by Rafael Ostertag's avatar Rafael Ostertag
Browse files

Work in progress commit of API.md.

parent d98e622d
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>`.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment