Gravity Forms 文档

Email Routing in Gravity Forms Notifications

IntroductionConfigurationTroubleshooting

Introduction

Within each Gravity Forms notification, you have the option of configuring additional routing. This is similar to conditional logic, in that different events can cause the notification to go to a different recipient. But unlike conditional logic, Routing can』t prevent the notification processing, it only provides the email address to be used for the Send To setting, therefore it』s important to make sure your routing rules will cover all the possible user choices to prevent scenarios where your routing setup doesn』t provide any email address and therefore the notification is processed with an empty value for the Send To.

In this article, we will show you how to configure routing options within your notification.

Configuration

This short animation shows how to access and modify Notifications for a form.

First, start by accessing the notification that you want to configure additional routing for. This can be done by accessing the form associated with the notification, hovering over Settings, clicking on Notifications, and then accessing the notification you want to manage. If you want to create a new notification, simply click the Add New button. Within the settings for your notification, you will see an option labeled Send To. If you select Configure Routing, additional options similar to conditional logic will appear. Inside the routing configuration, the first thing you will need to do is determine where the notification will be sent if the routing condition is met. Simply enter the email address of the user that you want to send the notification. Next, you』ll need to configure the field that the routing condition will use. To do so, use the dropdown box to select the field that the condition will be based on. Now that the field is selected, you』ll need to set the operator used to compare the field and value. For example, if you only want to send this notification if a particular radio button is checked, you would select is within the operator dropdown. Conversely, if you do not want a notification to be sent when that radio button field is selected, you would use is not. Finally, you』ll need to set the value that will be used to compare against the field submission result. If using pre-selected options, this will appear as a dropdown. If the field is something like a text field where the user will enter their own value, the condition value will appear as a text box. Within the condition value, enter the value to compare with the submission. If you want to add additional conditions or remove a condition, use the + and – icons to the right of the condition item to either add or remove it.

You can now continue configuring your notification as seen fit.

Troubleshooting

If Routing rules are not working as you expected there is a high likelihood that you』re facing one of the following:

You added or modified field values after configuring Routing. Routing rules are based on existing values when you saved them, if you use a choices field like a Drop Down for your Routing rules, and you change any of these field choices after configuring Routing, you need to update your Routing rules to select the new or modified choice(s) and save your notification settings. It doesn』t matter if you just changed a single character, any change done to choices used in your Routing rules matters. The following screenshot shows an example of an outdated Routing rule, when it was configured the choice selected was Jim, but currently, that choice no longer exists, the Drop Down was edited and Jim was replaced by Samuel, therefore, the Routing rule will not work. Your routing rules are not covering all the possible user selection. If your Routing rules are based on a drop down that has three choices, but you only have Routing rules added for two of the choices, the notification will fail when the user selects the third choice without a matching Routing rule.

Email Field CSS Selectors

ContainerInput

Container
example: email field container (div) – applies to all forms
1body .gform_wrapper .gform_body .gform_fields .gfield .ginput_container_email {border: 1px solid red;}
example: email field container (div) – applies just to form ID #1
1body #gform_wrapper_1 .gform_body .gform_fields .gfield .ginput_container_email {border: 1px solid red;}
example: email field container (div) – applies just to specific container (based on the unique parent element ID – replace 「XX_X」 with your actual element ID)
1body #gform_wrapper_1 .gform_body .gform_fields #field_XX_X.gfield .ginput_container_email {border: 1px solid red;}
Input
example: email field input (input) – applies to all forms
1body .gform_wrapper .gform_body .gform_fields .gfield .ginput_container_email input {border: 1px solid red;}
example: email field input (input) – applies just to form ID #1
1body #gform_wrapper_1 .gform_body .gform_fields .gfield .ginput_container_email input {border: 1px solid red;}
example: email field input (input) – applies just to specific container (based on the unique parent element ID – replace 「XX_X」 with your actual element ID)
1body #gform_wrapper_1 .gform_body .gform_fields #field_XX_X.gfield .ginput_container_email input {border: 1px solid red;}

Forms List Page

Filter ToolbarSorting OptionsForm Quick ToolbarForm ActionsBulk Actions

The forms list page displays a list of all your forms. From this page you can manage and edit your existing forms and get a quick rundown on basic analytics such as views, number of entries, and the conversation ratio.

Filter Toolbar

The filter toolbar allows you to filter which forms you would like to view: All, Active, Inactive, and Trash. In the parenthesis beside each filter label is the number of forms currently applicable to that filter. By default All forms will be displayed, although you can select to view only Active or Inactive forms.

Sorting Options

StatusTo the left of the form name is the status icon. By default this is checked, which activates the form. To inactivate a form, simply click on the status icon to change the status.

