feat: multi-page form submission improvements (#425)

* fix: Flush state between multiple calls to `GFUtils::submit_form()`

* feat: improve multi-page submission handling

Author: justlevine

CHANGELOG.md

@@ -5,9 +5,11 @@
 - feat!: Implement `FormField` model and `DataLoader`, and refactor `FormFieldsConnectionResolver` to extend `AbstractConnectionResolver`.
 - feat!: Refactor `FormsConnectionResolver` and `EntriesConnectionResolver` for compatibility with WPGraphQL v1.26.0 improvements.
 - feat!: Narrow `FormField.choices` and `FormField.inputs` field types to their implementations.
+- feat: Add `targetPageNumber` and `targetPageFormFields` to `SubmitGfFormPayload` for better multi-page form support.
 - fix!: Keep `PageField` with previous page data when filtering `formFields` by `pageNumber`. H/t @SamuelHadsall .
 - fix: Handle RadioField submission values when using a custom "other" choice. H/t @Gytjarek .
 - fix: Check for Submission Confirmation url before attempting to get the associated post ID.
+- fix: Flush static Gravity Forms state between multiple calls to `GFUtils::submit_form()`. 
 - feat: Add `FieldError.connectedFormField` connection to `FieldError` type.
 - dev: Use `FormFieldsDataLoader` to resolve fields instead of instantiating a new `Model`.
 - chore: Add iterable type hints.
@@ -16,6 +18,7 @@
 - chore!: Bump minimum Gravity Forms version to v2.7.0.
 - chore: Declare `strict_types` in all PHP files.
 - chore: Update Composer dev-dependencies and fix test compatibility with `wp-graphql-test-case` v3.0.x.
+- docs: Add docs on using Multi-page forms.
 
 ## v0.12.6.1
 

docs/submitting-forms.md

@@ -317,3 +317,52 @@ mutation submit {
   }
 }
 ```
+
+## Submitting Multi-page Forms
+
+When submitting a multi-page form, you can use the `sourcePage` and `targetPage` inputs to validate a specific page of the form before proceeding to the next page. This can then be combined with the Mutation payload's `targetPageNumber` and `targetPageFormFields` to serve the correct fields for the next _valid_ page.
+
+When using a `sourcePage`, only the fields on that page will be validated. If that page fails validation, the `targetPageNumber` and `targetPageFormFields` will return the current page number and fields, instead of the provided `targetPage` input. Similarly, if the page passes validation, but the `targetPage` is not available (e.g. due to conditional page logic), the `targetPageNumber` and `targetPageFormFields` will return the next available page number and fields.
+
+Only once the `targetPage` input is greater than the number of pages in the form, will the submission be processed, _all_ the values validated, and the entry created. As such, when using this pattern, it is recommended to submit all the user-provided `fieldValues` inputs to the mutation, and not just the fields on the current page.
+
+### Example Mutation
+
+```graphql
+mutation submit {
+	submitGfForm(
+		input: {
+			id: 50
+			fieldValues: [
+				# other form fields would go here.
+				{
+					# Text field value
+					id: 1
+					value: "This is a text field value."
+				}
+			]
+			saveAsDraft: false
+			sourcePage: 1 # The page we are validating
+			targetPage: 2 # The page we want to navigate to.
+		}
+	) {
+		errors {
+			id
+			message
+		}
+		confirmation {
+			message
+		}
+		entry { # Will only be returned if the `targetPage` is greater than the number of pages in the form.
+			databaseId
+		}
+		targetPageNumber # The page number to navigate to. Will be the same as the `sourcePage` if validation fails, and different than the `targetPage` if the `targetPage` is not available.
+		targetPageFormFields { # The form fields for the next page.
+			nodes {
+				databaseId
+				# Other field data
+			}
+		}
+	}
+}
+```

src/Connection/FormFieldsConnection.php

@@ -12,24 +12,57 @@
 
 namespace WPGraphQL\GF\Connection;
 
+use GraphQL\Type\Definition\ResolveInfo;
+use WPGraphQL\AppContext;
+use WPGraphQL\GF\Data\Factory;
+use WPGraphQL\GF\Data\Loader\FormsLoader;
+use WPGraphQL\GF\Mutation\SubmitForm;
 use WPGraphQL\GF\Type\Enum\FormFieldTypeEnum;
+use WPGraphQL\GF\Type\WPInterface\FormField;
 
 /**
  * Class - FormFieldsConnection
  */
 class FormFieldsConnection extends AbstractConnection {
-	/**
-	 * {@inheritDoc}
-	 */
-	public static function register_hooks(): void {
-		// @todo register to rootQuery.
-	}
-
 	/**
 	 * {@inheritDoc}
 	 */
 	public static function register(): void {
-		// @todo register to rootQuery.
+		// SubmitGfFormPayload to FormFields.
+		register_graphql_connection(
+			[
+				'fromType'      => SubmitForm::$name . 'Payload',
+				'toType'        => FormField::$type,
+				'fromFieldName' => 'targetPageFormFields',
+				'resolve'       => static function ( $source, array $args, AppContext $context, ResolveInfo $info ) {
+					// If the source doesn't have a targetPageNumber, we can't resolve the connection.
+					if ( empty( $source['targetPageNumber'] ) ) {
+						return null;
+					}
+
+					// If the form isn't stored in the context, we need to fetch it.
+					if ( empty( $context->gfForm ) && ! empty( $source['form_id'] ) ) {
+						$form = $context->get_loader( FormsLoader::$name )->load( (int) $source['form_id'] );
+
+						if ( null === $form ) {
+							return null;
+						}
+
+						// Store it in the context for easy access.
+						$context->gfForm = $form;
+					}
+
+					if ( empty( $context->gfForm->formFields ) ) {
+						return null;
+					}
+
+					// Set the Args for the connection resolver.
+					$args['where']['pageNumber'] = $source['targetPageNumber'];
+
+					return Factory::resolve_form_fields_connection( $context->gfForm, $args, $context, $info );
+				},
+			]
+		);
 	}
 
 	/**

src/Mutation/SubmitForm.php

@@ -35,7 +35,7 @@ class SubmitForm extends AbstractMutation {
 	 *
 	 * @var string
 	 */
-	public static $name = 'submitGfForm';
+	public static $name = 'SubmitGfForm';
 
 	/**
 	 * {@inheritDoc}
@@ -74,11 +74,11 @@ public static function get_input_fields(): array {
 	 */
 	public static function get_output_fields(): array {
 		return [
-			'confirmation' => [
+			'confirmation'     => [
 				'type'        => SubmissionConfirmation::$type,
 				'description' => __( 'The form confirmation data. Null if the submission has `errors`', 'wp-graphql-gravity-forms' ),
 			],
-			'entry'        => [
+			'entry'            => [
 				'type'        => Entry::$type,
 				'description' => __( 'The entry that was created.', 'wp-graphql-gravity-forms' ),
 				'resolve'     => static function ( array $payload, array $args, AppContext $context ) {
@@ -117,14 +117,18 @@ public static function get_output_fields(): array {
 					}
 				},
 			],
-			'errors'       => [
+			'errors'           => [
 				'type'        => [ 'list_of' => FieldError::$type ],
 				'description' => __( 'Field errors.', 'wp-graphql-gravity-forms' ),
 			],
-			'resumeUrl'    => [
+			'resumeUrl'        => [
 				'type'        => 'String',
 				'description' => __( 'Draft resume URL. Null if submitting an entry. If the "Referer" header is not included in the request, this will be an empty string.', 'wp-graphql-gravity-forms' ),
 			],
+			'targetPageNumber' => [
+				'type'        => 'Int',
+				'description' => __( 'The page number of the form that should be displayed after submission. This will be different than the `targetPage` provided to the mutation if a field on a previous field failed validation.', 'wp-graphql-gravity-forms' ),
+			],
 		];
 	}
 
@@ -161,14 +165,15 @@ public static function mutate_and_get_payload(): callable {
 			if ( $submission['is_valid'] ) {
 				self::update_entry_properties( $form, $submission, $entry_data );
 			}
-
 			return [
-				'confirmation' => isset( $submission['confirmation_type'] ) ? EntryObjectMutation::get_submission_confirmation( $submission ) : null,
-				'entryId'      => ! empty( $submission['entry_id'] ) ? absint( $submission['entry_id'] ) : null,
-				'errors'       => isset( $submission['validation_messages'] ) ? EntryObjectMutation::get_submission_errors( $submission['validation_messages'], $form_id ) : null,
-				'resumeToken'  => $submission['resume_token'] ?? null,
-				'resumeUrl'    => isset( $submission['resume_token'] ) ? GFUtils::get_resume_url( $submission['resume_token'], $entry_data['source_url'] ?? '', $form ) : null,
-				'submission'   => $submission,
+				'confirmation'     => isset( $submission['confirmation_type'] ) ? EntryObjectMutation::get_submission_confirmation( $submission ) : null,
+				'entryId'          => ! empty( $submission['entry_id'] ) ? absint( $submission['entry_id'] ) : null,
+				'errors'           => isset( $submission['validation_messages'] ) ? EntryObjectMutation::get_submission_errors( $submission['validation_messages'], $form_id ) : null,
+				'form_id'          => $form_id,
+				'resumeToken'      => $submission['resume_token'] ?? null,
+				'resumeUrl'        => isset( $submission['resume_token'] ) ? GFUtils::get_resume_url( $submission['resume_token'], $entry_data['source_url'] ?? '', $form ) : null,
+				'submission'       => $submission,
+				'targetPageNumber' => self::get_target_page_number( $target_page, $submission ),
 			];
 		};
 	}
@@ -300,4 +305,21 @@ private static function get_input_values( bool $is_draft, array $field_values, a
 
 		return $input_values + $field_values;
 	}
+
+	/**
+	 * Get the target page number use to resolve the mutation.
+	 *
+	 * @param int                     $original_target_page The original target page number.
+	 * @param array<int|string,mixed> $submission The Gravity Forms submission result array.
+	 */
+	private static function get_target_page_number( int $original_target_page, array $submission ): ?int {
+		// Valid Draft submissions should pass through to the original target page.
+		if ( ! empty( $submission['resume_token'] ) && ! empty( $submission['is_valid'] ) ) {
+			return ! empty( $original_target_page ) ? $original_target_page : null;
+		}
+
+		// Regular submissions should return the target page.
+		// In draft submissions, the target page is the source page, so this will work with invalid submissions.
+		return ! empty( $submission['page_number'] ) ? (int) $submission['page_number'] : null;
+	}
 }

src/Utils/GFUtils.php

@@ -362,6 +362,11 @@ public static function submit_form( int $form_id, array $input_values, array $fi
 			$source_page,
 		);
 
+		// Cleanup GF state.
+		unset( $_POST );
+		\GFFormsModel::flush_current_lead();
+		\GFFormDisplay::$submission = [];
+
 		if ( $submission instanceof \WP_Error ) {
 			throw new UserError( esc_html( $submission->get_error_message() ) );
 		}

tests/_support/Helper/GFHelpers/PropertyHelper.php

@@ -232,6 +232,10 @@ public function gquizWeightedScoreEnabled( ?bool $value = null ): ?bool {
 	}
 
 	public function errorMessage( $value = null ) {
+		if ( null === $value ) {
+			return null;
+		}
+
 		return ! empty( $value ) ? $value : 'Some error message';
 	}
 
@@ -267,7 +271,7 @@ public function hasInputMask( ?bool $value = null ): ?bool {
 	}
 
 	public function isRequired( $value = null ) {
-		return null !== $value ? $value : false;
+		return null !== $value ? ! empty( $value ) : false;
 	}
 
 	public function isSelected( $value = null ) {

tests/wpunit/FormFieldConnectionPageFilterTest.php

@@ -17,14 +17,12 @@ class FormFieldConnectionPageFilterTest extends GFGraphQLTestCase {
 	private $fields;
 
 	/**
-	 * run before each test.
+	 * {@inheritDoc}
 	 */
 	public function setUp(): void {
 		// Before...
 		parent::setUp();
 
-		wp_set_current_user( $this->admin->ID );
-
 		$this->fields  = $this->generate_form_pages( 3 );
 		$this->form_id = $this->factory->form->create(
 			array_merge(
@@ -37,7 +35,7 @@ public function setUp(): void {
 	}
 
 	/**
-	 * Run after each test.
+	 * {@inheritDoc}
 	 */
 	public function tearDown(): void {
 		// Your tear down methods here.