Gravity Forms Nested Forms

What does it do?

This plugin adds a new Nested Form field type. This field allows you to select another form that will be used to collect “child” entries and attach them to the “parent” entry on submission. The child entries display in a clean, compact table on the parent form where they can be viewed, edited or deleted.

Can this be used as a Gravity Forms Repeater?

Yes, it sure can! While Nested Forms can perform much more complex functionality, it can be used as a simple Gravity Forms Repeater as well. A repeater allows you to dynamically add additional fields to a Gravity Form. GF Nested Forms differs only in that it allows you to submit the group of repeating fields via a modal.

Features

Documentation

1. How do I enable this functionality?
2. Feature Details
   1. Nested Form Field
      1. Field Settings
         1. Nested Form
         2. Display Fields
         3. Entry Labels
         4. Modal Header Color
         5. Entry Limits
         6. Feed Processing
      2. On the Frontend
      3. On the Backend
   2. Child Entries
   3. The {Parent} Merge Tag
      1. Populate Child Form Fields with Parent Form Data
      2. Display Parent Data in Child Form Notifications
   4. Feed Processing
   5. Calculations
   6. Templating
      1. Available Templates
      2. Templating Hooks
3. FAQs
   1. What happens to child entries when the parent entry is never submitted?
   2. How do I dynamically populate a Nested Form field?
   3. How to set a Nested Form as required?
   4. How do I include Nested Entry totals in the Parent Form total?
   5. Why are my child entries not counting towards the parent form’s total?
   6. How do I show a single value from each child entry?
   7. Why my Nested Form modal window (popup) is not displaying?
4. Known Limitations
5. Hooks

How do I enable this functionality?

After installing and activating Gravity Forms Nested Forms, you’ll want to add a Nested Form field to your form. Let’s step through that process.

	Create two forms; a parent form and a child form. The child form will be “nested” in the parent form via the Nested Form field.
	Add a Nested Form field on your parent form and select your child form in the Nested Form field setting.
	Select which fields from the child form should be displayed in the Nested Form field on the parent form.

Now that you have your first Nested Form field, let’s dig into the specifics of its settings and how it can be configured.

---

Feature Details

Nested Form Field

Field Settings

Nested Form

Select the form that should be used to create nested entries for current form.

Display Fields

Select which fields should be displayed on the current form from the nested entry.

Entry Labels

Specify a singular and plural label with which entries submitted via this field will be labeled (i.e. “player”, “players”).

Modal Header Color

Select a color which will be used to set the background color of the nested form modal header.

Entry Limits

Specify the minimum and maximum number of entries that can be submitted for this field.

Feed Processing

Specify when feeds attached to the nested form should be processed. By default, nested form feeds will be processed when the nested form is submitted. See Feed Processing for more details on this feature.

---

On the Frontend

By default, child entries will be displayed in a clean, compact table. Click the “Add” button to add a new child entry.

The Display Fields selected in the field settings will be displayed for each submitted child entry. Child entries can be edited by clicking the “Edit” link and deleted by clicking the “Delete” link.

On the Backend

The backend will also display the configured Display Fields for each child entry. To view the full child entry click the “View Entry” button. To view the child entries in the Gravity Forms list view, click the “View Expanded {Item} List” link.

---

Child Entries

Child entries are entries that are submitted via a Nested Form field. For examples of how child entries are displayed on the frontend and on the backend, see the respective section.

In order to protect the user from accidental data loss, child entries will be repopulated into the Nested Form field if the parent form is reloaded.

---

The {Parent} Merge Tag

The special {Parent} merge tag allows you to 1) populate data entered into the parent form into the child form and 2) populate data submitted on the parent entry in child form notifications.

Populate Child Form Fields with Parent Form Data

Any field on the child form that supports a default value can be populated via the {Parent} merge tag. Currently, you must manually specify the field/input ID from the parent form that should be populated into the child form. In the following example, we’ll populate the value of field ID 3 from the parent form into field ID 1 on the child form.

To populate multi-input fields (like the Name field), you will need to specify the input ID (which includes the field ID and the input index).

Here is a quick reference guide for the input indexes of common field types. The input ID will always use the FIELDID.INPUTID format. For example, a field ID of 2 and an input index of 3 would give you an input ID of 2.3.

All examples assume a field ID of 1.

Input Name	Index	Example
Name Field
Prefix	2	{Parent:1.2}
First	3	{Parent:1.3}
Middle	4	{Parent:1.4}
Last	6	{Parent:1.6}
Suffix	8	{Parent:1.8}
Address Field
Street Address	1	{Parent:1.1}
Address Line 2	2	{Parent:1.2}
City	3	{Parent:1.3}
State / Province	4	{Parent:1.4}
Zip / Postal Code	5	{Parent:1.5}
Country	6	{Parent:1.6}

Display Parent Data in Child Form Notifications

The {Parent} merge tag can also be used to display data from the parent entry in the notification send for a child entry. The desired entry property must be manually specified. For example, if you want to fetch the parent entry ID, you would use {Parent:id}. If you want to fetch the parent entry creation date, you would use {Parent:date_created}.

All properties of the entry object are supported. For a full list, see Gravity Forms’ Entry object documentation.

---

Feed Processing

By default, GF Nested Forms will only process feeds attached to the nested form after the parent form is submitted.

A practical example of this would be a parent form that creates a team and a nested form that uses the User Registration to register players. In most cases, you wouldn’t want the user accounts created for the players until the team submission has been finalized. GF Nested Forms handles this for you automatically.