TitleThis is the form name. It is editable by using the form editor.

IDThis is the form id. You can use this for displaying the form via the shortcode or function call.

EntriesThe number of times a form entry has been created by submitting the form.

ViewsThe number of times a form has been viewed.

ConversionThe ratio of entries to views, expressed as a percentage. Note that form previews do not count as views, but entries submitted by a form preview do count as an entry.

Form Quick Toolbar

Each form has a toolbar that displays when you hover over the first cell of a form row. This quick toolbar will allow you to edit the form, view the form settings, view the form entries, preview the form, make a copy of the form, or send the form to the trash to be deleted later.

Animation showing the quick toolbar available by hovering over a form title.

Form Actions

The following form actions are available per form in the Form Quick Toolbar by hovering over a form in the list.

EditEdit the form using the form editor.

SettingsThis deals with all of the settings of your form such as Form Settings, Confirmations, and Notifications.

PreviewPreview the form to see how it will look to the enduser. This can also be used to submit an entry or test.

EntriesView the entries for this form.

DuplicateCreate a duplicate of this form. Duplication includes all form, field, and notification settings.

TrashChoosing this option will send the form to the Trash.

Bulk Actions

Using bulk actions you may apply the same action to multiple forms at once. To use bulk actions, you must first select the checkbox next to each form you would like to modify. Then select the desired action from the Bulk Actions drop down list, and click 「Apply.」

The following bulk actions are available:

Mark as Active/InactiveMark all selected forms as active/inactive.

Reset ViewsReset the counter for the number of times a form has been viewed.

Permanently Delete EntriesDelete all of the entries associated with the selected form. These entries cannot be restored.

Move to trashSend the selected forms to the Trash.

The short animation shows the application of a bulk action.

Using EDD Software Licensing with the Add-On Framework

IntroductionThe ConstantsThe License Key SettingValidating the License KeyActivating and Deactivating the License KeyPerform the Remote RequestPlugin UpdatesImportant

Introduction

In this article we will show how you can integrate your add-on with the Easy Digital Downloads Software Licensing extension to handle license key activation, deactivation, validation, and enabling access to automatic updates.

Before reading on we do recommend you read the following articles from the EDD documentation:

Activating License Keys in WP Plugins and ThemesDeactivating License Keys in WP Plugins and ThemesAutomatic Upgrades for WordPress Plugins

The following examples are based on the Simple Add-On from the Add-On Framework article.

The Constants

Some of the arguments used in the various requests to the EDD Software Licensing API are identical so we are going to store their values in constants.

In our Simple Add-On we have already defined the add-on version number (GF_SIMPLE_ADDON_VERSION) in the root file so we will add our two new constants there.

define( 'GF_SIMPLE_ADDON_VERSION', '2.0' );
define( 'GF_SIMPLE_ADDON_EDD_SL_STORE_URL', 'http://yoursite.com' );
define( 'GF_SIMPLE_ADDON_EDD_SL_ITEM_NAME', 'Simple Add-On' );

GF_SIMPLE_ADDON_EDD_SL_STORE_URL is the URL of the site where you have installed the Easy Digital Downloads plugin and Software Licensing extension.

GF_SIMPLE_ADDON_EDD_SL_ITEM_NAME is the name of the product as you have configured it in EDD.

The License Key Setting

The plugin_settings_fields() function of our example add-on had a simple text field named mytextbox. In the following example we have replaced that field with a new text field named license_key which will use a password type input to capture the license key.

/**
* Configures the settings which should be rendered on the add-on settings tab.
*
* @return array
*/
public function plugin_settings_fields() {
return array(
array(
'title' => esc_html__( 'Simple Add-On Settings', 'simpleaddon' ),
'fields' => array(
array(
'name' => 'license_key',
'label' => esc_html__( 'License Key', 'simpleaddon' ),
'type' => 'text',
'input_type' => 'password',
'validation_callback' => array( $this, 'license_validation' ),
'feedback_callback' => array( $this, 'license_feedback' ),
'error_message' => esc_html__( 'Invalid license', 'simpleaddon' ),
'class' => 'large',
'default_value' => '',
),
),
),
);
}

Review the Settings API documentation for more details about how to define sections of fields.

Validating the License Key

The example below shows the function assigned to the feedback_callback property of the license_key field. This function runs when the markup for the text field is being prepared on page display so the validation check can determine which icon is displayed next to the field.

