Skip to content

Latest commit

 

History

History
202 lines (180 loc) · 7.68 KB

querying-formfields.md

File metadata and controls

202 lines (180 loc) · 7.68 KB

Querying formFields

Getting the formFields from a form or entry

Both forms and entries use the formFields GraphQL Interface to retrieve information about Gravity Forms fields, and their submission values.

In addition to the shared fields available on the FormField Interface, each Gravity Forms Field type implements a number of additional interfaces that correspond to their defined Gravity Forms Field Settings

By default, all Gravity Forms Fields - including custom ones - are automatically registered to the GraphQL schema - included custom ones!, and their specific GraphQL fields generated from GF_Field::get_form_editor_field_settings() . If you are using custom editor field settings, you will need to register those manually.

Basic Usage: Querying FormField types determinately.

The easiest way to query individual FormFields by requesting their properties directly. You can then map these fields directly to specific frontend component props. This method is best if you have a small form with a limited number of field types that rarely (if ever) changes, however is hard to scale while maintaining the Drag & Drop customizability of Gravity Forms.

Example Query

{
  gfForm(id: 1, idType: DATABASE_ID) {
    databaseId
    formFields(first: 300) {
      nodes {
        databaseId
        type
        cssClass
        ... on TextField {
          description
          label
          isRequired
        }
        ... on CheckboxField {
          description
          label
          choices {
            isSelected
            text
            value
          }
        }
        ... on NameField {
          description
          label
          inputs {
            isHidden
            label
            placeholder
          }
        }
      }
    }
  }
}

Advanced Usage: Querying FormField types indeterminately with GraphQL Interfaces.

With so many different types of Form Fields and possible settings, querying for FormFields determinately quickly becomes unscalable, requiring unnecessarily-specific frontend components and often forcing developers to limited fields/settings supported by the frontend.

Luckily, we can use GraphQL Interfaces to craft queries indeterminely based on possible Gravity Form Field settings, instead of tying them to an individual GraphQL object. While a bit more verbose to write initially, this method makes both GraphQL queries and frontend FormField components DRYer and more reusable.

Example

{
  gfForm(id: 1, idType: DATABASE_ID) {
    databaseId
    formFields(where: {pageNumber: 1}) {
      nodes {
        databaseId
        inputType
        type
        ... on GfFieldWithLabelSetting {
          label
        }
        ... on GfFieldWithRulesSetting {
          isRequired
        }
        ... on GfFieldWithAddressSetting {
          defaultState
          defaultCountry
          defaultProvince
          addressType
        }
        ... on GfFieldWithInputs {
          inputs {
            id
            label
            ... on AddressInputProperty {
              autocompleteAttribute
              customLabel
              placeholder
            }
          }
        }
        ... on GfFieldWithChoices {
          choices {
            text
            value
            ... on GfFieldChoiceWithChoicesSetting {
              isSelected
            }
            ... on ChainedSelectFieldChoice {
              choices {
                text
                value
                isSelected
              }
            }
          }
        }
      }
    }
  }
}

Getting formField entry values

Entry values can be accessed similarly to other Gravity Forms Field properties, by including the corresonding GraphQL field in the fragment.

Important

Due to GraphQL limitations regarding Union types, you must use the specific value type specific to that field. A full list of field value types and their corresponding field fragments are below.

As of v0.10.0, all formFields have access to the value GraphQL field, which provides the string representation of the entry value, created by GF_Field::get_value_export(). Certain supported formFields provide a value type specific to that field, as follows:

Field Value Type Used by Available subfields
addressValues ( obj ) AddressField city
country
lineTwo
state
street
zip
checkboxValues ( [ obj ] ) CheckboxField connectedChoice ( GfFieldChoice )
connectedInput (GfFieldInput)
inputId
text
value
fileUploadValues ( [ obj ] ) FileUploadField basePath
baseUrl
filename
url
imageValues ( obj ) ImageField altText
basePath
baseUrl
caption
description
filename
title
url
listValues ( [ obj ] ) ListField values ( [ string ] )
nameValues ( obj ) NameField first
last
middle
prefix
suffix
timeValues ( obj ) TimeField amPm
displayValue
hours
minutes
values ( [ string] ) ChainedSelectField
MultiSelectField
PostCategoryField
PostTagsField
QuizField
n/a

Example Query

{
  gfEntry(id: 1, idType: DATABASE_ID) {
    databaseId
    formFields(first: 300) {
      nodes {
        ... on CheckboxField {
          checkboxValues {
            inputId
            value
            ... on CheckboxFieldChoice {
              isSelected
            }
          }
        }
        ... on NameField {
          nameValues {
            prefix
            first
            middle
            last
            suffix
          }
        }
        ... on TextField {
          value
        }
      }
    }
  }
}

Filtering formFields

The code comments in the example query below explain how you can get a filtered list of form fields.

{
  gfEntry(id: 1, idType: DATABASE_ID) {
    databaseId
    formFields(
      first: 300
      after: "YXJyYXljb25uZWN0aW9uOjI=" # Or pass null to start from the beginning.
      where: {
        # Return a specific list of form fields.
        ids: [1,4,8]
        # Find form fields by their `adminLabel`.
        adminLabels: ['projectID', 'mylabel']
        # Filter form fields by field types.
        fieldTypes: [ ADDRESS, MULTISELECT, TEXTAREA ]
        # Filter form fields by the page number in multi-page forms.
        pageNumber: 2
      }
    ) {
      nodes {
        databaseId
        type
      }
    }
  }
}