Gravity Forms 文档

Configuring Subscriptions in PayPal Checkout

IntroductionConfigurationSetup FeeTrialEntry DetailsNotifications

Introduction

PayPal Subscriptions allow you to create recurring payments according to a flexible schedule. Subscription support was added in version 2.0 of the official Gravity Forms PayPal Checkout Add-On (previously named 「PayPal Commerce Platform Add-On」).

Note: If you get a notice indicating that credit cards are not supported for subscriptions and will not display on the form itself, you will need to adjust the field settings. This field is not supported in all markets and accounts by PayPal. You can uncheck the Credit Card option under Supported Payment Methods in the PayPal Field settings to disable this notice.

Configuration

Before continuing, note that if your form uses AJAX submission, you need to turn it off. PayPal Checkout subscriptions are not compatible with AJAX submission.

For your PayPal compatible form, choose Form → Settings → PayPal Checkout. Create new, or edit an existing feed.

Change the Transaction Type to Subscription This will load the Subscription Settings options

Select the Recurring Amount. This can be either a specific product field from your form, or the Form Total to use the total of all pricing fields as the recurring amount.Subscription Product Type: Indicate the type of product that this subscription is for, either Digital, Physical or ServiceBilling Cycle: The billing cycle determines how often the recurring payment should occur. You can choose a numeric interval of days, weeks, months or years.Recurring Retry: Select this option to retry the charge again after a failed attempt.Recurring Times: Select how many times the recurring payment should be made. The default is to bill the customer until the subscription is canceled.

Setup Fee

You can either enable a Setup Fee or a Trial Fee. Click Enabled to enable and you can choose a product field from your form to be used as the setup fee.

Trial

Use the Trial to establish a trial period for your subscription. You can either enable a Setup Fee or a Trial Fee. Click Enabled to enable the Trial Fee and you』ll be given additional options to complete.1. Select a Trial Price: You can select either a Free Trial, enter an amount for the trial price or choose from the product field from your form as the trial price.1. Configure the Trial Period: This is the duration for the trial subscription until the regular price is charged. You can choose a numeric interval of days, weeks, months or years.

Entry Details

The entry detail screen will show Subscription Details box including status, start date, subscription ID, and recurring amount.

Notifications

You can set up notifications for the subscription related events of:

– Subscription payment completion– Subscription payment failure– Subscription cancellation– Subscription expiration

Each of these events can initiate a notification that you can configure normally.

Configuring Authorize and Capture in PayPal Checkout

IntroductionConfigurationPayment Details for AuthorizationsRelated Notifications

Introduction
This feature of the official Gravity Forms PayPal Checkout Add-On allows PayPal to authorize the payment on a customer』s card at entry, but to not capture that payment (that is, collect the charge) until you choose, such as upon successful shipping of an order.
See this document from PayPal for more information.
Configuration
For your PayPal compatible form, choose Form → Settings → PayPal Checkout. Create new, or edit an existing feed.

Ensure Transaction Type is set to Products & Services.

Select the payment amount. This can be either a specific product field from your form, or the Form Total.

Enable the Authorize only option under Products & Services Settings and save your changes.

Payment Details for Authorizations
The entry detail screen for a payment entry will show a Payment Details section. When using authorization & capture, the entry will initially show a Status: Authorized along with transaction ID, amount, and a button that will allow you to Capture Payment.

Upon capturing the payment, the notes section is updated to indicate a successful capture and the Payment Details section updates to Status: Paid along with date, transaction ID, amount and a button allowing you to Refund Payment.
Related Notifications
Notifications can be configured to fire on the event of Authorization Voided. Refer to this PayPal document for more information on voiding an authorization.

Conditional Shortcode

IntroductionUsageExamplesShow content if a certain checkbox was checkedShow content if a certain field is not emptyShow content based on the price for a product field set to Radio Buttons type.

Introduction
The conditional shortcode allows you to perform conditional logic in the message content of your Admin and User Notification emails as well as the Confirmation Message that is displayed when a form is submitted.
The conditional shortcode consists of an opening and closing shortcode. Any text or content contained within the opening and closing conditional shortcode will be the content that is conditionally displayed.

Please note: Nested conditional shortcodes are not supported at this time.

Usage
[gravityforms action="conditional" merge_tag="{Number:1}" condition="greater_than" value="3"]
Content you would like to conditionally display.
[/gravityforms]

