Summary

forms-manager (includes/forms-manager/) is the integration boundary between mam-main and the third-party Gravity Forms plugin. Almost every data-entry surface in a MAM Suite app — registration, contact, listing submission, profile completion, send-notification, claim-listing — is backed by a Gravity Form.

Without Gravity Forms installed, the forms-manager subsystem is largely inert. mam-main flags GF as deactivated via the mam_gravity_forms_deactivated option and the setup wizard surfaces a warning.

What the integration does

1. Discovery — pulls GF form definitions from the GF API
2. Augmentation — sibling plugins register custom (non-GF) forms via mam_form_manager_get_forms_from_plugins
3. Caching — transformed shapes cached in mam-form-cache-* options (see Form cache and invalidation)
4. Mobile transformation — converts GF schema into a mobile-renderable shape; fires per-field-type filters
5. Submission handling — receives app submissions via AJAX, runs validation, fires per-form-id hooks
6. Notification dispatch — fires mam_form_manager_send_notifications after submission

Discovery and augmentation

GF’s native API gives us the raw form list. mam-main augments via:

add_filter( 'mam_form_manager_get_forms_from_plugins', function ( array $forms ): array {
    $forms[] = array(
        'id'     => 'my_custom_form',
        'title'  => 'Subscribe to newsletter',
        'fields' => array( ... ),  // mobile-renderable shape
        'is_custom' => true,       // signals "this isn't a GF form"
    );
    return $forms;
} );

Custom forms have is_custom = true so the submission pipeline knows to skip GF-specific processing.

When GF is missing

If Gravity Forms isn’t installed or active:

• forms-manager subsystem registers but its GF integration is inert
• Custom forms (registered via mam_form_manager_get_forms_from_plugins) still work
• The setup wizard surfaces a “Gravity Forms required” warning
• Forms admin grids show empty
• The mobile app’s form_data JSON section is sparse

mam_gravity_forms_deactivated option tracks the deactivation state. The setup wizard re-checks on every visit.

Per-form integration pattern

For sibling plugins that bind to a specific GF form id (e.g., “the listing-submission form on this customer’s site”):

// Bind your handler to that form id specifically
add_filter( 'mam_for_gravity_forms_form_submitted_42', function ( $entry, $form, $confirmation ) {
    // your post-submission logic
    return $entry;
}, 10, 3 );

// Per-form result envelope
add_filter( 'mam_for_gravity_forms_form_result_form_42', function ( $result, $entry, $form ) {
    $result['redirect'] = '/thank-you';
    return $result;
}, 10, 3 );

Sibling plugins like mam-geodirectory store their form ids in their own settings (mam_gd_forms option) and bind dynamically based on those ids.

Pre-send transformation chain

The transformation chain that converts GF schema → mobile shape:

GF native form → mam_populate_gravity_form
              → per field: mam_form_manager_precached_field
              → per field: mam_form_manager_process_field_type_{type}  ← custom field types
              → mam_gf_populate_form_data_with_post_meta
              → mam_populate_gravity_form_final
              → mam_update_form_before_sending_{form-id}
              → mam_update_form_before_sending
              → cached in mam-form-cache-{form-id}

See Forms manager overview for the full hook list and Custom field types for the recipe.

Submission lifecycle (high-level)

App POSTs to wp_ajax_*_mam_gf_submit_app_form
        │
        ▼
Auth + nonce check
        │
        ▼
do_action('mam_gf_processing_form', $form_id, $entry)
        │
        ▼
Per-field validation (standard handlers + mam_form_manager_process_field_type_{type})
        │
        ▼
GF native submission (entry inserted)
        │
        ▼
mam_for_gravity_forms_form_submitted_{form-id}
        │
        ▼
Result envelope (mam_for_gravity_forms_form_result_form_{form-id} + variants)
        │
        ▼
do_action('mam_form_manager_send_notifications', $entry, $form, $result)
        │
        ▼
JSON response to app

See Form submission lifecycle.

Settings exposed

Gotchas

• Cache invalidation is the hard part. If admin edits a form in GF and the app still shows the old version, the cache wasn’t invalidated for that form id. See Form cache and invalidation.
• GF must be installed and active. Deactivating GF doesn’t break the WP site, but every mam-app form goes blank.
• Custom field types need two hooks — build-time (mam_form_manager_process_field_type_{type}) AND submit-time. Forgetting one breaks the round trip silently.
• Per-form dynamic hooks are the right extension point — not the generic versions. Bind to mam_for_gravity_forms_form_submitted_42, not the generic.
• Don’t fire mam_notification_send_message directly from form handlers — go through mam_form_manager_send_notifications.

Related articles

• Forms manager overview
• Form submission lifecycle
• Custom field types
• Form cache and invalidation
• Hook: mam_form_manager_get_forms_from_plugins
• Hook: mam_form_manager_process_fieldtype{type}
• Hook: mam_for_gravity_forms_formsubmitted{id}
• Hook: mam_form_manager_send_notifications

Metadata