This app is in development. The description is NOT STABLE.
The Forms Soda application enables users with appropriate permissions to create and edit forms, and users with possibly different permissions to enter data using those forms. It uses the jQuery formBuilder library.
Data Formats
HTML
When a page containing a form is loaded, the HTML has the start and end of a full-width block, but the content between the start and the end is not HTML that displays the form. Instead, it is a JSON object that is interpreted by client Javascript code that displays the formBuilder form. The JSON object has a single attribute:
- formData - a JSON formData array as described at https://formbuilder.online/docs/formBuilder/demos/data/.
Whether the elements of the array contain user data as described at https://formbuilder.online/docs/formRender/actions/userData/ depends on whether the page is being edited. If the page is being edited, the user can edit the formBuilder form but not enter data, and they do not contain user data. If the page is not being edited, the user can use the formBuilder form to enter data, and they do contain user data.
If the page is being edited, the HTML also contains a <form> for the user to enter metadata describing the formBuilder form. It has style attribute display: none and is only displayed when the user edits the block containing the formBuilder form.
Form Definition
When a form is updated, or a draft is saved, the posted data consists of a JSON object with two attributes:
- formData - data that describes the form: the form template. This is a JSON object as described in the formRender documentation. Any user data that it contains is ignored by the server.
- formMetadata - metadata describing the form. This is a JSON object with the following string attributes:
- type - the type of the form: .GLOBAL, .SUBJECT, or .USER
- formws - the identifier of the item representing the workspace containing the view that the form is pinned to. If the form is not pinned to a view, this attribute is absent.
- formname - the name of the view that the form is pinned to. If the form is not pinned to a view, this attribute is absent.
User Data
When a form is being used to enter data, and the user saves the data, the posted data consists of a JSON object with one attribute:
- formData - data that describes the form and gives the field values entered by the user. This is a JSON object as described in the formRender documentation. It includes user data as described at https://formbuilder.online/docs/formRender/actions/userData/.
API
The Forms API extends the base Soda API. It has add_block, delete_block, get_block_draft, save_block_draft, and update_block methods that are invoked in the same way as the base Soda API methods but apply to blocks that contain forms. It also has a save_user_data method.
Add Form Block
Add a block containing a form to a page. The block will have full width.
Method
POST
Command
add_block
App
Forms
Other Parameters
- page - the identifier of the page that will contain the block
- blocks - the identifier of the set of blocks on the page that the block is to be added to
Response
If the request succeeds a status of 200 is returned and the response is the HTML code of the block, as described under HTML.
If the request is recognized but the block cannot be added (for example because the session does not have access permission) an appropriate HTTP status code is returned and the response is a JSON object with one attribute:
- error - a message describing the problem.
If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.
Delete Form Block
Delete a block containing a form. If the block has a draft, this is deleted also. The form is deleted with the block. Data entered using the form is not deleted. If the form is pinned to a view, the view is not deleted.
Method
POST
Command
delete_block
Other Parameters
- block - the identifier of the block
Response
If the request succeeds a status of 200 is returned.
If the request is recognized but the block cannot be deleted (for example because the session does not have access permission) an appropriate HTTP status code is returned and the response is a JSON object with one attribute:
- error - a message describing the problem.
If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.
Form Update
Save data entered by a user of a form.
Method
POST
Command
form_update
App
Forms
Other Parameters
- form - the identifier of the form
- data - the data to be saved, as described under User Data.
- segment - the identifier of the part of the view associated with the form that is to have data added to it. This might for example be a the values of a particular item created using an item definition form. It may be null if there is only one part of the view that can have data added to or edited in it, for example if a new item is being created using an item definition form, or if information about the user is being added or edited using a user information form.
Response
If the request succeeds a status of 200 is returned.
If the request is recognized but the data cannot be saved (for example because the session does not have access permission) an appropriate HTTP status code is returned and the response is a JSON object with one attribute:
- error - a message describing the problem.
If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.
Get Form Block Draft
Get the stored draft of a block containing a form.
This method is normally invoked when the block on the page containing the form is being edited.
Method
GET
Command
get_block_draft
Other Parameters
- block - the identifier of the block.
Response
If the request succeeds a status of 200 is returned and the response is a JSON object, as described under Form Definition.
If the request is recognized but the content cannot be returned an appropriate HTTP status code is returned and the response is a JSON object with one attribute:
- error - a message describing the problem.
In particular, if the block does not have a stored draft, a status of 404 (not found) is returned.
If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.
Save Form Block Draft
Save a draft of a block containing a form.
Method
POST
Command
save_block_draft
Other Parameters
- block - the identifier of the block
- content - the form definition as described under Form Definition.
Response
If the request succeeds a status of 200 is returned.
If the request is recognized but the draft cannot be saved (for example because the session does not have access permission) an appropriate HTTP status code is returned and the response is a JSON object with one attribute:
- error - a message describing the problem.
If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.
Update Block
Update a block containing a form, by changing the form. The width of the block cannot be changed.
Method
POST
Command
update_block
Other Parameters
- block - the identifier of the block
- content - the form definition as described under Form Definition.
Response
If the request succeeds a status of 200 is returned.
If the request is recognized but the data cannot be saved (for example because the session does not have access permission) an appropriate HTTP status code is returned and the response is a JSON object with one attribute:
- error - a message describing the problem.
If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.