action
The action you would like to perform. This must be set to conditional as in the example above. (required)
merge_tag
The form merge tag who』s value you are executing the conditional logic for. You can get the correct merge tag for the form data you would like to use using the insert merge tag drop down. (required)
condition
The type of condition used to determine success. Available conditions are: is, isnot, greater_than, less_than, contains, starts_with, ends_with. (required)
value
The value that the condition must equal in order for the condition to be met and the content displayed. (required)

Examples
Show content if a certain checkbox was checked
In this case we use the :value modifier to ensure we』re checking the value (that can be different from the label). And we』re using the 「contains」 condition instead of 「is」 because the value for a checkboxes field can contain different choices separated by a comma.
[gravityforms action="conditional" merge_tag="{Checkboxes:1:value}" condition="contains" value="10"]
This content would be displayed if the value of field id 1 has a 10.
[/gravityforms]

Show content if a certain field is not empty
In this example, we want to show our content only if a Text field with id 5 is not empty.
[gravityforms action="conditional" merge_tag="{Text:5}" condition="isnot" value=""]
This content would be displayed if a value exists for field id 5.
[/gravityforms]

Show content based on the price for a product field set to Radio Buttons type.
In this example, we want to show our content only if the choice selected has a price of 3. Note the use of the :price merge tag modifier, and the lack of the currency symbol for the value.
[gravityforms action="conditional" merge_tag="{Radio Product:5:price}" condition="is" value="3"]
This content would be displayed if the choice selected has a price of 3.
[/gravityforms]

Conditional Logic Object

IntroductionUsagePropertiesRule Properties

Introduction

Conditional Logic, when applied to the form or page button or to any field, controls the visibility of that element based on a choice selected or value entered by the user in other fields on the form. It can also be used to determine if a notification, confirmation or add-on feed should be used.

12345678910111213array(    'conditionalLogic' => array(        'actionType' => 'show',        'logicType'  => 'all',        'rules'      => array(            array(                'fieldId'  => 2,                'operator' => 'is',                'value'    => 'Second Choice',            ),        )    ),);

Usage

12345678// returns the conditional logic rules for the form button$rules = rgars( $form, 'button/conditionalLogic/rules' ); // returns the conditional logic rules for the field$rules = rgar( $field->conditionalLogic, 'rules' ); // returns the conditional logic rules for the feed$rules = rgars( $feed, 'meta/feed_condition_conditional_logic_object/conditionalLogic/rules' );

Properties

actionType stringThe type of action the conditional logic will perform. Possible values: show, hide

show: Displays the field when the rules match and hides the field when the rules do not match
hide: Hides the field when the rules match and displays the field when the rules match

logicType stringDetermines how to the rules should be evaluated. Possible values: any, all

any: Evaluates the conditional logic to true if any of the rules match. More specifically, will OR the rules together (i.e. rule1 || rule2 || rule3)
all: Evaluates the conditional logic to true if all rules match. More specifically, will AND the rules together (i.e. rule1 && rule2 && rule3)

rules arrayAn associative array containing the conditional logic rules. See below for the individual rule properties.

Rule Properties

fieldId integer
Target field Id. Field that will have it』s value compared with the value property to determine if this rule is a match

operator string
Operator to be used when evaluating this rule. Possible values: is, isnot, >, <, contains, starts_with, or ends_with is: Evaluates this rule to true when the value property is equal to the value of field specified by fieldId. isnot: Evaluates this rule to true when the value property is not equal to the value of field specified by fieldId. value stringThe value to compare with field specified by fieldId

Nested Conditional Logic Limitations

DisclaimerWhen will nested conditional logic work?When will nested conditional logic not work?WorkaroundsBulletproof MethodDrop Down PlaceholdersFinding nested conditional Logic

Disclaimer

Gravity Forms does not officially support nested conditional logic. This means a field should not have conditional logic based on a field that also has conditional logic. Some clever folks have come up with workarounds or specific scenarios they feel work, but these are not officially supported by us.

With that in mind, here is some info that may or may not be of use!

When will nested conditional logic work?

Nested conditional logic will work if the conditional field does not have a default value, is not dynamically populated, and, if the field is a Drop Down, it uses a placeholder.

When will nested conditional logic not work?

Nested conditional logic will not work if:– the conditional field has a default value– the conditional field is dynamically populated– if the conditional field is a Drop Down and does not use a placeholder.

When Gravity Forms hides a field via conditional logic, it resets the field』s initial value. Conditional logic dependent on this field will be evaluated with that reset value rather than an empty value which is unexpected.

