Author 诗语

Email

SummaryCommon SettingsGeneral SettingsMerge TagsUsageModifiers

Summary

The Email field allows you to present a field that captures email data. It is available under the Advanced Fields section within the form editor.

Email field as displayed in the Field Library

Email field as displayed in the Form Editor.

Common Settings

This field uses only common field settings for the Appearance and Advanced settings. For a description of each of the common field settings, refer to this article. Below you will find description of specialty settings that are particular to this field.

General Settings

SettingDescriptionEnable Email ConfirmationPrompts the user to confirm the email address.

Merge Tags

For more information on the use of merge tags, refer to these articles.

Usage

{Field Name:2}

Modifiers

This merge tag does not have any modifiers.

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.

Enabling Conditional Logic for Confirmations

SummaryConfirmations SettingsExample

Summary

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. Here we will show you how to use conditional logic within your form confirmation messages.

Confirmations Settings

You will need to create a new confirmation as conditional logic is only available in additional confirmations.

Note: The Default Confirmation doesn』t have support for logic. This is intended as the form always needs to process one confirmation. The Default Confirmation will be used if the logic failed in additional confirmations.

Go to the Confirmations settings page of the form.

Here you can determine the criteria for sending the Confirmation.

Example

In this example we are using conditional logic to determine which confirmation the user should see based on their answer to the question 「Do you own a pet?」.

First we create a form with a field containing the question 「Do you own a pet?」.

Then we create a new confirmation for the people who answer yes.

Then we set the conditional logic accordingly. We set the condition to 「Do you own a pet?」 is 「Yes」.

The users who answer no will receive the default confirmation.

EmailOctopus Change Log

1.2 | 2020-09-081.1 | 2020-03-161.0 | 2020-01-15

1.2 | 2020-09-08

Added support for Gravity Forms 2.5.

1.1 | 2020-03-16

Added translation files
Fixed a PHP notice and warning which occur when editing an existing feed when the add-on is connected to a different EmailOctopus account.

1.0 | 2020-01-15

It's all new!

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.

Enabling Conditional Logic for Notifications

SummaryNotifications SettingsExample

Summary

Conditional logic can be used with Notifications to determine which notification is sent to the user based on the data they input into the form.

Notifications Settings

Go to the Notifications settings page of the form to enable conditional logic.

Here you can determine the criteria for sending the Notification.

Example

In this example we are using conditional logic to determine which notification should be sent to the user based on their answer to the question 「Do you own a pet?」.

First, we create a form with a field containing the question 「Do you own a pet?」.

Then we create two separate notifications: one for people who answer no and one for people for answer yes.

Then we enable conditional logic for each form accordingly. For the notification for people who do not have a pet, we set the conditional logic to 「Do you own a pet?」 is 「No」. This will send this notification to the users who said they do not own a pet.

For the notification for people who do have a pet, we set the conditional logic to 「Do you own a pet?」 is 「Yes」. This will send this notification to the users who said they do own a pet.

Click here to view a video demonstration.

{embed_post} Merge Tag

SummaryUsageMember VariablesExamples

Summary

Displays the member-variable data specified for the singular post or page from which the entry was submitted.

Note: This is not designed for use with forms embedded on blog or archive type pages.

Usage

{embed_post:[member_variable]}

Member Variables

For a list of all the member variables of a post object that you can use in your merge tag, review this WordPress reference document.

Examples

ExampleDescription{embed_post:ID}Display the ID of the post/page.{embed_post:post_title}Display the title of the post/page.{embed_post:post_author}Display the author ID of the post/page.

Below is a confirmation created with the above example merge tags:

This is what the user will see when they submit the form:

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;}

Enabling Conditional Logic For A Field

IntroductionBasic Conditional Logic ExampleConditional Logic Example using SectionsLimitationsPerformance

Introduction

The Enable Conditional Logic option in the field settings allows you to create rules to dynamically display or hide the field based on values from another field. In order to use conditional logic, you will need to add a field to your form which supports conditional logic.

After enabling conditional logic for a field, you will have the option to show or hide the field depending on whether all/any of the conditions you specify are met. You can specify additional conditions by clicking the plus icon to right of the conditions. Clicking the minus sign will remove the corresponding condition.

