Gravity Forms

Introduction

The Gravity Forms Connector is an advanced addon that professional WordPress developers can utilize to create highly customized forms to permit your site’s visitors to add their own entries to your directory. And, when used in combination with the Gravity Forms User Registration Addon, it allows you to create a Gravity Form to permit the currently logged-in user to edit their directory entry.

Note

To be used in place of the Form add-on for Connections.

Important

In order to use the Edit Entry Gravity Form Feed action, you must setup a User Registration Form Feed using the Gravity Forms User Registration addon.

Important

This documentations assumes you are familiar with how to create complex forms in Gravity Forms.

Known Limitation

Important

Data loss potential! Please take note. The edit form must contain all in-use fields, else the omitted fields will cause existing data in those fields to be deleted.

Here is an example. You add an entry with a home address and a work address, but your Gravity Form to edit an entry only has the ability to edit the work address. When the Gravity Form is submitted, only the existing work address will be submitted regardless if it was changed or not. The home address will be removed from the entry. This might be an unexpected behavior, but it is the correct behavior because there is no way to know if a field not present in a Gravity Form is to be removed from the entry or if it is to be left unchanged.

To mitigate this potential issue, add the fields to your Gravity Form you do not wish to be user-editable. Then use CSS to hide the fields or make the fields conditional fields which are hidden by default and set the condition for the field to be visible to a condition that can not be met.

Installation

Important

First, and most importantly, before you can install and use the Gravity Forms Connector, you must first install Connections. Follow this link to the installation instructions.

Important

This addon requires the installation of the Link add-on.

Install the Gravity Forms Connector as you would any other WordPress plugin.

plugins-add-new

In the WordPress admin, under the Plugins menu, select Add New.

plugins-add-new-upload

Click the Upload link and the top of the page.

Browse to the location where you downloaded the Gravity Forms Connector zip file and select it.

screenshot-custom-entry-order-install-zipfile

Click Install Now.

Upon successful installation, click Activate Plugin.

settings-licenses-tab

Support License Activation

After you have activated Custom Entry Order , go to the Connections : Settings admin page and click the Licenses tab.

Enter the support license key that you received in your email receipt and click the Activate button. With your support license key activated, any time there is an update to the Gravity Forms Connector is released, you will be notified in the WordPress admin with an opportunity to update to the latest version with a single click.

Usage

The only required field a Gravity Form must contain to be compatible with the Gravity Form Connector is the Name field when creating a form to add Individuals.

Steps to create a Gravity Form to add a Connections entry.

  1. Create a new form and add your desired fields.
  2. Navigate to the form’s Connections Feed Settings.
  3. Map the Connections’ fields to the fields in your form.

Steps to create a Gravity Form to update a Connections entry. The steps are virtually identical as to creating a form to add an entry. The most important required step is to make sure you add a hidden field to the form for the Entry ID.

  1. Duplicate the form which was created to add a new Connection entry. (Recommended, not required. You can create a new one from scratch if desired.)
  2. Edit the form and add the Entry ID field.
  3. Navigate to the form’s Connections Feed Settings.
  4. Map the Connections’ fields to the fields in your form.

Important

An Entry ID field is required when creating a Gravity Form with an Update Entry Feed action.

Important

In order to ensure no data loss when using a Gravity Form to update an existing Connections entry, ensure the Update Entry Feed action has the same fields and that those fields are mapped in the Feed settings.

Form Fields

Entry ID

This field must be a hidden field. The “Field Label” is not essential and can be named anything which will help you identify the field.

Important

This is a required field in an “Update Entry” Feed action.
Visibility

To allow the user to choose their own entry visibility add a “Radio Buttons” field to your Gravity Form. Configure the form field, and give it a “Field Label” and “Description” of your choosing. Add three choices, the “Label” of these choices is unimportant. You may set them to anything you wish to help convey to the user what they are selecting. You must check the “show values” checkbox above the choices and set the values to public, private, and unlisted respectively as shown in the screenshot. It is recommended that you set this field to be required. If you choose not to make it a required field, then you must choose a default choice.

Below are a couple of demo forms that you can import into Gravity Forms showing how to set up the form fields to allow a user to choose their entry visibility and set the default visibility. These are very basic forms only, using the absolute minimum fields required to demonstrate how set the entry visibility. Use the Gravity Forms Import tool to import the demo forms. After you import the demo form, you will need to set up the Connections Feed for the imported form.

Tip

It is not required that you add all three choices, you may only add those which meet your requirements.

If you do not wish to allow the user to choose their entry visibility, add a “Hidden” field and set the “Default Value” option under the “Advanced” tab in the field settings to either public, private or unlisted.

Important

If you do not add this field the entry will default to being Public.
Entry Type

To allow the user to choose the entry type add a “Radio Buttons” field to your Gravity Form. Configure the form field, and give it a “Field Label” and “Description” of your choosing. Add two choices, the “Label” of these choices is unimportant. You may set them to anything you wish to help convey to the user what they are selecting. You must check the “show values” checkbox above the choices and set the values to individual and organization respectively as shown in the screenshot. It is recommended that you set this field to be required. If you choose not to make it a required field, then you must choose a default choice.

Below are a few demo forms which you can import into Gravity Forms showing how to set up the form fields to allow a user to choose their entry type, default to Individual entry type, and default to Organization entry type. These are very basic forms only, using the absolute minimum fields required to demonstrate how set the entry type. Use the Gravity Forms Import tool to import the demo forms. After you import the demo form, you will need to set up the Connections Feed for the imported form.