/**
* Determine if the license key is valid so the appropriate icon can be displayed next to the field.
*
* @param string $value The current value of the license_key field.
* @param array $field The field properties.
*
* @return bool|null
*/
public function license_feedback( $value, $field ) {
if ( empty( $value ) ) {
return null;
}

// Send the remote request to check the license is valid
$license_data = $this->perform_edd_license_request( 'check_license', $value );

$valid = null;
if ( empty( $license_data ) || $license_data->license == 'invalid' ) {
$valid = false;
} elseif ( $license_data->license == 'valid' ) {
$valid = true;
}

return $valid;
}

Activating and Deactivating the License Key

The example below shows the function assigned to the validation_callback property of the license_key field. This function runs when the plugin settings are saved. It will deactivate the old license key if the posted value doesn』t match the value found in the existing settings. It will also activate the new license key.

/**
* Handle license key activation or deactivation.
*
* @param array $field The field properties.
* @param string $field_setting The submitted value of the license_key field.
*/
public function license_validation( $field, $field_setting ) {
$old_license = $this->get_plugin_setting( 'license_key' );

if ( $old_license && $field_setting != $old_license ) {
// Send the remote request to deactivate the old license
$this->perform_edd_license_request( 'deactivate_license', $old_license );
}

if ( ! empty( $field_setting ) ) {
// Send the remote request to activate the new license
$this->perform_edd_license_request( 'activate_license', $field_setting );
}
}

Perform the Remote Request

The following example shows the helper being used by the license_feedback() and license_validation() functions to send the license key validation, activation, and deactivation requests to your EDD store url.

/**
* Send a request to the EDD store url.
*
* @param string $edd_action The action to perform (check_license, activate_license, or deactivate_license).
* @param string $license The license key.
*
* @return object
*/
public function perform_edd_license_request( $edd_action, $license ) {
// Prepare the request arguments
$args = array(
'timeout' => 10,
'sslverify' => false,
'body' => array(
'edd_action' => $edd_action,
'license' => trim( $license ),
'item_name' => urlencode( GF_SIMPLE_ADDON_EDD_SL_ITEM_NAME ),
'url' => home_url(),
),
);

// Send the remote request
$response = wp_remote_post( GF_SIMPLE_ADDON_EDD_SL_STORE_URL, $args );

return json_decode( wp_remote_retrieve_body( $response ) );
}

Plugin Updates

Adding support for automatic updates is very simple. If you have read the EDD documentation on the subject you will know that the EDD Software Licensing plugin includes a sample plugin containing a file named EDD_SL_Plugin_Updater.php. You will want to include a copy of this file with your add-on.

Next, return to your add-ons root file and add the following to the end of the file.

add_action( 'init', 'gf_simple_addon_edd_plugin_updater', 0 );
function gf_simple_addon_edd_plugin_updater() {

if ( ! class_exists( 'EDD_SL_Plugin_Updater' ) ) {
// load our custom updater if it doesn't already exist
include( dirname( __FILE__ ) . '/EDD_SL_Plugin_Updater.php' );
}

// retrieve the license key
$license_key = trim( gf_simple_addon()->get_plugin_setting( 'license_key' ) );

// setup the updater
$edd_updater = new EDD_SL_Plugin_Updater( GF_SIMPLE_ADDON_EDD_SL_STORE_URL, __FILE__, array(
'version' => GF_SIMPLE_ADDON_VERSION,
'license' => $license_key,
'item_name' => GF_SIMPLE_ADDON_EDD_SL_ITEM_NAME,
'author' => 'John Doe'
)
);

}

That』s all there is to it! As long as the license key entered on the plugin settings page is valid and active, the add-on will have access to updates.

Important

The GFAddon class includes a protected variable named $_enable_rg_autoupgrade which is set to false.

The $_enable_rg_autoupgrade variable is not intended for use in third-party add-ons. It is only used by add-ons developed by Rocketgenius, Inc. to include the class-gf-auto-upgrade.php file which handles integrating the add-ons with our licensing and updates system.

All other add-ons should leave the $_enable_rg_autoupgrade variable set to false.

Dynamically Populating the Post Author

Registering a Function to a HookGetting and Returning the ValueUsing 『Admin Only』 FieldsConclusion

If you aren』t familiar with dynamic population with Gravity Forms, it is probably worth your while to take a quick breeze through the Using Dynamic Population walk-through.
This walk-through demonstrates how to retrieve the author』s email based on the post that the Gravity Form is being displayed.
Let』s jump right into the code!
add_filter( 'gform_field_value_author_email', 'populate_post_author_email' );
function populate_post_author_email( $value ) {
global $post;

$author_email = get_the_author_meta( 'email', $post->post_author );

return $author_email;
}

The first thing you would do with this code is copy and paste it into your theme』s functions.php file. Now let』s break it down line by line to get a better understanding of what is happening.
Registering a Function to a Hook
add_filter( 'gform_field_value_author_email', 'populate_post_author_email' );