Basic Conditional Logic Example

In this example, we will use conditional logic to show different products based on a parent category. A dropdown field will determine what products may be purchased based on the current selection.

First, set up your fields. As we will be using a dropdown to handle the display of various products, start off by creating a single dropdown, a few product fields, and a total field to display the order total. In this example, we have created 3 different options within the dropdown for Jeep, Ford, and Honda, as well as product fields such as Wrangler, Cherokee, and Mustang.

As we want Jeep models to show up when Jeep is selected, Ford models when Ford is selected, and Honda models when Honda is selected, we will need to enable conditional logic on each of these products. Open the options on one of your products by clicking on the field, and click on the Conditional Logic section.

Within the fly-out, you should see a toggle labeled Enable Conditional Logic. When toggled on, the options to conditionally display or hide this field will be shown.

On each of your products, simply enable conditional logic, and use the dropdowns to only show when your dropdown equals the desired selection. For example, for our Wrangler product, we have set it to only show if the Option field equals Jeep.

That』s all there is to creating basic conditional logic within products. You should now be able to conditionally show or hide fields based on other fields in your form.

Conditional Logic Example using Sections

In this example, we will use conditional logic to show different sections of a form based on the user』s input. A radio button field will determine which form section displays based on the current selection.

As we will be using a radio button field to handle the display of the sections, start off by creating a single radio button field. In this example, we have created 3 different options within the radio button for Cat, Dog, and Fish.

Next you will need to create the different sections of the form using the Section field. Create the 3 sections of Cat, Dog, and Fish with the necessary fields under each section break. In this case we used Single Line Text, Number, and Paragraph fields.

As we want the Cat section to show up when Cat is selected, Dog section when Dog is selected, and Fish section when Fish is selected, we will need to enable conditional logic on each of these sections. Open the options on one of your sections by clicking on the field, and click on the Conditional Logic section.

Within the fly-out, you should see a toggle labeled Enable Conditional Logic. If you click the toggle on, the options to conditionally display or hide this field will be shown.

On each of your sections, simply enable conditional logic, and use the dropdowns to only show when your dropdown equals the desired selection. For example, for our Cat section, we have set it to only show if the radio button field equals Cat.

Limitations

As mentioned above in the introduction, conditional logic rules must be based on values from another field, configuring conditional logic to display or hide a field based on its own values is not supported. Fields hidden by conditional logic are ignored on form submission, this is one of the main reasons to use conditional logic and can』t be changed. This means fields hidden will be not available for any process done after form submission (e.g. Calculations) and not saved in the entry.Certain special characters, like pipe (|) greater than and less than ( < > ) or HTML tags in field values, can prevent conditional logic rules from working as expected. To avoid this problem when using a field with pre-defined choices, like a Drop Down or Radio Buttons field, we recommend enabling the 「show values」 setting in the field and ensure you use only plain text in the Value column for the choices, without any special character or HTML tags. Nested conditional logic. Please check the following documentation page for more details.

Performance

Conditional logic evaluation is done at client side (the browser) using JavaScript, and unfortunately browsers are not super fast doing these tasks. The browser has to process all fields to evaluate conditional logic and know which fields to display/hide, along with any other JS scripts that you may have in the page. Also some conditional logic use cases can add extra work to the browser, e.g. If you』re using conditional logic to show/hide a field and also using this same field as value in another field conditional logic that would make the browser to be constantly checking both fields rules, creating a loop and increasing the CPU resource usage of the browser.

This means if you have a huge form with lots of fields you may experience slowness in the form displaying or usage, this is something expected due to the explained above. The only workaround for improving the conditional logic performance in this case would be to reduce the number of fields or split your form in many smaller forms.

In the following tutorial you can see how to pass data from one form to another if you need it: Using Confirmation Query Strings to Populate a Form Based on Another Submission. There』s also a third-party add-on that could help to simplify the process: Easy Passthrough.

{embed_url} Merge Tag

SummaryUsage

Summary
The {embed_url} merge tag in Gravity Forms displays the URL from which the form was submitted. Gravity Forms uses merge tags to allow you to dynamically populate submitted field values and other dynamic information in notification emails, post content templates and more.
Usage
{embed_url}