In some cases, you may want to trigger the nested form feed to be processed when the nested form is submitted (e.g. collecting emails for a mailing list via MailChimp). To enable this, select the “nested form” option on the “Feed Processing” field setting.

For even more granular control over when nested feeds are processed, use the gpnf_should_process_feed filter.

---

Calculations

GF Nested Forms provides support for using Nested Form fields in your Gravity Forms calculations. To use a Nested Form field in your calculation formula, you will need to manually type the desired merge tag using the following template:

{FIELD_LABEL:FIELD_ID:MODIFIER}

The following examples are based on a field label of “Players” and a field ID of “1”.

• count – Returns the total number of child entries attached to the Nested Form field. If there are two child entries submitted for a Nested Form field, this merge tag would return 2.

  {Players:1:count}

• total – Returns the sum of all child entry totals. For example, if Child Entry #1 has a total of $10 and Child Entry #2 has a total of $25, this merge tag would return 35.

  {Players:1:total}

• sum – Returns the sum of the specified target field’s value from each child entry. For example, you had a Quantity field with an ID of “2” on your nested form and Child Entry #1 had a quantity of 2 and Child Entry #2 had a quantity of 3, this merge tag would return 5.

  {Players:1:sum=2}

---

Templating

You can take complete control over the Nested Form field output via the templating system. To do so, you will need to copy the template files from the plugin to your theme.

In the plugin, they’re located in the templates directory:

<WordPress plugins>/gp-nested-forms/templates

In your theme, you will need to create a directory named gp-nested-forms and copy the template files there:

<WordPress themes>/your-theme/gp-nested-forms/

Now anytime GF Nested Forms attempts to load a template file, it will pull your version of the template file from your theme.

Available Templates

• nested-entries.php – Used to render the child entries in a Nested Form field on the frontend.
• nested-entries-detail.php – Used to render the child entries on the entry detail page (in the Gravity Forms backend).
• nested-entries-simple-list.php – Used to render a single value from each child entry in a simple list format when the Nested Form field merge tag (or {all_fields} merge tag) is filtered to a single field via the All Fields Template plugin (e.g., {Players:1:filtered[2]}).
• nested-entry.php – Used to render a single child entry via the Nested Form field merge tag (e.g. {Players:1} – or – when a Nested Form field is rendered via the {all_fields} merge tag.

Templating Hooks

To make minor changes to verbiage or customize the data that will be used to render the Nested Form field, use the gpnf_template_args filter.

---

FAQs

What happens to child entries when the parent entry is never submitted?

Child entries with no parent entry are called orphaned entries. Orphaned entries are considered “expired” after a week. Expired entries are trashed daily. To modify how long orphaned entries should be preserved, use the gpnf_expiration_modifier filter.

If the user returns the form, their orphaned child entries will be repopulated into the Nested Form field.

How do I dynamically populate a Nested Form field?

Nested Form fields can be dynamically populated the same way as other Gravity Forms fields. Nested Form fields expect a comma-delimited list of entry IDs for the dynamic population value.

How to set a Nested Form as required?

To set a Nested Form as required, go to the Advanced tab of the field options window and set the Minimum field to “1” in the Entry Limits option.

How do I include Nested Entry totals in the Parent Form total?

We’ll need to include a Calculated Product field on the parent form to capture the entry totals for each nested entry and automatically apply those totals towards the Parent Forms total. Here’s how to set this up in three, quick steps.

	Add a Product field to your parent form.
	Set the “Field Type” setting to “Calculation” and check the “Disable quantity field” checkbox.
	Manually enter the Nested Form field merge tag into the “Formula” setting and append the “:total” modifier. The Nested Form field merge tag is not yet available in the merge tag list. Just add {:1:total} where “1” is the ID of your Nested Form field on your parent form.

All done! See the demo at top of this page to see this live.

Why are my child entries not counting towards the parent form’s total?

You must explicitly include child entry totals in your parent form via a Calculated Product field. See this walkthrough.

How do I show a single value from each child entry?

First, you’ll need to install our All Fields Template plugin. This provides the ability to filter which fields from the nested form are displayed in the Nested Form field’s merge tag (and {all_fields}).

Once installed, you can filter down to a specific field like so:

{Players:1:filter[1]}

Based on our demo form, this would display a simple list of the Player’s names.

Why my Nested Form modal window (popup) is not displaying?

An element with a larger z-index generally covers an element with a lower one. So if your theme has a larger z-index specified, it’ll cover the modal window from the Nested Forms field. The solution in this case is to specify a larger z-index number for the Nested Form modal window, like this: .gpnf-dialog.ui-dialog { z-index: 99999999 !important; }

---

Known Limitations

• You may not include a Nested Form field within a nested form.
• You may not display a form independently if it is nested inside of a Nested Form field on the same page.
• Exporting a parent entry does not export child entry data. We welcome your feedback on how you would expect this upcoming feature to work.
• Mobile support is lacking; we are working on improvements for v1.0.
• Payment feeds will not be processed on child forms.
• GravityView does not support our Nested Forms yet.

---

Hooks

• gpnf_all_fields_markup
  
• gpnf_bypass_entry_permissions
  
• gpnf_display_value
  
• gpnf_entry_url
  
• gpnf_expiration_modifier
  
• gpnf_init_script_args
  
• gpnf_item_labels
  
• gpnf_jquery_ui_dependencies
  
• gpnf_should_process_feed
  
• gpnf_should_send_notification
  
• gpnf_template_args