Workarounds

Bulletproof Method

The best method to support nested conditional logic is to add additional conditions to account for the nested dependency.

For example:

Field B is conditionally dependent upon Field Ayou want Field C to be conditionally dependent upon Field B

In this case, you would set up Field C』s dependence on B, but also add the conditions that you configured for Field B onto Field C as well. In this was you make Field C explicitly dependent on both Field B and Field A.

Conditional logic as configured for Field B

Conditional logic as configured for field C, in order to enforce the nested dependency.

Drop Down Placeholders

Nested conditional logic issues are most commonly exposed by Drop Downs. If the Drop Down does not have a choice with an empty value (such as a placeholder), the Drop Down』s value will be reset to that of the Drop Down』s first option when the field is hidden via conditional logic. Since the field is hidden, many users expect the value of the field to be empty and create nested conditional logic rules based on this assumption.

The simplest solution is to make sure your Drop Down has a placeholder. In this way, the Drop Down value will be reset to an empty value (via the placeholder) when hidden via conditional logic. Note: This does not address the issues with setting a default value and dynamic population mentioned above.

Finding nested conditional Logic

To check if your form has any nested conditional logic, copy and paste this script into your browser』s console on the form editor page.

123456789101112131415161718192021222324252627282930var deps = {}; for( var i = 0; i < form.fields.length; i++ ) {   var field = form.fields[i];  if( ! field.conditionalLogic ) { continue; }   if( typeof deps[ field.id ] === 'undefined' ) { deps[ field.id ] = []; }   for( var j = 0; j < field.conditionalLogic.rules.length; j++ ) {    var rule = field.conditionalLogic.rules[j];    if( jQuery.inArray( rule.fieldId, deps[ field.id ] ) === -1 ) {      deps[ field.id ].push( rule.fieldId );    }  } } for( var fieldId in deps ) {   if( ! deps.hasOwnProperty( fieldId ) ) { continue; }   for( i = 0; i < deps[ fieldId ].length; i++ ) {    var depFieldId = deps[ fieldId ][i]; // Does current dependent field have any dependencies?    if( typeof deps[ depFieldId ] !== 'undefined' ) {      console.log( 'Nested dependency found', '|', 'ID:', fieldId, '|', 'Label:', GetFieldById( fieldId ).label );    }  } } It will output a message for each dependency found. Nested dependency found | ID: 3 | Label: Field C

Conditional Logic in Gravity Forms Confirmations

IntroductionRequirementUsage NotesHow To Setup A Conditional Confirmation

Introduction

Sometimes you may want to send a user to a different page or display different information to them based on what they submit within the form. In this article, we will show you how to use conditional logic within your form confirmation options you can display information to users that is dependent on their selections within the form submission.

Requirement

This article assumes that you have already created your form, as well as created an additional confirmation message.

Usage Notes

A default confirmation is established automatically at the creation of every new form.Conditional logic is only available in confirmations you create, and is not available for the default confirmation.The default confirmation cannot be turned off. This is intended to always ensure one confirmation can execute. The default confirmation will execute only if no other confirmation is executed.If a form submission would trigger multiple active conditional confirmations, then only the first one will be executed.

How To Setup A Conditional Confirmation

Within your form confirmations page, at the bottom, you should notice a heading labeled Conditional Logic.The first field you will see is a dropdown in which you can switch between All and Any. Setting this to All will require all rules to match before the confirmation is executed. Conversely, setting it to Any will only require one of the rules to match.Below this, you will see another set of fields. The first field will list the form field name, the second field is the comparison operator, and the third field is the value. For example, if you wanted to show a different confirmation for users that selected a particular radio button, you would select the field that contains the radio buttons, then is, and finally the individual radio button option that you want to base the confirmation on. In this scenario, users will receive the custom confirmation only if the particular radio button First Choice is selected.If you want to add additional conditions, simply press, the 「+」 button to the right of your first condition.

Common Form Issues

Why is 『display:none』 being added and my form isn』t showing up?Why do I see paragraph tags or line breaks after each element in my form?Why do I have extra space above and below my form?

Why is 『display:none』 being added and my form isn』t showing up?
This is because you have conditional logic being used on your form. Anytime conditional logic is present the entire form is set to display: none; and then JavaScript is used to only show the fields that should be shown.
However, this requires Gravity Forms being able to output the necessary JavaScript using the WordPress built in enqueue function which outputs the JavaScript in your footer.
This is due to one of two likely issues:
1.) Your theme probably does not have this function call in your theme』s footer.php file:

This function call, which all themes should have, but many people forget to include, enables plugins to output code in the footer of a theme dynamically. If it isn』t present, the theme can』t output the necessary code.
2.) Your theme has a JavaScript error or conflict causing Gravity Forms』 JavaScript not to function correctly. Please go through the theme and plugin conflict testing steps to isolate the issue.
Between these two important pieces of information, you』ll likely find the source of why your form is not displaying properly.
Why do I see paragraph tags or line breaks after each element in my form?
You』ll see these when another plugin or theme causes them. They aren』t added by Gravity Forms. To fix it, you』ll want to go through our theme and plugin conflict testing
Why do I have extra space above and below my form?
Usually this happens when you copy the form shortcode directly from the help page and paste it into the visual editor. Often it pastes the tags in the markup which then causes the formatting issues.Edit the page the form resides on, view the content in the editor using the HTML tab and if you see the tags around your form shortcode, simply remove them.
Complete information on embedding forms can be found in the documentation by clicking the link below:
https://docs.gravityforms.com/embedding-a-form/