Tip

Adding this field is optional and only required if you plan on permitting the user to choose between submitting an “Individual” or “Organization” entry type.

Important

If you choose to omit this field, you must add the Name field for the Individual entry type and set the Name field to be required. OR Add a “Single Link Text” field for the Organization name and set the field to be required. You will also need to add a “Hidden” field and set the “Default Value” option under the “Advanced” tab in the field settings to organization to set the entry type to organization.

Note

It is not possible to allow users to create the “Family” entry type.
Name

The Name field is required if creating a form to permit users to submit the Individual entry type. Use the Gravity Forms Name field and configure as desired.

Organization

The Organization field is required if creating a form to permit users to submit the Organization entry type. Use the Gravity Form Single Line Text field.

Department

The Department field is optional. Use the Gravity Form Single Line Text field.

Title

The Title field is optional. Use the Gravity Form Single Line Text field.

Address

The Address field is optional. Use the Gravity Forms Address field.

Phone

The Phone field is optional. Use the Gravity Forms Phone field.

Email

The Email field is optional. Use the Gravity Forms Email field.

Links

The Link field is optional. Use the Gravity Forms Website field.

Biography

The Biography field is optional. Use the Gravity Forms Paragraph Text field.

Notes

The Notes field is optional. Use the Gravity Forms Paragraph Text field.

Categories

The Connections Categories field can be found within the Connections Fields group located below the core Gravity Form Pricing Fields group. If you are familiar with the core Gravity Forms Post Categories field, you will be familiar with the Connections Categories field as it functions the same with identical features with the primary difference being that it functions with Connections Categories instead of Post Categories.

  • General
    • Field Label :: Enter the form field label which will be displayed to the user.
    • Description :: Enter the form field description, which will be displayed to the user.
    • Field Type :: Select the field type that the category options will be displayed. The available options are: Dropdown, Checkboxes, Radio Options and Multi Select.
    • Category :: Choose to display all categories as options or select individual categories as options for the chosen field type.
    • Display placeholder :: This option will only be presented when the Drop Down field type is selected. Enabling this option will display a text input. Filling in the text input will display that text as the first option in the Drop Down. This is often used to display instructional text as the first option in the Drop Down. Leaving this option disabled will default to the Dropdown to the first displayed category when the form is submitted.
    • Rules ::
      • Required :: Whether or not the field is required.
      • No Duplicates :: Prevent duplicate options from being selected.
  • Appearance
    • Description Placement :: The field description placement in relation to the field input.
    • Custom Validation Message :: The error message displayed to a user if there is an error. If left blank, the default error message will be displayed to the user.
    • Custom CSS Class :: Custom CSS class names to add to the field.
    • Field Size :: Set the width of the field. Available options are Small, Medium, and Large.
  • Advanced
    • Admin Field Label :: Enter the field label displayed in the admin.
    • Visibility ::
      • Everyone :: Field will be displayed for the user submitting the form.
      • Hidden :: Field will be hidden from the user. This is useful for setting a default category(ies) to the submitted entry.
      • Administrative :: Field will only be visible in the Gravity Forms administration tool.
    • Allow field to be populated dynamically :: Enable this option to enable data to be passed to the form and pre-populated dynamically. Field data can be passed via HTTP Query Strings, WordPress Shortcode, and/or WordPress Hooks.
    • Enable Conditional Logic :: Enable rules to dynamically display or hide the field based on values from another field.

Tip

The Categories field is optional. If it is not added to the form, the submitted entry will be assigned the to Default Category.
Custom Field

To be implemented in a future update.

Feed Settings

Configuring the Feed is the most important part of setting up the Gravity Form. Without the feeds properly set up, the form will not add or be able to be used to update Connections entries.

Feed Details
  • Name :: Enter a name that will help you identify the feed in the admin.
  • Action :: You will select the appropriate action based on if you plan to use this feed to create a new directory entry or update an existing directory entry.
Map Fields

After choosing a feed action, the page will refresh, allowing you to map the fields from within your Gravity Form to fields within Connections. If you are familiar with the User Registration Add-on for Gravity Forms, the process is similar.

Connections has many fields, so the mapping step may feel overwhelming. To aid you with mapping, when possible, the form field selection will be limited to a similar field type within Connections. For example, when mapping the Connections entry name field, you can only choose the options from a Gravity Forms Name field. The same applies to the Connections address fields; you can only select from the Gravity Forms Address field options.

Entry Meta

If you registered custom fields, you can map the custom field ID to the Gravity Form field.

Note

Presently this only supports “Single Line Text” and “Paragraph Text” Gravity Forms fields being mapped to text and textarea custom fields.
Additional Options

Enable the Moderate Entry option if you wish to have the entry submission routed to the admin moderation queue.

When creating a Create feed action to create a new Connections entry and the Gravity Forms User Registration is installed and has a create user feed action, you will have the option to link the newly created WP User to the newly created Connections entry.

When creating an Update feed action to update a Connections entry and the Gravity Forms User Registration is installed, you can prioritize the data from the WordPress User Profile data or the Connections Entry data when prepopulating the form. The default is to prioritize the Connections Entry data.

Integrations

The Connections Gravity Forms Connector has been designed to work seamlessly with all of the Gravity Forms Addons in addition to specific support for:

PayPal Addon

When setting up the PayPal Addon Feed, there is an option to delay the Connections entry creation until after receiving payment.

User Registration Addon

When setting up the Update Entry Connections Feed, there is an Additional Option to prioritize the Connections Entry data over the WordPress User data when populating the Name field.