PROTOCOL.md 7.25 KB
Newer Older
1
2
<!-- -*- markdown -*- -->

3
# Client/Server Protocol
Carsten  Rose's avatar
Carsten Rose committed
4

5
## Form initial call
6

Carsten  Rose's avatar
Carsten Rose committed
7
8
9
10
11
12
13
14
15
16

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.

17

18
## General Protocol
Carsten  Rose's avatar
Carsten Rose committed
19

20
21
22
23
### 

Asynchronous request (read AJAX) initiated by the Client receive a
JSON Response from the server containing at least:
Carsten  Rose's avatar
Carsten Rose committed
24

25
26
27
	{
		"status": "success"|"error",
		"message": "<message>"
Carsten  Rose's avatar
Carsten Rose committed
28
29
    }
   
30
31
32
33
`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.
34
35
36

Depending on the request, the server may provide additional
information in the response, as outlined below.
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

### HTML Form Element Validation

The Server may perform a serverside validation of values submitted. If
the validation fails, it may notify the Client by adding following
name/value pairs to the response JSON Stream

	{
		"status": "error",
		...
	    "field-name": "<field name>",
		"field-message": "<message>",
		...
	}
	
Only one validation failure per request can be reported to Client.

The Server is expected to set the status `"status"` to `"error"`, and
the Client is expected to treat the error as explained in [General]
and must obey the rules of redirection as explained in [Redirection].

The Client must visibly highlight the HTML Form Element that caused the
validation failure.

`"field-name"`
:	The value of the `name` attribute of the HTML Form Element that
	caused the validation failure.
	
`"field-message"`
:	Message to the User, indicating the nature of the failure.
Carsten  Rose's avatar
Carsten Rose committed
67
 
68
69
70
### Form Group Configuration

As part of the server response, the JSON stream may contain a key
71
`form-update`. It contains an array of objects having the following
72
73
74
structure

    {
75
76
77
78
79
80
81
82
83
84
85
86
		...
		"form-update" : [
			{
				"form-element": "<element_name>",
				"hidden": true | false,
				"disabled": true | false,
				"required": true | false,
				"value": <value>
			},
			...
		],
		...
87
88
89
90
    }


`"form-element"`
91
:	 the name of the HTML Form Element as it appears in the `name` attribute.
92
93

`"hidden"`
94
:   whether the Form Group is visible (value: `false`) or invisible (value: `true`).
95
96
97
98
99
	
`"disabled"`
:   whether or not the Form Element is disabled HTML-wise.

`"required"`
100
:   whether or not the Form Element receives the HTML5 `required` attribute.
101
102

`"value"`
103
:   For textual HTML Form Input elements, it is supposed to be a scalar value, which is set on the element.
104
105
106
	
	When `"form-element"` references a `<select>` element, a scalar value
    selects the corresponding value from the option list. In order to replace
107
    the entire option list, use an array of objects, having this format
108
109
	   
	    [
110
111
112
113
114
115
116
117
118
119
			{
				"value": 100,
				"text": "a",
				"selected": true
			},
			{
				"value": 200,
				"text": "b",
				"selected": false
			}
120
121
122
123
        ]
		
	`"select"` is optional, as is `"text"`. If `"text"` is omitted, it
    will be derived from value.
124
125
126
127
128
129
130
131
132
133
134
	
	HTML checkboxes are ticked with a `"value"` of `true`. They are
    unchecked with `false`.
	
	HTML radio buttons are activated by providing the value of the
    radio button `value`-attribute to be activated in `"value"`.
	

### Redirection

Depending on the request, the server may return redirection
135
136
137
138
139
140
141
information to Client. It is up to the Client to respect the
redirection information.

The Client must not perform a redirect in case the status in
`"status"` is `"error"`.

The format of redirect information is outlined below
142
143
144
145
146
147
148
149
150
151

	{
		...
		"redirect": "no" | "url" | "client"
		"redirect-url": "<url>"
		...
	}
	

`"redirect"`
152
153
154
155
156
157
158
159
:	type of redirection. `"no"` advises the Client to stay on the
	Current Page. `"client"` advises the Client to decide where to
	redirect to. `"url"` advices the Client to redirect to the URL
	provided in `"redirect-url"`.
	
`"redirect-url"`
:	Used to provide an URL when `"redirect"` is set to `"url"`. It
	should be disregarded unless `"redirect"` is set to `"url"`.
160
		
Carsten  Rose's avatar
Carsten Rose committed
161
162


163
## Form Update
Carsten  Rose's avatar
Carsten Rose committed
164

165
166
Request URL
:	api/load.php
Carsten  Rose's avatar
Carsten Rose committed
167

168
169
Request Method
:	POST
Carsten  Rose's avatar
Carsten Rose committed
170

171
172
URL Parameters
:	none
Carsten  Rose's avatar
Carsten Rose committed
173

174
175
Server Response
:   The response contains
Carsten  Rose's avatar
Carsten Rose committed
176

177
178
179
180
181
The Client may request an updated set of Form Group Configuration and
HTLM Element states. In order for the Server to compile the set of
Form Group Configuration and HTML Element states, it requires the
entire HTML Form in the POST body, without any HTML Input Elements of
type `file`.
182

183
The Client must include the SIP using an HTML Input Element (most likely of `type` `hidden`).
Carsten  Rose's avatar
Carsten Rose committed
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303


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'

304
305
306
307
308
309
310
311
312
313
314
## 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>`.
315
316

Client
317
318
319
320
321
322
323
324
325
:   Application that enables a user to interact with QFQ, i.e. a Web Browser.


Current Page
:	The currently displayed page in the Client.

Redirect
:	Issued by the Server. It is a command prompting the Client to
	navigate away from the Current Page.