Common Field Settings

SummaryGeneral Settings SectionField LabelDescriptionInput MaskMaximum CharactersRequiredNo DuplicatesAppearance Settings SectionPlaceholderField Label VisibilityDescription PlacementCustom Validation MessageCustom CSS ClassField SizeAdvanced Settings SectionAdmin Field LabelDefault ValueEnable AutocompleteEnable Password InputVisibilityAllow field to be populated dynamicallyConditional Logic Fly-outScreenshots

Summary

When editing a form, many of the fields you use will offer the same group of settings. This article helps explain the most common ones. If the setting you are interested in is not listed here, then refer to the more specific user guide documentation for the Field Type you are using.

Fields usually offer three Field Settings sections available in the right hand sidebar when a field is selected:

GeneralAppearanceAdvanced

Additionally, it is common for fields to also present a conditional logic fly-out in the right hand sidebar.

The settings most commonly offered in each of these sections are listed below.

General Settings Section

See screenshots below.

Field Label

This is the name by which this field is displayed. The field label is shown on the front-end (that is, displayed to people when they fill out a form you have embedded on your site), as well as used to refer to that field within form administration areas where choosing the field is required. Such as for conditional logic, merge fields, or even in the Entries list.

Description

An extended text area used to annotate the purpose or instructions on filling this field. If included, it will be displayed with the form.

Input Mask

Available for Single Line Text fields and Post Custom fields only. When this setting is toggled to on, the form administrator may specify a specific format to be accepted in this field, choosing from standard masks provided or defining a custom one. The field will then provide visual guidance to form users on the expected format, as well as enforce the input format during entry validation.

See this article for more information on input masks.

Maximum Characters

Determines the maximum number of characters that can be entered in this field. Offered for longer fields such as the Paragraph field.

Required

If a field is marked as required, then the form cannot be submitted without it.

No Duplicates

Select this option to limit user input to unique values only. This means that for a form submission to be accepted, the value entered must not already exist in the form entry database for that field.

Appearance Settings Section

See screenshots below.

Placeholder

A placeholder is text shown inside the blank field to help the user know what is expected. If the field is left blank at submission time, the placeholder text is not saved with the entry. That field will be blank in the Entry table.

Field Label Visibility

Choose from the drop down to determine if you want the field label to be shown on the form. If shown, the placement of the label is inherited from whatever you have specified within the Form Settings.

Note: hiding the field label can make it more difficult for users to fill out your form. As visible field labels improve accessibility, a warning is displayed when you activate this setting to hide. See this accessibility article for more details.

Description Placement

Choose where you would like the description to appear, own relation to the input field.

Custom Validation Message

This is a custom message that displays when an attempted entry fails validation for this field. The message appears in red, below the field upon an invalid submission. Note that all fields that are validated will generate a simple, default error message. Use this setting if you wish to customize it.

Example of a custom validation message.

Custom CSS Class

Add any custom CSS class you have defined if you wish to apply it to this field and override the default style.

Field Size

The choice of small, medium or large affects the width of the entry area for most fields. For a paragraph field, it affects the height. By default, it is large.

Advanced Settings Section

See screenshots below.

Admin Field Label

This is the field label that will be shown within the administrative interfaces. It does not affect what a form visitor would see.

Default Value

