Purpose

Form-state validation pass fired immediately after mam_get_phone_data_before_send. Lets sibling plugins inspect the assembled response and force the app to display a specific form on launch — caregiver invitation, pending staff invitation, claim-listing prompt, profile completion.

Signature

$data_array = apply_filters( 'mam_main_check_initial_form', array $data_array );

Returns: array — the (possibly augmented) data array.

How “force a form on launch” works

Set two top-level keys in the response:

$data_array['has_initial_form_to_display'] = 'yes';
$data_array['initial_form_to_display']     = $form_index;  // 1-based index into the form array

The mobile client checks has_initial_form_to_display on launch; if 'yes', it opens the form at initial_form_to_display instead of the normal home screen.

Example: prompt for caregiver invite acceptance

add_filter( 'mam_main_check_initial_form',
    function ( array $data_array ): array {

        $user_id = mam_current_request()->user_id();
        if ( ! $user_id ) return $data_array;

        $pending = $this->get_pending_caregiver_invite( $user_id );
        if ( ! $pending ) return $data_array;

        // Look up the form to inject.
        $form_id    = get_option( 'my_plugin_caregiver_accept_form_id' );
        $form_index = apply_filters( 'mam_gf_get_form_from_cache', 0, $form_id );
        if ( $form_index <= 0 ) return $data_array;

        $data_array['has_initial_form_to_display'] = 'yes';
        $data_array['initial_form_to_display']     = $form_index;

        return $data_array;
    }
);

mam-geodirectory uses this pattern for pending-staff-invite acceptance (inject_pending_invite_form()).

Pipeline order recap

phase_content:
    Button loop / form data / left menu / ajax_url
        │
        ▼
    apply_filters('mam_get_phone_data_before_send', $data_array)   ← ~70 subscribers
        │
        ▼
    apply_filters('mam_main_check_initial_form', $data_array)      ← THIS HOOK
        │
        ▼
phase_finalize:
    home_cats injection / output cleanup

Gotchas

• Runs once per request, after pre-send. Heavy work multiplies pipeline latency.
• initial_form_to_display is 1-based — be careful translating from 0-indexed array offsets.
• Multiple subscribers can each try to set the form. Last-writer-wins; if two competing flows both want to force-show a form, you need application-level conflict resolution.
• Frozen contract. The has_initial_form_to_display / initial_form_to_display keys are observed by deployed mobile clients.
• Don’t use this for normal data injection — that’s mam_get_phone_data_before_send. The “check initial form” filter is for force-on-launch decisions.

Related articles

• Phone data pipeline phases
• Mobile JSON shape
• Hook: mam_get_phone_data_before_send

Metadata