With this line, we are registering a custom function populate_post_author_email to the gform_field_value_parameter_name filter. All this means is when Gravity Forms is rendering the form on a page it will call our custom populate_post_author_email function *and then* populate the value returned by our custom function into the field.
So how does Gravity Forms know which field to populate with the returned value? The dynamic population parameter! Note that you can apply the same parameter name to as many fields as you』d like and this code would populate them all.
Ready for the next bit of code?
Getting and Returning the Value
The next step is getting the value we want to populate into the field and then returning it so Gravity Forms can populate our field.
global $post;

$author_email = get_the_author_meta( 'email', $post->post_author );

return $author_email;

In this example, we want to get the author』s email based on the post that the Gravity Form is embedded in. To get access to all the juicy post details, we need to declare the $post object global. We can now access various properties of the current post.
One of those properties is the post_author which is the ID of the current post』s author. Why do we need this? To get the author』s email of course! We』ll pass the author』s ID and the author meta (aka 』email』) we are looking for to the WordPress get_the_author_meta function. This function will then return the… you guessed it, author email.
Now all we have to do is return the author』s email back to Gravity Forms which will automatically populate our field with the returned value.
Using 『Admin Only』 Fields
We』ve got our field populating with the post author』s email perfectly… but then you do your first test submission and realize that the author』s email is included in the {all_fields} token when the email notification is generated. You』d prefer that this field only be visible to the admin. What do you do?
You set the field』s visibility to Administrative and update the merge tag to {all_fields:noadmin}. This will prevent the field from displaying in the default notification emails. If the field has dynamic population enabled, this field will display as a hidden field when the form is displayed. If dynamic population is not enabled, the field will not display at all.
Conclusion
Let us know if you have any questions on this or suggestions to better explain this functionality.

Dynamically Populating Drop Down, Radio Buttons or Multi-Select Fields

IntroductionThird Party OptionsCustom Code ApproachThe CodeThe HooksCustom Filter FunctionLooping Through the FieldsGet the PostsCreating an Array of ChoicesAdd a Placeholder ChoiceWhat about Checkboxes?Conclusion

Introduction

Being able to dynamically populate the values in a select (aka drop down) field is fairly common requirement for product selection forms, product option forms, or any form that requires earlier submissions to drive choices in a latter collection field.

This walkthrough will teach you how to configure a specific example of this population, using custom code to present a list of existing posts as options in the drop down.

Third Party Options

If you are not keen on custom code, or require more complex capabilities, check for third party solutions across popular WordPress Plug-In repositories, and in our very own Community Add-On Library.

Make sure you don』t miss the Add-On Populate Anything, a fully-featured offering from one of our Certified Developers, GravityWiz.

Custom Code Approach

The premise for this walkthrough is that we want to populate the options in a Gravity Form select field with all of the posts currently published on the site. There are a variety of reasons for wanting to do this, but in this example, we just want to know what the user』s favorite post is.

IMPORTANT: For obvious reasons, dynamic population can』t run when the page where your form is embedded is cached. This is not a Gravity Forms limitation but a consequence of using caching.

The Code