The value will be used to pre-populate the field when initially loaded and presented to visitor. If unchanged during form submission, it will also be saved with the Entry. A merge tags marker is also presented next to this field, meaning that merge tags can also be utilized to determine the default value.

Enable Autocomplete

Select this setting to let browsers help a user fill in a field with autocomplete. You can enter a single autocomplete attribute or multiple attributes separated with a space. Learn more about autocomplete in the accessibility documentation .

Enable Password Input

Toggling this setting on means that the text typed in this form field will be hidden to the user with a default 「•」 character.

Visibility

Controls whether or not the field will be visible to a form viewer. Options include:

Visible: default option, field shows normally.Hidden: this field will be hidden from a form viewer, but will still exist. This is useful when you need the field to execute or be used in some functionality (such as capturing a piece of capture information, or be utilized in conditional logic elsewhere in the form), but do not want the form viewer to put an input here.Administrative: the field is not visible to a form viewer and will not add any functionality to the form. It can still affect an entry though in that default values will be captured in the Entry table.

Allow field to be populated dynamically

Checking this option allows data to be passed to the form and pre-populate the field dynamically. Data can be passed via Query Strings, Shortcode, Block Settings, and/or Hooks. See this article for more information.

Conditional Logic Fly-out

Open the conditional logic fly-out and click the toggle Enable Conditional Logic to turn on conditional logic. The logic rules added here will control whether this field is shown or hidden. If disabled, this field will be shown by default. See this article for more information. This fly-out will only be available when fields that support conditional logic exist on the form.

Screenshots

General SectionAppearance SectionAdvanced Section

CleverReach Feed Meta

IntroductionUsagePropertiesCustom Field Properties

Introduction
The Feed Object meta for the CleverReach add-on is an associative array containing the properties which determine how the add-on should process the form submission.
12345678$feed['meta'] = array(    'feed_name'                               => 'Your Feed Name',    'email'                                   => '2',    '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.:
1$conditional_logic_enabled = rgars( $feed, 'meta/feed_condition_conditional_logic' );

Properties

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

group string
The CleverReach Group ID this feed will add the contacts to.

email string
The ID of the form field containing the user』s email.

custom_fields array
A multidimensional array containing the CleverReach custom fields. See Custom Field Properties.

double_optin_form string
The ID of the CleverReach form which will be used when exporting to CleverReach to send the opt-in email.

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.

Custom Field Properties
1234array(    'key'   => 'first_name',    'value' => '1.3',)
Each custom field is an associative array containing the following properties:

key string
The CleverReach custom field name. Lowercase and spaces replaced with underscores.

value string
The ID of the form field or entry meta item containing the value for this custom field.

CleverReach Change Log

1.7 | 2020-09-081.6 | 2020-03-121.5 | 2019-02-191.4 | 2018-04-021.3 | 2017-05-161.2 | 2016-07-291.1 | 2015-06-021.0 | 2015-05-19

1.7 | 2020-09-08

Added support for Gravity Forms 2.5.
Fixed a PHP warning which occurs when accessing an existing feed after the add-on is connected to a different CleverReach account.

1.6 | 2020-03-12

Added translations for Hebrew, Hindi, Japanese, and Turkish.
Fixed a PHP 7.4 notice which occurs on the feed configuration page when saving a new feed.
Fixed an issue with the double opt-in email not being sent if the personal data settings for a form are set to prevent storage of user IP addresses.
Fixed a PHP warning which could occur during form submission.

1.5 | 2019-02-19

Updated Add-On to use CleverReach REST API.

1.4 | 2018-04-02

Added security enhancements.
Added Double Opt-In support when updating contact.
Added License GPL to plugin header.
Updated Plugin URI and Author URI to https.
Fixed a PHP warning which could occur during feed processing if Double Opt-In was enabled.
Fixed fatal errors which could occur when getting the choices for the Group and Double Opt-In settings.
Fixed a PHP warning which occurred when the CleverReach API did not return the requested group details.

1.3 | 2017-05-16

Updated warning message when SOAP extension is not present.
Fixed strings for translations.
Fixed fatal error which could occur when initiating the CleverReach API.
Fixed PHP notice.

1.2 | 2016-07-29

Added feed duplication support.
Added gf_cleverreach() for easily getting a CleverReach instance.
Added support for delaying feed processing until payment by PayPal Standard is successfully completed.

1.1 | 2015-06-02

Added Double Opt-In support.
Added Spanish (es_ES) translation.

1.0 | 2015-05-19

It's all new!