Custom fields

Many objects within the DevHub platform support custom_fields that can then be used throughout the templates and pages within projects.

Supported objects

• Sites

• Locations

• Pages

• Posts

• Menu items

Datamodels and list of associated fields

Using the dashboard, you can visit Manage fields and view a specific datamodel to see its associated fields including the field slug and field_type.

To get the list of fields available programmatically for an object, these are tied to Datamodels (/api/v2/datamodels/:datamodel_id/) by type

• For Page templates, the Datamodel.id associated with the template is available via the Page.datamodel_id value on the Page template (page.type of template) object itself.

• For Site > Manage content fields, these are defined in two ways

  • Specific Datamodel.id associated with the Theme assigned to the Site (via site.theme_id)

  • If no specific assignment is set, uses the first datamodel of datamodel_type site_custom_fields

Field serialization

Guidance on how to send structured fields based on field type and slug

Text fields

Field types of short_text, long_text or multi_line_text.

"custom_fields": {
	"<field.slug>": "Field value",
	...
}

For multiline text, you will just send the value serialized with the linebreaks \n escaped within the JSON

"custom_fields": {
	"<field.slug>": "Multi-line.\nValue.",
	...
}

HTML fields

Field types of html or simple_html.

"custom_fields": {
	"<field.slug>": "<h1>Headline</h1><p>Some content</p>"
}

Linebreaks in the HTML are not needed

Images

Field type of image

To host the image within DevHub and supporting this native Image field, images will need to be first uploaded to DevHub using the Images endpoint (/api/v2/images/)

From the uploaded image, you will need to use the image.absolute_path and image.id values for sending within the custom fields

For storing in the custom_fields you would send the following pattern based on the field.slug

"custom_fields": {
	"<field.slug>": image.absolute_path,
	"<field.slug>_id": image.id,
	"<field.slug>_alt": "Optional alt tag associated with the image"
	...
}

Example of an image field with a slug of hero_image

"custom_fields": {
	"hero_image": "/img/upload/custom-hero-image.jpg",
	"hero_image_id": 12345,
	"hero_image_alt": "Optional alt tag associated with the image"
	...
}

Nested objects / Related models

Field type of related_model_list

We support nested objects, each with separated defined list of fields that can be used for each item in the list. Each of those fields then has a type. Nesting of related models (a related_model_list within a related_model_list item) is not currently supported.

"custom_fields": {
	"<field.slug>": [
		{
			"<related model field.slug>": "Field value",
			...
		},
		{
			"<related model field.slug>": "Field value",
			...
		}
	],
	...
}

Example of a FAQ related/nested field with a question and answer field

"custom_fields": {
	"faqs": [
		{
			"question": "Question 1?",
			"answer": "Answer to the question"
		},
		{
			"question": "Question 2?",
			"answer": "Answer to the question"
		}
	],
	...
}

Select field

Field type of select

Similar to the Text fields, the selected choice will be sent as a string. But this value must match the available field.choices strings.

"custom_fields": {
	"<field.slug>": "Option 2",
	...
}

Boolean field

Field type of boolean

Sent as a JSON true/false value

"custom_fields": {
	"<field.slug>": true,
	...
}