123456789101112131415161718192021222324252627282930add_filter( 'gform_pre_render_51', 'populate_posts' );add_filter( 'gform_pre_validation_51', 'populate_posts' );add_filter( 'gform_pre_submission_filter_51', 'populate_posts' );add_filter( 'gform_admin_pre_render_51', 'populate_posts' );function populate_posts( $form ) {     foreach ( $form['fields'] as &$field ) {         if ( $field->type != 'select' || strpos( $field->cssClass, 'populate-posts' ) === false ) {            continue;        }         // you can add additional parameters here to alter the posts that are retrieved        // more info: http://codex.wordpress.org/Template_Tags/get_posts        $posts = get_posts( 'numberposts=-1&post_status=publish' );         $choices = array();         foreach ( $posts as $post ) {            $choices[] = array( 'text' => $post->post_title, 'value' => $post->post_title );        }         // update 'Select a Post' to whatever you'd like the instructive option to be        $field->placeholder = 'Select a Post';        $field->choices = $choices;     }     return $form;}

This code should be pasted in your theme』s functions.php file.

The Hooks

Using the gform_pre_render filter allows us to modify the form right before it is displayed. This is really useful, especially when you are looking to display content that will be constantly changing. In our case, this saves us the time and hassle of having to update our drop down of posts every time we add a new post. In addition you should use the gform_pre_validation, gform_pre_submission_filter and gform_admin_pre_render filters as well.

1234add_filter( 'gform_pre_render_51', 'populate_posts' );add_filter( 'gform_pre_validation_51', 'populate_posts' );add_filter( 'gform_pre_submission_filter_51', 'populate_posts' );add_filter( 'gform_admin_pre_render_51', 'populate_posts' );

This line tells Gravity Forms to filter the $form object through the populate_posts function every time the form with ID of 51 is displayed. You should update the 51 here to the ID of your form.

Please note: A form-specific version of the gform_pre_validation filter was added in Gravity Forms version 1.9.

Next, let』s create a populate_posts function to modify our form.

Custom Filter Function

In this example, our custom filter function is titled 「populate_posts」. Since we told Gravity Forms to call this function from the gform_pre_render filter, Gravity Forms will also send the $form object as a parameter to this function. This means we can modify the $form object with this function and then return our changes at the end of the function.

Looping Through the Fields

1foreach ( $form['fields'] as $field ) { ... }

Since we have the $form object, let』s loop through the fields in the form and find the field(s) that we』d like to modify.

123if ( $field->type != 'select' || strpos( $field->cssClass, 'populate-posts' ) === false ) {    continue;}

Given our premise, we only want to modify fields that are select (drop down) fields AND have a CSS class titled 「populate-posts」. We could check for the field ID instead of a CSS class; however, if we ever change our form we』d have to update the code to match the new field ID. Using a CSS class to identify our desired field allows us to manage which field should be targeted right from the Gravity Forms admin.

If the current field we are at in the loop is not a select OR does not have our designated CSS class, we simply skip that field and move on to the next.

Get the Posts

Now it』s time to get an array of all the posts to display in our drop down.

1$posts = get_posts( 'numberposts=-1' );

get_posts() is a WordPress function that returns an array of posts based on the parameters you provide it. For more information on how to modify which posts are returned, read here.

Quick Tip: You can retrieve any kind of post type here; even custom post types. Just pass the name of your post type with the 「post_type」 parameter:

1$posts = get_posts( 'post_type=event&numberposts=-1' );

Creating an Array of Choices

The way Gravity Forms handles fields with multiple options (such as a select field) is with a 「choices」 property for the field which contains an array of 「options」. Each option consists of:

a 「text」 property (which is what the user will see in the drop down)a 「value」 property (which is what will be recorded by Gravity Forms)an 「isSelected」 property (which is used to indicate whether the option is currently selected or not)and a 「price」 property (which only applies to pricing fields)

In our scenario, we are only concerned with the 「text」 and 「value」 properties.

1$choices = array();

The first thing we do is create an array to store all of our options.

123foreach ( $posts as $post ) {    $choices[] = array( 'text' => $post->post_title, 'value' => $post->post_title );}

Next, we』re going to loop through the posts we retrieved using the get_posts() function and create an option array for each post. For the 「text」 property we will use the Post Title and for the 「value」 property we will use the same. In some cases you may want to collect the ID of the selected post. If so you』d use $post->ID instead of $post->post_title; however, for our goal of recording the users favorite post, the post title is sufficient.

1$field->choices = $choices;

Once we』ve looped through all of the posts and created all of our options, we assign the $choices array (which has all of our new options) to the $field choices property.

Add a Placeholder Choice

1$field->placeholder = 'Select a Post';

We also want to make the first option in the drop down a 「placeholder」 choice. It let』s the user know what they are supposed to do with this drop down (ie 「Select a Post」). We do this by assigning the choice text to the fields placeholder property.

When the drop down is rendered on the form the placeholder choice will have an empty value for the 「value」 property. This ensures that if this is a required field, that the user must select an option other than the placeholder option. Failing to do so will generate a validation error.

What about Checkboxes?

Checkbox fields can also be dynamically populated, but they require additional handling since their structure is created by a fieldset of inputs and choices. See this example code for Dynamically Populating a Checkbox as included in our gform_pre_render documentation.

Conclusion

That』s all there is to it! When you view your form on the front end you should now see that your select field is populated with a list of all your current posts.

Dynamic Field Map Field

IntroductionParametersExampleValidationHelpersget_dynamic_field_map_fields()Uses

Introduction

The dynamic_field_map type field, part of the Settings API, allows the user to map their form fields to custom keys (fields), e.g. fields you will be sending to a third-party service such as a CRM.

Parameters

name string Required. Name of the field. Use it to retrieve saved data.label string Required. Field label. Will be displayed in the UItype string Required. Field type. Must be set to dynamic_field_map for the Dynamic Field Map field.tooltip string Optional. Defaults to blank (no tooltip). Displays a question mark icon and a tooltip next to the field label.field_types arrayOptional. Defaults to empty (no filtering). Array of form field types to be available as options when mapping to this field. Only form fields of the specified types will be included in the list of fields.Example: array( 『text』, 『name』 )exclude_field_types arrayOptional. Defaults to empty (no filtering). Array of form field types to be excluded when mapping to this field.Example: array( 『creditcard』 )field_map arrayOptional. Defaults to empty.By default, the Dynamic Field Map allows users to enter a custom key and map that key to a form field (using the associated form field drop down).The field_map property allows the Key field to be presented as a drop down list, where users can select from a set of predefined choices.Each item in the field_map array has the following propertieslabel stringRequired. Choice label to be displayed in the key drop down.value stringOptional. Defaults to the Label value. Value that will be saved.

choices arrayOptional. Defaults to empty.Creates an option group in the drop down. The label property becomes the Option Group label and the choices defined here become the options under the new group.Each item in the choices array has the following propertieslabel stringRequired. Choice label that is displayed in the drop down.value stringOptional. Defaults to the Label text. Value that is saved.limit int Optional. Defaults to no limit. Defines the number of fields that can be mapped by the user.enable_custom_key boolOptional. Defaults to false. Possible values are true or false. When set to true, allows users to enter a custom value in addition to the options in the drop down field.validation_callback (function)Optional. Defaults to nothing (no callback). Calls a function during validation allow for custom validation logic. The example in the existing documentation page is good.allow_duplicate boolOptional. Defaults to false. Controls whether or not the same option in the key field can be mapped multiple times.Note: This only prevents options from being selected multiple times in the drop down. If custom keys are enabled, users won』t be prevented from typing the same custom option multiple times.

Example

The following example shows how you can allow the user to define a number of custom keys and map them to their form fields, which in this case is limited to twenty. We are also excluding the creditcard field from the drop downs which contain the form fields as choices.

array(
'title' => esc_html__( 'This is the title for Section 1', 'sometextdomain' ),
'fields' => array(
array(
'name' => 'metaData',
'label' => esc_html__( 'Metadata', 'sometextdomain' ),
'type' => 'dynamic_field_map',
'limit' => 20,
'exclude_field_types' => 'creditcard',
'tooltip' => '

' . esc_html__( 'Metadata', 'sometextdomain' ) . '

' . esc_html__( 'You may send custom meta information to [...]. A maximum of 20 custom keys may be sent. The key name must be 40 characters or less, and the mapped data will be truncated to 500 characters per requirements by [...]. ', 'sometextdomain' ),
'validation_callback' => array( $this, 'validate_custom_meta' ),
),
),
),

The above code would render a field like the following:

Validation

In the above example a validation callback is also specified to ensure that the limit is not exceeded and that the custom keys don』t exceed the character limit defined by the third-party service.

public function validate_custom_meta( $field ) {
//Number of keys is limited to 20 - interface should control this, validating just in case
//key names can only be max of 40 characters

$settings = $this->get_posted_settings();
$metaData = $settings['metaData'];

if ( empty( $metaData ) ) {
return;
}

//check the number of items in metadata array
$metaCount = count( $metaData );
if ( $metaCount > 20 ) {
$this->set_field_error( array( esc_html__( 'You may only have 20 custom keys.' ), 'sometextdomain' ) );

return;
}

//loop through metaData and check the key name length (custom_key)
foreach ( $metaData as $meta ) {
if ( empty( $meta['custom_key'] ) && ! empty( $meta['value'] ) ) {
$this->set_field_error( array( 'name' => 'metaData' ), esc_html__( "A field has been mapped to a custom key without a name. Please enter a name for the custom key, remove the metadata item, or return the corresponding drop down to 'Select a Field'.", 'sometextdomain' ) );
break;
} elseif ( strlen( $meta['custom_key'] ) > 40 ) {
$this->set_field_error( array( 'name' => 'metaData' ), sprintf( esc_html__( 'The name of custom key %s is too long. Please shorten this to 40 characters or less.', 'sometextdomain' ), $meta['custom_key'] ) );
break;
}
}
}

Helpers

The following functions may come in helpful when interacting with the dynamic_field_map field type during feed processing.

get_dynamic_field_map_fields()

Retrieves the individual field_map fields from the meta property of the Feed Object for the supplied field name.

$metaData = $this->get_dynamic_field_map_fields( $feed, 'metaData' );

$feed Feed Object
The Entry Object to be checked.

$name string
The name property of the dynamic_field_map field to retrieve the mapped fields for.

Returns array
An array containing the field names or custom keys as the keys to the mapped form field ID or entry meta key.

Uses

settings_dynamic_field_map()

Dropbox Upload Field

IntroductionNotesGeneralAppearanceAdvancedMore Information

Introduction
The Dropbox Upload field uses the Dropbox JavaScript Chooser API to allow your users to select files from their Dropbox account. When the form is submitted, the field value will contain the Dropbox preview links for the selected files.
During submission, if your form also has a Dropbox feed, then the feed processor loops through all selected Dropbox Upload fields for the form and sends a copy request to Dropbox to move the selected files to the Dropbox folder chosen in the feed settings. Once the copy requests are complete, the Gravity Forms entry is updated with the new Dropbox links and notifications are sent out.

Notes
The Dropbox Upload field is only available when you have configured the add-on to use a custom app. See the Creating A Custom Dropbox App article for more details.
If the account the file is being uploaded from is the same as the account is being uploaded to, the Dropbox share link will be to the original file location. Same account includes:

Uploading from a personal account to the same personal account
Uploading from a personal account to a business account that is linked to the personal account
Uploading from a business account to a personal account that is linked to the business account

General

Field Label
Enter the label of the form field. This is the field title the user will see when filling out the form.

Description
Enter the description for the form field. This will be displayed to the user and provide some direction on how the field should be filled out or selected.

Allow multiple files to be selected
This option allows the user to upload multiple files.

Allowed file extensions
Enter the allowed file extensions for file uploads. This will limit what type of files a user may upload.

Rules
These properties set rules for how the data should be handled.

Required
A required field will prevent the form from being submitted if it is not filled out or selected.

Appearance

Field Label Visibility
Select the label visibility for this field. Labels can either inherit the form setting or be hidden.

Description Placement
Determines where, in relation to the field, the labels will be placed. The labels can be placed either above or below the Dropbox Chooser button.

Custom Validation Message
This allows you to set a custom message that will be displayed in the event that there is an error in the submission.

Custom CSS Class
Allows you to define a custom style for these fields to override the defaults.

Advanced

Admin Field Label
Enter the admin label of the form field. Entering a value in this field will override the Field Label when displayed in the Gravity Forms administration tool.

Visibility
Select the visibility for this field. Field visibility set to Everyone will be visible by the user submitting the form. Form field visibility set to Admin Only will only be visible when editing the entry on the entry detail page.

Enable Conditional Logic
Create rules to dynamically display or hide this field based on values from another field. Remember, to use conditional logic, you will need to create a dropdown, checkbox or multiple choice field.

More Information
See the GF_Field_Dropbox article for more details about this field type.

Dropbox Feed Meta

IntroductionUsageProperties

Introduction
The Feed Object meta for the Dropbox add-on is an associative array containing the properties which determine how the add-on should process the form submission.
$feed['meta'] = array(
'feedName' => 'Dropbox Feed 1',
'fileUploadField' => 'all',
'destinationFolder' => '/local.wordpress.dev',
'feed_condition_conditional_logic' => true,
'feed_condition_conditional_logic_object' => array(
'conditionalLogic' => array(),
),
);

Usage
We recommend accessing the $feed meta using the rgar() or rgars() functions, e.g.:
$conditional_logic_enabled = rgars( $feed, 'meta/feed_condition_conditional_logic' );

Properties

feedName string
The feed name which appears on the add-ons feeds tab.

fileUploadField string
The ID of the field containing the files to be uploaded to Dropbox or 『all』 to upload files from all relevant fields.

destinationFolder string
The folder in the Dropbox account where the files will be stored.

feed_condition_conditional_logic boolean
Is the feed condition (conditional logic) setting enabled. Default is false.

feed_condition_conditional_logic_object array
An associative array containing the conditional logic rules. See the Conditional Logic Object for more details.

Dropbox Change Log

3.0.13.0 | 2021-09-022.9 | 2021-05-062.8 | 2020-09-242.7 | 2020-07-132.6 | 2020-04-012.5 | 2019-11-132.4 | 2019-07-242.3 | 2019-03-292.2 | 2019-02-122.1 | 2018-03-212.0 | 2017-06-161.3 | 2017-03-151.2 | 2016-03-311.1 | 2015-11-021.0 | 2015-08-13

3.0.1

Added the gform_dropbox_should_upload_file filter.
Updated the minimum Gravity Forms version to 2.0.8.
Fixed an issue where the upload is attempted again for existing files, if the feed is reprocessed by other add-ons.
Fixed an issue where files with names that include Chinese characters aren't sent to Dropbox when uploaded via a multi-file enabled File Upload field.

3.0 | 2021-09-02

Added support for OAuth refresh tokens in accordance with changes to the Dropbox API.
Fixed the ability of custom apps with team permissions to authenticate.
Fixed an issue where it is not possible to disconnect a custom app if using an access token that has already been deauthorized.
Fixed the folder display so it is possible to select team folders when using a custom app with team permissions.
Fixed an issue where an empty space appears under the connect to dropbox button on the settings page.
Updated the user interface on the Dropbox settings page.
Updated the user interface of the authorization screen.

2.9 | 2021-05-06

Added accessibility enhancements to the Dropbox upload field.
Fixed styling of the Dropbox Upload field description to correctly display above or below the input in the editor in Gravity Forms 2.5.
Fixed an issue where authentication may not complete after attempting a connection with Dropbox.

2.8 | 2020-09-24

Updated support for Gravity Forms 2.5.

2.7 | 2020-07-13

Added security enhancements.
Added support for Gravity Forms 2.5.

2.6 | 2020-04-01

Added translations for Hebrew, Hindi, Japanese, and Turkish.
Updated a few labels on the settings page related to connecting and disconnecting the add-on with Dropbox.
Updated Gravity API domain.
Fixed an issue where the Dropbox Upload field can pass the required validation if a file is uploaded and then removed.

2.5 | 2019-11-13

Updated Javascript files, stylesheets to use minified versions.
Fixed an issue with files uploaded to Dropbox not attaching to notifications.
Fixed feed processing background request not registering in certain scenarios.
Fixed an issue in notifications with multiple Dropbox feeds tied to different file upload fields sometimes returning bad file URLs.
Fixed PHP warning caused by logging statement during feed processing.

2.4 | 2019-07-24

Added security enhancements.
Fixed Dropbox Upload field utilizing deprecated jQuery.live() function.
Updated Dropbox API requests to use WordPress requests API.

2.3 | 2019-03-29

Updated authentication process to create new folder for authenticated site.
Updated feed processing to not utilize WP_CONTENT_DIR and WP_CONTENT_URL.
Updated Dropbox PHP SDK.

2.2 | 2019-02-12

Fixed folder tree not defaulting to currently selected folder on initial load of feed settings page.
Fixed file selected in Dropbox Upload field not being saved when hidden input contains invalid JSON string.
Fixed shareable link not being returned if link already exists for file.
Removed deprecated logic events for Gravity Forms 2.4.
Restore link type and multiselect field settings.

2.1 | 2018-03-21

Added security enhancements.
Added gform_dropbox_shareable_link_settings filter to modify settings when generating a shareable Dropbox link.
Added GPL to plugin header.
Fixed Dropbox PHP SDK not being included in the 2.0.1 build.
Fixed the file extensions list used to initialize the Dropbox Chooser.
Updated Plugin URI and Auth or URI to use https.
Updated included version of Dropbox PHP SDK.

2.0 | 2017-06-16

Added minimum requirements needed to use Dropbox Add-On.
Updated Dropbox API calls to use latest version of Dropbox API.
Updated Dropbox authentication process.
Updated background feed processing request to not verify SSL by default.

1.3 | 2017-03-15

Fixed an issue with the Dropbox Upload field value on the entry list page.
Fixed an issue with the processing of the File Upload field.
Fixed PHP warning which could occur during validation of the Dropbox Upload field if no files were chosen.
Fixed an issue with notifications for events other than form_submission not being processed after the last feed is processed.
Fixed CSRF token error when authorizing with Dropbox.
Fixed file extension validation for Dropbox Upload form field.
Updated strings for translations.
Updated installation instructions to show only domain for Chooser/Saver domain.

1.2 | 2016-03-31

Added feed duplication support.
Added gform_dropbox_post_upload action that fires after a feed has been processed.
Added gform_dropbox_ssl_compatibility filter to override SSL compatibility test.
Fixed a fatal error which could occur if the request used to validate the app secret key fails.
Fixed a redirect loop issue when processing Dropbox feeds.
Fixed default label for Dropbox Upload field.
Fixed PHP fatal error when initializing API.
Fixed Update Settings button being hidden on plugin settings pages.
Modify execution order of gform_dropbox_post_upload.
Updated plugin compatibility check to verify existence of openssl_random_pseudo_bytes and mcrypt_create_iv functions.
Updated SSL compatibility check to allow for 404 response codes.

1.1 | 2015-11-02

Added error message for versions of PHP that do not support 64-bit integers.
Added some additional logging statements.
Added SSL compatibility check to prevent plugin from running when SSL is not available.
Fixed Dropbox PHP SDK autoloader from being included when if autoloader class already exists.
Fixed Dropbox Upload field being included if custom app key and secret were not provided.
Fixed files uploaded through the Dropbox Upload field not uploading to remote Dropbox.
Removed debugging output from plugin settings page.
Updated plugin settings with a more streamlined install process.
Updated save URL functions to use WordPress API functions.

1.0 | 2015-08-13

It』s all new!