API.md 6.47 KB
Newer Older
1
2
<!-- -*- markdown -*- -->

Carsten  Rose's avatar
Carsten Rose committed
3
4
5
API: Client / Server
====================

6

Carsten  Rose's avatar
Carsten Rose committed
7
8
9
10
11
12
13
14
15
16
17
18
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.

19
20
## General

Carsten  Rose's avatar
Carsten Rose committed
21
22
23

Asynchronous request (read AJAX) initiated by the client receive a JSON Response from the server containing at least:

24
25
26
	{
		"status": "success"|"error",
		"message": "<message>"
Carsten  Rose's avatar
Carsten Rose committed
27
28
29
    }
   
`status` indicates whether or not the request has been fullfiled by the server (`"success"`) or encountered an error (`"error"`).
30
31
32
33
34
On `"error"` the client must display `"<message>"` to the user. On
`"success"`, the client may display `"<message>"` to the user.

Depending on the request, the server may provide additional
information in the response, as outlined below.
Carsten  Rose's avatar
Carsten Rose committed
35
 
36
37
38
### Form Group Configuration

As part of the server response, the JSON stream may contain a key
39
`form-update`. It contains an array of objects having the following
40
41
42
structure

    {
43
44
45
46
47
48
49
50
51
52
53
54
		...
		"form-update" : [
			{
				"form-element": "<element_name>",
				"hidden": true | false,
				"disabled": true | false,
				"required": true | false,
				"value": <value>
			},
			...
		],
		...
55
56
57
58
    }


`"form-element"`
59
:	 the name of the HTML Form Element as it appears in the `name` attribute.
60
61

`"hidden"`
62
:   whether the Form Group is visible (value: `false`) or invisible (value: `true`).
63
64
65
66
67
	
`"disabled"`
:   whether or not the Form Element is disabled HTML-wise.

`"required"`
68
:   whether or not the Form Element receives the HTML5 `required` attribute.
69
70

`"value"`
71
:   For textual HTML Form Input elements, it is supposed to be a scalar value, which is set on the element.
72
73
74
	
	When `"form-element"` references a `<select>` element, a scalar value
    selects the corresponding value from the option list. In order to replace
75
    the entire option list, use an array of objects, having this format
76
77
	   
	    [
78
79
80
81
82
83
84
85
86
87
			{
				"value": 100,
				"text": "a",
				"selected": true
			},
			{
				"value": 200,
				"text": "b",
				"selected": false
			}
88
89
90
91
        ]
		
	`"select"` is optional, as is `"text"`. If `"text"` is omitted, it
    will be derived from value.
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
	
	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
information to client. It is up to the client to respect the
redirection information. The format of redirect information is
outlined below

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

`"redirect"`
		
Carsten  Rose's avatar
Carsten Rose committed
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138


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
139
140
141
142

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.
Carsten  Rose's avatar
Carsten Rose committed
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164

### 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>
        }
     ]
    }
    
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
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.
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
317

Client
: