Goal

You can have your app greet users with a chosen form before they reach the rest of the app — an onboarding intake, a waiver, a “complete your profile” form, or a start-of-activity form. Once you’ve set this up, the form you pick appears automatically, and (for the app-open case) stops appearing on its own once the signed-in user has supplied everything it requires.

This is a no-code task. You build the form once in Gravity Forms, then point an app setting at it from a dropdown.

Before you start

• Your app needs the Gravity Forms integration available. The form-picker settings are gated on the mam_for_gravity_forms_forms_manager class, which ships with mam-main’s Forms Manager module; for the dropdowns to list any forms to pick, you need Gravity Forms and the MAM Gravity Forms plugin (mam-gravity-forms-manager) active with at least one form built. If you don’t see forms to pick, see Recipe: Activate the plugin (mam-gravity-forms-manager).
• Build the form first. See Recipe: Add a Gravity Form to your app (mam-gravity-forms-manager) for how to build a form and attach it to the app. The picker stores the form’s Form ID, so you can rename the form later without breaking anything.
• You need WP admin access to Mobile App Manager → App Settings.

Which “first form” do you mean?

“The form a screen opens to first” isn’t just one setting — it maps to a few distinct app settings, each scoped to a different part of the app, so start by picking the one that matches your goal. Three of these are form-list dropdowns — you select a form by name, and the setting saves its Form ID behind the scenes; the activity option works differently, as a yes/no toggle (activity_use_start_form).

Most people asking for this mean initial_form_to_display — “the app opens straight to a form the first time.” That’s the setting the rest of this how-to walks through; further down, we’ll cover how the others differ.

Steps: open the app to a form

1. Build (or identify) the form

Start in Gravity Forms and build the form you want users to see first — a short intake, say, with the fields you need to collect before the user can use the app. Mark the fields you genuinely require as required in Gravity Forms: the “stops appearing once complete” behavior described below keys off that GF required flag, so this is the step that makes the whole thing work.

Keep it short. Every required field is a question standing between the user and the rest of the app, so the form gates the whole experience on open.

2. Point the setting at the form

1. Go to Mobile App Manager → App Settings.
2. Pick the role you’re configuring — settings are stored per role, so you can show the intake form to one audience without showing it to another.
3. Find the Forms category and the “Form to display when opening the app?” dropdown (initial_form_to_display).
4. Select your form by name.
5. Save the role.

3. Verify in the app

Now see it work. Sign in to the app as a user in the role you configured, someone who has not yet completed the form:

1. The app should open to the form before the normal home screen.
2. Fill in the required fields and submit.
3. Re-open the app. The form should not appear again.

How “show it until it’s complete” works

This form isn’t a blunt “always show this.” When the app requests its data, MAM Suite checks whether the signed-in user already satisfies the form before deciding whether to display it at all:

• If there’s no signed-in user, or the picker isn’t set, nothing is shown.
• MAM loads the chosen form and checks its fields one by one: any field that’s required and still empty for this user makes the form incomplete.
• If anything required is still empty, the form gets pushed into the app’s payload — the bundle of data your app downloads from your site — and the app is told to open to it (internally, a has_initial_form_to_display flag is set to yes).
• If everything required is already filled in, the form drops out of the payload and the app goes straight to its normal first screen.

That’s what makes this behave like a one-time onboarding gate: it keeps appearing until the user has answered everything it needs, then quietly stops.

A couple of details worth knowing:

• Name fields are checked on both first and last name when the name field is required.
• Certain fields can be exempted from the “is it complete?” check via the mam_initial_form_exclude_fields filter (developer-only) — useful when a required-looking field actually gets filled in some other way and shouldn’t be allowed to keep the gate open. See Hook: mam_initial_form_exclude_fields if you need that level of control.
• Some fields get special handling too — ones the app fills in automatically, for instance — and are skipped in the completeness check so they can’t hold the gate open forever.

The other “first form” pickers

These work a little differently from the app-open form: instead of gating the whole app on open, each one places a chosen form at one specific screen.

• User Profile Form (mam_main_user_profile_form) and Form for User Profile in Nav Header (home_user_profile_form) decide which form backs the user profile experience. The app-open gate can tie into this too: point the picker at the same form as the user-profile form, and that profile form is what shows on open, until its required fields are filled.
• Activity start form shows up when a user starts an activity, controlled by the “Use Start Form When Starting Activity” toggle (activity_use_start_form). Turn the toggle on, then see App setting: activity_use_start_form for how the start form itself gets configured.

For both profile pickers, setup follows the same shape: build the form in Gravity Forms, then select it from the matching form-list dropdown in App Settings for the role.

Common gotchas

• No forms to pick. The pickers only list forms from the Gravity Forms integration — without Gravity Forms and the MAM Gravity Forms plugin active (and at least one form built), there’s nothing for the dropdowns to offer. See Recipe: Activate the plugin.
• The form keeps reappearing. For initial_form_to_display, that’s by design — it shows until every required field is filled for that user. If it never goes away, some required field is never getting satisfied; check whether the user can actually answer it, or exempt it with mam_initial_form_exclude_fields.
• The form never appears. Confirm a user is signed in (the gate is skipped for logged-out users), the right role is selected, and the picker is actually saved on that role — an empty or unsaved picker shows nothing.
• Per-role surprises. Because the setting is stored per role, a form you set for one role won’t show up for users in another — re-pick it on every role that should see it.
• Renaming vs. re-creating the form. Go ahead and rename the form any time — it’s safe, since the picker stores the Form ID, not the name. Deleting and re-creating it, though, gives the form a new ID, so you’ll have to re-pick it.

Verification

This article was last verified against:

• mam-main — includes/app-settings/admin-settings-page.php (the form-list settings: initial_form_to_display, mam_main_user_profile_form, home_user_profile_form)
• mam-main — includes/user-roles/form-manager.php and includes/app-settings/global-settings.php (the completeness check and has_initial_form_to_display logic)
• mam-gravity-forms-manager (required for the form pickers to appear)
• App setting docs: initial_form_to_display, activity_use_start_form

Re-verify whenever the initial_form_to_display completeness logic in form-manager.php / global-settings.php changes, the mam_initial_form_exclude_fields filter contract changes, a form-list setting is added or renamed, or the App Settings category/field labels are reorganized.

Related articles

• Recipe: Add a Gravity Form to your app (mam-gravity-forms-manager)
• Recipe: Activate the plugin (mam-gravity-forms-manager)
• App setting: initial_form_to_display
• App setting: activity_use_start_form
• Hook: mam_initial_form_exclude_fields