Gravity Forms 文档

List of Hooks Related to User Registration

SummaryWhere To Find ThemList

Summary
This document contains a quick reference list of all the hooks related to user registration actions.
Where To Find Them
Many of these are contained within the User Registration Add-On, but some may be found within Gravity Forms core or other Gravity Forms Add-Ons.
List
For more information, click the item below and it will search the document library using the hook name.
gform_activate_user
gform_admin_pre_render
gform_disable_registration
gform_shortcode_login
gform_shortcode_user
gform_site_created
gform_user_registered
gform_user_registration_add_option_group
gform_user_registration_add_option_section
gform_user_registration_check_email_pre_signup_activation
gform_user_registration_config_validation
gform_user_registration_enable_multisite_section
gform_user_registration_form_selected
gform_user_registration_login_args
gform_user_registration_login_form
gform_user_registration_login_form_description
gform_user_registration_login_form_title
gform_user_registration_login_redirect_url
gform_user_registration_meta_value
gform_user_registration_new_site_meta
gform_user_registration_prepared_value
gform_user_registration_save_config
gform_user_registration_signup_meta
gform_user_registration_update_user_id
gform_user_registration_user_data_pre_populate
gform_user_registration_user_meta_options
gform_user_registration_username
gform_user_registration_validation
gform_user_registration_validation_message
gform_user_updated
gform_username
gform_userregistration_delete_signup
gform_userregistration_feed_settings_fields
gform_user_registration_login_form

Login Form Shortcode

IntroductionShortcode ActionsloginExampleParameters

Introduction
The Gravity Forms User Registration plug-in adds a couple of shortcode actions that extends the possibilities for your Gravity Forms shortcode. See also the article on the user information shortcode.
Shortcode Actions
login
Requires: User Registration Add-On.
Displays the login form.
Example
[gravityform action="login" description="false" logged_in_message="Yay! You are logged in!" registration_link_text="Register for my super awesome site" forgot_password_text="Stop forgetting your password" /]

Parameters

title
If the form title should be displayed. Defaults to true.

description
If the form title should be displayed. Defaults to false.

logged_in_avatar
If the user avatar should display for logged in users. Defaults to true.

logged_in_message
A message to display to users who are logged in.

login_redirect
Defines a URL that the user should be redirected to after they have logged in.

logout_redirect
Defines a URL that the user should be redirected to after they have logged out.

registration_link_display
If the registration link should be displayed. Defaults to true.

registration_link_text
The text to display within the registration link. Defaults to Register.

forgot_password_display
If the Forgot Password link should be displayed. Defaults to true.

forgot_password_text
The text to display within the Forgot Password link. Defaults to Forgot Password.

tabindex
Defines a custom tabindex.

User Registration Feed Meta

IntroductionUsagePropertiesMultisite PropertiesCustom Field Properties

