Pods DFV JS API

Overview

DFV is the JavaScript API that was built for Pods 2.7 as we were converting HTML+PHP based fields into something that could support repeatable fields. In Pods 2.8, this was revamped and expanded to support some additional field types and expand functionality into using React components from WordPress. Pods 2.8 also includes a revamp of the Edit Pod experience using React. Then in Pods 2.9, we converted more field types into DFV and now it powers the Simple Repeatable Fields functionality.

Now that Pods is using DFV in more places, interacting with field values and forms has made it necessary to create an underlying API that you can leverage when building integrations or customizations.

Accessing this API can be accomplished by interacting with the API object at: window.PodsDFV

Quick Glossary

• DFV: This stands for Dynamic Field Views and represents the entire Pods JS library for forms powered by React.
• Form Counter: Since Pods supports multiple forms on the same screen for multiple Pods and/or items, the Form Counter is necessary to distinguish between form instances. This will start at 0 and increment by 1 for each form instance for a specific Pod and Item. The only time this starts at 1 is on the Edit Pod screen itself, otherwise all other content form screens start with 0.

Get list of field configurations

This will get a list of field configurations based on Pod, Item ID, and Form Counter.

Parameters

PARAMETER	TYPE	DETAILS
pod	(string)	The Pod name.
itemId	(int)	The Item ID.
formCounter	(int)	The Form Counter value. Defaults to 1.

Returns

(Object|Array|undefined) Object of field data keyed by field name, an Array of fields across all Pods/Item IDs/Form Counters, or undefined if not found.

Examples

Work with a field configuration for a specific Pod / Item ID / Form Counter combination.

const fields = window.PodsDFV.getFields( 'your_pod_name', 123, 0 );

// Depending on the screen, your field will probably be prefixed with "pods_meta_".
const yourField = fields.pods_meta_your_field;

// Do what you want here.

// yourField.fieldConfig has the field configuration options as an object.
// yourField.fieldItemData has the item data as an array (if a relationship/file field).
// yourField.fieldValue has the initial field value from the page load, this is not live data.
// yourField.group has the Field Group name.
// yourField.pod has the Pod name.
// yourField.itemId has the Item ID.
// yourField.formCounter has the Form Counter.

Work with all field configurations for any Pod / Item ID / Form Counter combination.

const allFieldsOnScreen = window.PodsDFV.getFields();

allFieldsOnScreen.forEach( function( fieldSet ) {
	// Do what you want here.

	// field.pod has the Pod name.
	// field.itemId has the Item ID.
	// field.formCounter has the Form Counter.
	// field.fields has the object of field data keyed by field name (see above example).
} );

Get a field configuration

This will get a field configuration based on Pod, Item ID, Field Name, and Form Counter.

Parameters

PARAMETER	TYPE	DETAILS
pod	(string)	The Pod name.
itemId	(int)	The Item ID.
fieldName	(string)	The Field name.
formCounter	(int)	The Form Counter value. Defaults to 1.

Returns

(Object|undefined) The field data configuration, or undefined if not found.

Examples

Work with a specific field configuration.

// Depending on the screen, your field will probably be prefixed with "pods_meta_".
const yourField = window.PodsDFV.getFields( 'your_pod_name', 123, 0 );

// Do what you want here.

// yourField.fieldConfig has the field configuration options as an object.
// yourField.fieldItemData has the item data as an array (if a relationship/file field).
// yourField.fieldValue has the initial field value from the page load, this is not live data.
// yourField.group has the Field Group name.
// yourField.pod has the Pod name.
// yourField.itemId has the Item ID.
// yourField.formCounter has the Form Counter.

Get list of field values

This will get a list of current field values based on Pod, Item ID, and Form Counter.

Parameters

PARAMETER	TYPE	DETAILS
pod	(string)	The Pod name.
itemId	(int)	The Item ID.
formCounter	(int)	The Form Counter value. Defaults to 1.

Returns

(Object|Array|undefined) Object of field values keyed by field name, an Array of field values across all Pods/Item IDs/Form Counters, or undefined if not found.

Examples

Work with an array of field values for a specific Pod / Item ID / Form Counter combination.

const fieldValues = window.PodsDFV.getFieldValues( 'your_pod_name', 123, 0 );

// Depending on the screen, your field will probably be prefixed with "pods_meta_".
const yourFieldValue = fieldValues.pods_meta_your_field;

// Do what you want here.

Work with an array of field values for any Pod / Item ID / Form Counter combination.

const allFieldValuesOnScreen = window.PodsDFV.getFieldValues();

allFieldValuesOnScreen.forEach( function( fieldSet ) {
	// Do what you want here.

	// field.pod has the Pod name.
	// field.itemId has the Item ID.
	// field.formCounter has the Form Counter.
	// field.fieldValues has the object of field values keyed by field name (see above example).
} );

Get list of field values with field configurations

This will get a list of current field values along with the corresponding field configurations based on Pod, Item ID, and Form Counter.

This is handy if you want to work with the configuration and the current value of each field.

Parameters

PARAMETER	TYPE	DETAILS
pod	(string)	The Pod name.
itemId	(int)	The Item ID.
formCounter	(int)	The Form Counter value. Defaults to 1.

Returns

(Object|Array|undefined) Object of field values and their configurations keyed by field name, an Array of field values and their configurations across all Pods/Item IDs/Form Counters, or undefined if not found.

Examples

Work with an array of field values and their configurations for a specific Pod / Item ID / Form Counter combination.

const fieldValuesAndConfigs = window.PodsDFV.getFieldValues( 'your_pod_name', 123, 0 );

// Depending on the screen, your field will probably be prefixed with "pods_meta_".
const yourField = fieldValuesAndConfigs.pods_meta_your_field;

// Do what you want here.

// yourField.fieldConfig has the field configuration options as an object.
// yourField.value has the field value.

Work with an array of field values and their configurations for any Pod / Item ID / Form Counter combination.

const allFieldValuesAndConfigsOnScreen = window.PodsDFV.getFieldValues();

allFieldValuesAndConfigsOnScreen.forEach( function( fieldSet ) {
	// Do what you want here.

	// field.pod has the Pod name.
	// field.itemId has the Item ID.
	// field.formCounter has the Form Counter.
	// field.fieldValues has the object of field values and their configurations keyed by field name (see above example).
} );

Get field value for a field

This will get the current field value based on Pod, Item ID, Field Name, and Form Counter.

Parameters

PARAMETER	TYPE	DETAILS
pod	(string)	The Pod name.
itemId	(int)	The Item ID.
fieldName	(string)	The Field name.
formCounter	(int)	The Form Counter value. Defaults to 1.

Returns

(any|undefined) The field value, or undefined if not found.

Example

Get the field value for a specific field.

// Depending on the screen, your field will probably be prefixed with "pods_meta_".
const fieldValue = window.PodsDFV.getFieldValue( 'your_pod_name', 123, 'pods_meta_your_field', 0 );

// Do what you want here.

Set field value for a field

This will set the current field value based on Pod, Item ID, Field Name, and Form Counter.

Calling this will update React views for fields accordingly.

Parameters

PARAMETER	TYPE	DETAILS
pod	(string)	The Pod name.
itemId	(int)	The Item ID.
fieldName	(string)	The Field name.
value	(any)	The new value.
formCounter	(int)	The Form Counter value. Defaults to 1.

Returns

(void) No return value.

Example

Set the field value for a specific field to a new value.

// Depending on the screen, your field will probably be prefixed with "pods_meta_".
window.PodsDFV.setFieldValue( 'your_pod_name', 123, 'pods_meta_your_field', 'The new value', 0 );