Forms

IN DEVELOPMENT: FEATURE IS CURRENTLY NOT AVAILABLE

Due to the dynamic nature of AffinityLive it's really difficult to determine what fields are available and required when creating and editing objects. The forms feature can be used to retrieve a list of required and optional fields for a given object or group of objects. Once you have selected the details you wish to store, you can then simply submit the form with the same endpoints.

Endpoints

(POST|GET) [/object_type1,object_type2,..object_typeN]/_forms/fields

Request fields for given object type(s). For example,

$ curl -XGET /addresses,contacts/_forms/fields

would give you the fields for addresses and contacts available to the current user, so something like this:

{
    "response": {
		"forms": [{
			"form_type": "addresses",
			"form_content": [{
				"section_title": "Address",
				"section_content": [{
					"input_key": "title",
					"input_title": "Title",
					"input_type": "text",
					"input_options": [],
					"input_placeholder": "Your address..",
					"input_description": "This is your postal address.",
					"multiple_values" : 0,
					"required": 0
				}, ...]
			}]
		},{
			"form_type": "contacts",
			"form_content" : [{
				... contact fields ...
			}],
		}]
	},
	"meta": { ... }
}

You can also pass the form information in as body data. This can be used to configure the forms, which we will discuss a little bit later in the document. For example,

$ curl -XPOST /_forms/fields -d'{
	"forms": [{
		"form_type": "addresses",
		"form_config": { ... configure addresses form ... },
	}, {
		"form_type": "contacts"
	}]
}';

would return a similar structure of fields. The fields endpoint accepts the following parameters:

forms : The forms for each object type, with optional configuration options.

We currently only support the following form object types, which are being used in our mobile applications:

addresses
companies
contacts

POST /_forms

Submit given object type(s). For example, the following would submit two forms- address and contact.

$ curl -XPOST /_forms -d '{
	"forms": [{ 
		"form_type": "addresses",
		"form_config": { ... }
		"form_data": {
			"title": "My new address",
			"link" : {
				"type": "company",
				"id": 100
			},
			...
		}
	},{
		"form_type": "contacts",
		"form_data": {
			"contact.firstname": "Kurt",
            "affiliation.email": "abc@example.com",
			...
		}
	}]
}';

would create a contact and address with the supplied fields. The response will return the types and ids of the newly created objects.

{
    "response": {
		"submitted": [{
			"type": "address",
			"id": 112
		},{
			"type": "contact",
			"id": 1342
		}]
	},
	"meta": { ... }
}

The submit forms endpoint accepts the following parameters:

forms : The forms for each object type, with optional configuration options.
submit : The data you wish to submit for each type of form.

Linking new objects

When working with the input type "object" you're required to pass back a "type" and "id" of an existing object or "type" and "form", where "form" is an associative array of fields from that object's form. For example, the following will create a new company with a new physical address linked to it.

$ curl -XPOST /_forms -d '{
	"forms": [{ 
		"form_type": "companies",
		"form_config": { ... }
		"form_data": {
			"company.name" : "Kurt's sample company",
			"company.website": "http://www.kurts-sample-company.com",
			"company.physical_address" : {
				"type": "address",
				"form": {
					"form_type": "addresses",
					"form_config": { ... }
					"form_data": {
						"address.title" : "Kurt's sample address",
						"company.street1": "24323 Kurt's Test Street",
						"company.postcode": "2500",
						...
					}
				}
			},
			...
		}
	}]
}';

The "form" attribute is only supported for object's that are supported by this forms feature.

Multiple Value Support

There are some objects that support multiple values. These are indicated with a 1 in "mutiple_values" attributes from the fields endpoint. For example, companies can support multiple addresses. The following the creates a new physical address and links an existing address with id "1342".

$ curl -XPOST /_forms -d '{
	"forms": [{ 
		"form_type": "companies",
		"form_config": { ... }
		"form_data": {
			"company.name" : "Kurt's sample company",
			"company.website": "http://www.kurts-sample-company.com",
			"company.physical_address" : [{
				"type": "address",
				"id": 1342
			},{
				"type": "address",
				"form": {
					"form_type": "addresses",
					"form_config": { ... }
					"form_data": {
						"address.title" : "Kurt's sample address",
						"company.street1": "24323 Kurt's Test Street",
						"company.postcode": "2500",
						...
					}
				}
			}],
			...
		}
	}]
}';