Introduction
The Feed Object meta for the User Registration add-on is an associative array containing the properties which determine how the add-on should process the form submission.
12345678$feed['meta'] = array(    'feedName'                                => 'User Registration Feed 1',    'feedType'                                => 'create',    '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

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

feedType string
The feed action. Possible values: create or update.

username string
The ID of the form field containing the username.

first_name string
The ID of the form field containing the user』s first name.

last_name string
The ID of the form field containing the user』s last name.

displayname string
How the user』s name should be displayed publicly. Possible values: username, firstname, lastname, firstlast, or lastfirst.

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

password string
What to use for the user』s password. Possible values: ID of a password type field, generatepass, or empty.

role string
The role the user should be assigned. Possible values: a role name or gfur_preserve_role (update feed).

userMeta array
A multidimensional array containing the fields to be mapped to the user meta. See Custom Field Properties.

bpMeta array
A multidimensional array containing the fields to be mapped to the BuddyPress profile fields. See Custom Field Properties.

sendEmail boolean
Send the password to the new user by email? Default is true.

setPostAuthor boolean
Send this user as the author of the post created from the submission? Default is true.

userActivationEnable boolean
Enable user activation? Default is false.

userActivationValue string
Should the user be sent an email with an activation link or will the admin manually activate the user. Possible values: email or manual.

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.

Multisite Properties

createSite boolean
Should a new site be created?

siteAddress string
The ID of the form field that should be used for the site address.

siteTitle string
The ID of the form field that should be used for the site title.

siteRole string
The role the user should be assigned. Possible values: a role name or gfur_preserve_role (update feed).

rootRole string
The role the user should be assigned on the site they registered from. This option overrides the role property. Possible values: a role name, gfur_preserve_role (update feed), or empty.

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

key string
The User Meta or BuddyPress field the mapped form field should be saved to. Possible values: a user meta_key, a BuddyPress field id or gf_custom.

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

custom_key string
The custom meta_key. Only used by userMeta when key is set to gf_custom.

Using the User Registration Add-On

IntroductionPre-RequisitesCreate Your FormCreate Your FeedCustom Registration PageLimitationsPayPal Standard IntegrationBuddyPress IntegrationMapping BuddyPress Profile FieldsUser Registration Add-On Hooks

Introduction

The Gravity Forms User Registration Add-On integrates with any form to allow you to register users on your website. If you are familiar with the MailChimp, Campaign Monitor, and FreshBooks Add-Ons, you should have no problems getting started with the User Registration Add-On.

Pre-Requisites

Setup the User Registration Add-OnA form with the Username and Email fields

Create Your Form

The first step in integrating the User Registration Add-On is going to be creating the form you would like to use. This can include existing forms. The only required fields a Gravity Form must contain to be compatible with the User Registration Add-On are the Username and Email fields. Here are the steps used to create an optimal User Registration form.

In your WordPress admin dashboard go to New Form under the Forms navigation or choose an existing form from Edit Forms.

Ensure you have the following fields on your form: Username (required) – Single Line TextFirst Name & Last Name – NameEmail (required) – EmailPassword – PasswordSave your form.

Create Your Feed

Your notification feed does the heavy lifting and is used to determine exactly what should happen after someone submits your form. For information on setting up User Registration feeds, see the following: Creating a Feed for the User Registration Add-On

Custom Registration Page

If you would like to use a custom registration page, create and publish a new WordPress Page and embed your registration form there.

Go to Forms > Settings > User Registration, and check the box Enable Custom Registration Page.Once checked, you will be presented with a drop down of all the Pages on your site. Select the Page you created as your custom registration form.Click the Update Settings button. This will redirect any visitors who try to access your site』s /wp-login.php?action=register page to the page on your site which holds your User Registration form.

Limitations

The User Registration Add-On does not automatically add custom meta fields to the WordPress user profile page. If you need to display the data, take a look at Justin Tadlock』s custom user meta post. There are also some third-party plugins you can use like the Extra User Details.

The User Registration Add-On does not automatically create Roles & Capabilities in WordPress, nor does it provide any form of content restriction on your website based on Roles & Capabilities. If you need to create and manage Roles & Capabilities and restrict content on particular pages or posts, take a look at Members or User Role Editor, which both integrate directly with Gravity Forms Roles & Capabilities.

PayPal Standard Integration

The User Registration Add-On integrates with the Gravity Forms PayPal Standard Add-On to provide the following options:

Register user only when a payment is received.When this option is enabled, the user will not be registered until the PayPal payment has been received.Update user when subscription is canceled.When this option is enabled, the user』s role will be adjusted based on the drop down selected to the right.

BuddyPress Integration

The User Registration Add-On integrates with the BuddyPress (BP) Plugin allowing you to populate BP profile fields from Gravity Form fields. The BP Meta section of the User Registration feed functions almost identically to the Custom Meta section with the exception of not having an Add Custom option. To add new BP meta options, you must add additional BP profile fields on the BP Profile Field Setup page.

The User Registration Add-On is designed to work with BP v1.2.7.

Mapping BuddyPress Profile Fields

Some BuddyPress fields require special consideration when mapping to Gravity Form fields on your User Registration Feed. Below is a list of these fields and the requirements for mapping them correctly.

CheckboxesA BP checkboxes field must be mapped to a checkbox field. Mapping to other field types will have varied results. In addition, the BP checkboxes field values should match your GF checkbox field values. Only matched values will be added to BP user profile data correctly.Multi Select BoxA BP Multi Select Box field must be mapped to a checkbox field. Mapping to other fields types will have varied results.

User Registration Add-On Hooks

The User Registration Add-On provides an assortment of hooks that can be used to modify the default functionality or extend it. For more information, review the User Registration Add-On Hooks.

{user} Merge Tag

SummaryUsageMeta Field Name Examples (non-exhaustive):first_name:last_name:display_name:user_email:user_login:ID:preferred_contact_method

Summary
Displays the value of the user meta field for the logged in user, based on the modifier used.
Usage
{user:[meta_key]}
Meta Field Name Examples (non-exhaustive)
Any single user meta (including custom user meta) can be displayed with this merge tag by replacing [meta_key] with the specific meta_key for which you are wanting a value.
Below are a few examples of how this merge tag can be used. Please note: The user must be logged in when the entry is submitted.
:first_name
Displays the first name of the currently logged in user. {user:first_name}
:last_name
Displays the last name of the currently logged in user. {user:last_name}
:display_name
Displays the Display Name of the currently logged in user. {user:display_name}
:user_email
Displays the email of the currently logged in user. {user:user_email}
:user_login
Displays the user login of the currently logged in user. {user:user_login}
:ID
Displays the ID of the currently logged in user. {user:ID}
:preferred_contact_method
Displays the value of user meta with custom meta_key. {user:preferred_contact_method}

{user_agent} Merge Tag

SummaryUsageSample Output

Summary
Displays the browser and platform information of the machine from which the entry was submitted.
Usage
{user_agent}
Sample Output
User agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/604.3.5 (KHTML, like Gecko) Version/11.0.1 Safari/604.3.5

URLs Ignored for Gravity Forms License Site Limits

IntroductionRegex List

Introduction

Each type of Gravity Forms license has a limit to the number of websites that it can be installed on. You can see the list of those limits by license type in the linked help guide.

Sites in use as 「staging」, 「development」, 「sandbox」 etc, generally those being used for development and test and that are not being used for real customer traffic, are not counted against the site limit of your license.

The list below shows what we look for for to identify such a site, and answers the question: 「so how does Gravity Forms determine a staging/dev/sandbox site?」.

Regex List

Any site URL matching a pattern here will not be counted for the purposes of Gravity Forms site limits.

127.0.0.1

*.cloudwaysapps.com
*.dev.*
*.dreamhosters.com
*.flywheelstaging.com
*.kinsta.cloud
*.kinsta.com
*.lightningbasehosted.com
*.loc
*.local
*.localhost
*.localhost.*
*.mybluehost.com
*.myftpupload.com
*.myraidboxes.de (for raidboxes.io)
*.pantheonlocal.com
*.pantheonsite.io
*.savviihq.com
*.stage.site
*.staging
*.staging.*
*.test
*.test.*
*.tribe
*.wpengine.com
*.wpsc.site (for WP Stagecoach )
*.wpstagecoach.com

beta.*
corpwebstg.*
dev.*
devsite.*
local.*
localhost*
pantheon-dev.*
pantheon-live.*
sandbox.*
stage.*
staging[number].* i.e. staging10.mysite.com
test.*
upgrade.*
webdev.*
wpdev.*
www.staging[number].* (for SiteGround)

URL Validation In Gravity Forms

What is URL validation?How are URLs validated?TroubleshootingValidation hooks

Within Gravity Forms, URL validation methods exist to heighten security as well as avoid possible bugs. In this article, we will explain how URL validation works in Gravity Forms, and how to manipulate it.
What is URL validation?
URL validation is something that occurs within nearly all software and ensures the data submitted is the data expected. Doing so avoids issues related to security or bugs. By only allowing specific things to be passed, the probability of issues arising is significantly decreased.
How are URLs validated?
Within Gravity Forms, URLs are validated using multiple methods:

Checking that they begin with 『http://』 or 『https://』.
1$is_valid = ( strpos( $url, 'http://' ) === 0 || strpos( $url, 'https://' ) === 0 );

RFC validation of URLs using the filter_var() function.
1$is_valid = $is_valid && filter_var( $url, FILTER_VALIDATE_URL ) !== false;

Troubleshooting
Since Gravity Forms uses the PHP filter FILTER_VALIDATE_URL to validate URLs, the first course of action is to make sure your version of PHP is up-to-date.
If the issue persists on an up-to-date version of PHP, it is probably due to RFC standard limitations. The RFC standard is very strict, and does not account for some URLs that are valid. For example, it doesn』t support Hebrew characters even though there are URLs with those characters being used. To get around that problem, you can disable RFC validation. The following can be added to your theme or plugin:
1add_filter( 'gform_rfc_url_validation', '__return_false' );
Another alternative is to implement your own custom URL validation logic. That can be done with the gform_is_valid_url filter.
Validation hooks
Following are the hooks that be used to change the default URL validation methods:
gform_rfc_url_validation
gform_is_valid_url

Upgrading to Gravity Forms v2.3

IntroductionWhat Do I Have to Do Before I Upgrade?Backup your databaseUpdate all your add-onsUpdate custom codeTest the upgrade on a staging serverWhat Happens During the Upgrade?TroubleshootingThe system status page still says that the upgrade is queuedThe migration is going very slowlyI』m seeing a PHP warning about accessing a table that is not validCan I delete the deprecated tables once the upgrade is complete?How can I prevent Gravity Forms from checking for outdated code?I』m panicking and I want to roll back

Introduction
This is the first time Gravity Forms has ever made such a major change to the database schema so we want to ensure that the upgrade process goes smoothly and successfully for all sites.
For the vast majority of sites, the upgrade process will pass largely unnoticed. However, there』s a lot going on in this upgrade so this document explains how it works and a few troubleshooting tips in case you get stuck.
What Do I Have to Do Before I Upgrade?
Backup your database
Really. Double check that your site backups actually restore correctly. If something goes wrong with the upgrade this is your best option for rolling back.
Update all your add-ons
Make sure that all your Gravity Forms Add-Ons are up to date. You should update all add-ons – including third-party add-ons – but the following official Add-Ons must be updated to these versions before updating to Gravity Forms 2.3.

PayPal Add-On v2.9+
Authorize.Net Add-On v2.4+
Partial Entries Add-On v1.1+
PayPal Payments Pro Add-On v2.3+
Signature Add-On v3.4+
User Registration Add-On v3.9+
PayPal Pro Add-On v1.8+

If you have any of these add-ons and if any of them are older versions then update them. If you don』t see the automatic update in the plugins list then you can download the latest version from your downloads page.
If you don』t update all your add-ons then you risk either corrupting or losing data.
Update custom code
Check all your custom code for direct access to the database. If you see any references to the following legacy tables then you』ll need to update your code to use the new database tables. Here is a list of the legacy tables which should no longer be used:

wp_rg_form
wp_rg_form_meta
wp_rg_form_view
wp_rg_form_incomplete_submissions
wp_rg_lead
wp_rg_lead_detail
wp_rg_lead_detail_long
wp_rg_lead_meta
wp_rg_lead_notes

See the guide to upgrading your code for further details.
Custom code which uses the API functions like GFAPI will not be affected. We don』t recommend accessing the database directly unless API functions do not fulfil the requirements.
Test the upgrade on a staging server
If you have access to a staging server then do the upgrade there first and test your site thoroughly in debug mode.
What Happens During the Upgrade?

The new database schema is created with new tables for all the data. You can find out more about the new schema in this doc.
The upgrade is queued. On multisite installations, upgrades are processed one by one, not simultaneously to avoid overloading the database server, so if you have a lot of sites please be patient. Form Submissions can still be received at this point.
Once the migration starts, form submissions are blocked for the duration of the upgrade process. Attempts to submit forms will fail validation with the following message: 「Your form was not submitted. Please try again in a few minutes.」
The data is copied over to the new tables in batches of 2000 database rows.
If the process is interrupted for example, due to a server restart during the migration, then a cron task will kick in to continue the process within 5 minutes.
The database version is updated in the system report, the form submission block is released and Gravity Forms will now use the new tables.

Troubleshooting
The system status page still says that the upgrade is queued
Check in the system status report that background tasks are enabled on your installation. If they aren』t, follow the troubleshooting steps for background tasks.

The migration is going very slowly
It』s possible to speed up the process by increasing the batch size. However, beware, you may need to increase the PHP maximum execution time as well. For instance, a batch size of 100k would probably require a maximum execution time of around 5 minutes depending on your server resources. You can change the batch size by adding the following constant to your wp-config.php file:
define( 'GFORM_DB_MIGRATION_BATCH_SIZE', 50000 );

I』m seeing a PHP warning about accessing a table that is not valid
If an outdated add-on or some outdated custom code tries to access one of the legacy tables then the following PHP warning will be triggered and displayed and/or logged while in WP_DEBUG mode: 「An outdated add-on or custom code is attempting to access the **** table which is not valid in this version of Gravity Forms. Update your add-ons and custom code to prevent loss of form data.」. See the guide to upgrading your code for further details.

Can I delete the deprecated tables once the upgrade is complete?
The upgrade process will not delete the deprecated tables. We recommend leaving them in place for a period of time to ensure they are no longer in use (such as by forgotten custom code or an old third party plugin). Once you are satisfied that is the case, you may delete these tables as needed to satisfy storage or data security concerns. As always, we recommend backing up (and testing your backup) before modifying or deleting large portions of data, and ensure that the security of your backups and the orphaned tables is in line with your established data security protocols as they may include personal customer data.

How can I prevent Gravity Forms from checking for outdated code?
Gravity Forms currently checks all database queries for outdated code. This is not optimal for performance so the check will be phased out and removed in a future version. However, if you』re confident that none of your code is using the old tables then you can use the following snippet to reduce the number of checks made.
add_action( 'plugins_loaded', function(){
remove_filter( 'query', array( 'GFForms', 'filter_query' ) );
} );

I』m panicking and I want to roll back
If the upgrade was successful and you』ve started to receive entries then it』s best not to roll back or you will lose the new entries. If you want to roll back then make sure you delete all the new database tables or restore your database from a backup so the migration process can begin cleanly again when you try the upgrade again. Open a support ticket if you have any doubts.

Upgrading to GetResponse Add-On version 1.2.1

SummaryAreas To ConsiderWe Shouldn』t Have to Say This But…

Summary
GetResponse Add-On version 1.2.1 includes updates to utilize the newest GetResponse API version 3. This version of their API includes new field data validations that did not previously exist, and upgrading carries a risk if you have existing forms that were previously breaking these validations.
Areas To Consider

Refer to this section of our 「Setting up A Feed」 article for specific information on the way fields are validated now. A field that breaks the validation will be ignored on submission, and that data will not be added to your contact.

The newer API has a different endpoint for the GetResponse Enterprise plan. As such, there is a new setting to define that. This only needs adjustment if you are specifically using their Enterprise plan, as it defaults to 「standard」 (which covers all the other non-Enterprise plans).

The upgrade process to any version using the version 3 API will modify the metadata of your existing GetResponse feeds. If you downgrade later, those changes cannot be reversed, and your feed will need to be recreated manually.

We Shouldn』t Have to Say This But…
As always, test your forms and feeds in a sandbox environment before you upgrade any production environment.