GFCoupons is the class which houses the main functionality of the Gravity Forms Coupons Add-on, it extends the GFFeedAddOn class which is part of the add-on framework. Below are a few functions which you may find useful when working on your own custom code.
gf_coupons()
The gf_coupons() function is used to return an instance of the GFCoupons class.
get_submitted_coupon_codes()
Retrieves any submitted coupon codes from the entry object.
$coupon_codes = gf_coupons()->get_submitted_coupon_codes( $form, $entry );
$form Form Object
The form object currently being processed.
$entry Entry Object
The entry object currently being processed.
Returns array | boolean
An array of coupon codes or false if no codes were submitted.
get_coupons_by_codes()
Retrieves the properties for the specified coupon codes.
$coupons = gf_coupons()->get_coupons_by_codes( $codes, $form );
$codes string | array
The codes for the coupons to be retrieved.
$form Form Object
The form object currently being processed.
Returns array|boolean
An associative array with the coupon code as key to the array containing that coupons properties. False if no coupon feeds were found.
insert_feed()
The insert_feed() method can be used to add new coupons.
$feed_id = gf_coupons()->insert_feed( $form_id, $is_active, $meta );
$form_id integer
The ID of the form this coupon can be used with or 0 if it can be used with all forms.
$is_active boolean
Is this coupon active or inactive.
$meta Coupons Feed Meta
An associative array containing the properties which determine the type of coupon and discount available.
IntroductionGetting StartedThe Class VariablesActivating FeaturesRequiring DependenciesInitializationSettings APICreating Form SettingsAccessing Form SettingsAdding Custom Settings to the Main Form Settings TabCreating Plugin SettingsAccessing Plugin SettingsEnqueuing Scripts and StylesResults PageEntry MetaObject Locking APIUninstallingSample Add-On
Introduction
The GFAddOn class provides basic functionality for developers when creating new add-ons for Gravity Forms. It facilitates the following:
InitializationEnforcing Gravity Forms minimum version requirementCreating settings pages (add-on and form settings)Permissions and integration with the Members pluginConditional script enqueuing including no-conflict mode integrationAdding custom meta fields to the entry objectCreating a results pageIntegration with the Gravity Forms Locking APIStandardization of UI elements and stylesAutomatic clean uninstall
Getting Started
These are the first steps you』ll need to take to create an add-on using the Add-On Framework:
Create two PHP files. The first file handles registering your add-on. The second file will contain your add-on』s functionality. See A Simple Add-On in the Add-On Framework article for an example.In the second PHP file you would include the Add-On Framework files by calling the following:
GFForms::include_addon_framework();
Inherit the Add-On Framework by creating a new class which extends GFAddOn:
Add support for getting an instance of the add-on. When Gravity Forms is loading it initializes the add-ons; it does this by looping through each registered add-on and calling its get_instance function. Adding a get_instance function also helps other developers integrate with your add-on.
/**
* @var object|null $_instance If available, contains an instance of this class.
*/
private static $_instance = null;
/**
* Returns an instance of this class, and stores it in the $_instance property.
*
* @return object $_instance An instance of this class.
*/
public static function get_instance() {
if ( self::$_instance == null ) {
self::$_instance = new self();
}
return self::$_instance;
}
The Class Variables
$_version string
The version of this add-on.
$_min_gravityforms_version string
The version of Gravity Forms required for this add-on.
$_slug string
A short, lowercase, URL-safe unique identifier for the add-on. This will be used in option keys, filter, actions, URLs, and text-domain localization. The maximum size allowed for the slug is 33 characters.
$_path string
Relative path to the plugin from the plugins folder. Example 「gravityforms/gravityforms.php」
$_full_path string
The physical path to the main plugin file. Set this to __FILE__
$_title string
The complete title of the Add-On.
$_short_title string
The short title of the Add-On to be used in limited spaces.
Activating Features
The Add-On Framework contains many features that can be activated by overriding functions in the base class (GFAddOn). To override a function, add a function with the same name (and arguments) as the function in the base class.
A good example of this is the plugin page. If you take a look at the code in GFAddOn you』ll see an empty function called plugin_page() that looks like this:
/**
* Override this function to create a custom plugin page
*/
protected function plugin_page() {}
This function in GFAddOn does nothing; it』s just a placeholder with documentation explaining how to use it. To activate the plugin page and add a menu link for your add-on to the Forms menu, add the following function to the add-on:
/**
* Creates a custom page for this add-on.
*/
public function plugin_page() {
echo 'This page appears in the Forms menu';
}
Now the function in the base class has been overridden, the feature has been activated, and the link to the page will appear in the Forms menu.
There are many features like this in the Add-On Framework. Please read through the documentation on this page for further details of the features and how to activate them.
Requiring Dependencies
If your Gravity Forms add-on has any requirements that might not be present everywhere, it』s a good idea to define those dependencies using the minimum_requirements() class method. Within this class method, you will be able to define things such as Gravity Forms/WordPress/PHP versions, other Gravity Forms add-ons, PHP modules, and even other plugins that your Gravity Forms add-on might require.
Example:
array(
// Require WordPress version 4.6.2 or higher.
'wordpress' => array(
'version' => '4.6.2'
),
// Require PHP version 5.3 or higher.
'php' => array(
'version' => '5.3',
// Require specific PHP extensions.
'extensions' => array(
// Require cURL version 1.0 or higher.
'curl' => array(
'version' => '1.0'
),
// Require any version of mbstring.
'mbstring',
),
// Require specific functions to be available.
'functions' => array(
'openssl_random_pseudo_bytes',
'mcrypt_create_iv'
),
),
// Require other add-ons to be present.
'add-ons' => array(
// Require any version of the Mailchimp add-on.
'gravityformsmailchimp',
// Require the Stripe add-on and ensure the name matches.
'gravityformsstripe' => array(
'name' => 'Gravity Forms Stripe Add-On'
),
// Require the PayPal add-on version 5.0 or higher.
'gravityformspaypal' => array(
'version' => '5.0'
),
),
// Required plugins.
'plugins' => array(
// Require the REST API.
'rest-api/plugin.php',
// Require Jetpack and ensure the name matches.
'jetpack/jetpack.php' => 'Jetpack by WordPress.com',
),
// Any additional custom requirements via callbacks.
array( $this, 'custom_requirement' ),
);
Initialization
The Add-On Framework provides the following functions to help with initialization and to help organize your code:
pre_init()Override this function to perform any tasks that need to be done before the WordPress action 「init」 fires init()Override this function to perform tasks during WordPress initialization init_admin()Override this function to perform tasks only in the admin back-end init_frontend()Override this function to perform tasks only in the front-end init_ajax()Override this function to perform tasks only while processing ajax requests
IMPORTANT: call the parent function first. e.g. parent::init();
Example:
GFForms::include_addon_framework();
class GFSimpleAddOn extends GFAddOn {
// [snip: class variables]
public function pre_init() {
parent::pre_init();
// add tasks or filters here that you want to perform during the class constructor - before WordPress has been completely initialized
}
public function init() {
parent::init();
// add tasks or filters here that you want to perform both in the backend and frontend and for ajax requests
}
public function init_admin() {
parent::init_admin();
// add tasks or filters here that you want to perform only in admin
}
public function init_frontend() {
parent::init_frontend();
// add tasks or filters here that you want to perform only in the front end
}
public function init_ajax() {
parent::init_ajax();
// add tasks or filters here that you want to perform only during ajax requests
}
}
Settings API
The Add-On Framework includes a Settings API that can be used to create form and plugin settings pages. The API provides the mechanisms for rendering field UIs and saving values automatically. It supports standard field types like radio buttons, text boxes, and checkboxes and also custom field types.
See the Settings API for details about how to define sections of fields.
See the following articles for implementation examples of the various field types.
Text (『type』 => 『text』)Textarea Field (『type』 => 『textarea』)Hidden Field (『type』 => 『hidden』)Radio Field (『type』 => 『radio』)Checkbox Field (『type』 => 『checkbox』)Select Field (『type』 => 『select』)Select_Custom Field (『type』 => 『select_custom』)Field_Map Field (『type』 => 『field_map』)Field_Select Field (『type』 => 『field_select』)Dynamic_Field_Map Field (『type』 => 『dynamic_field_map』)Checkbox_And_Select Field (『type』 => 『checkbox_and_select』)Save Button (『type』 => 『save』)Custom Field Type
There are also a number of Helper Functions available for use when rendering custom settings.
Creating Form Settings
To create a tab on the Form Settings page, override the form_settings_fields() function returning an array with the configuration for the settings.
/**
* Define the markup for the my_custom_field_type type field.
*
* @param array $field The field properties.
*/
public function settings_my_custom_field_type( $field ) {
echo '
' . esc_html__( 'My custom field contains a few settings:', 'simpleaddon' ) . '
';
// get the text field settings from the main field and then render the text field
$text_field = $field['args']['text'];
$this->settings_text( $text_field );
// get the checkbox field settings from the main field and then render the checkbox field
$checkbox_field = $field['args']['checkbox'];
$this->settings_checkbox( $checkbox_field );
}
/**
* The feedback callback for the 'mytextbox' setting on the plugin settings page and the 'mytext' setting on the form settings page.
*
* @param string $value The setting value.
*
* @return bool
*/
public function is_valid_setting( $value ) {
return strlen( $value ) > 10;
}
The code above will create a tab on the Form Settings page for the Simple Add-On and look similar to the following:
Accessing Form Settings
The form settings for the current add-on can be accessed easily by using the function get_form_settings($form). This returns an associative array with the settings for the current add-on for the given form.
Example:
$settings = $this->get_form_settings( $form );
Adding Custom Settings to the Main Form Settings Tab
To add a custom setting to the main form settings tab, please consult the documentation for the gform_form_settings hook. Here』s a quick example of how you』d implement it with the Add-On Framework:
GFForms::include_addon_framework();
class GFSimpleAddOn extends GFAddOn {
Plugin settings pages appear in a tab in the Gravity Forms settings page. To create a settings page, override the plugin_settings_fields() function using the same array structure as described above for the form settings.
Example:
/**
* 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' => 'mytextbox',
'tooltip' => esc_html__( 'This is the tooltip', 'simpleaddon' ),
'label' => esc_html__( 'This is the label', 'simpleaddon' ),
'type' => 'text',
'class' => 'small',
'feedback_callback' => array( $this, 'is_valid_setting' ),
)
)
)
);
}
[/php]
Accessing Plugin Settings
The plugin settings for the current add-on can be accessed easily by using the following functions:
get_plugin_settings()returns all plugin settings in an associative array get_plugin_setting( $setting_name )returns a single setting with the given setting name e.g. 「my_setting_name」
public function results_fields( $form ) {
return GFAPI::get_fields_by_type( $form, array( 'poll' ) );
}
[/php]
Entry Meta
See the Including and using Entry Meta with the Add-On Framework article.
Object Locking API
The Gravity Forms Object Locking API prevents conflicts from occurring by preventing concurrent editing by different users of forms, entries, form settings and plugin settings. This eliminates the problem of users overwriting the changes made be other users. When one user is editing an object, the second user will be offered the choice to request control over the object. The first user will then be offered the choice to accept or deny that request. If the first user fails to respond, the second user will be offered control.
The Locking API uses the WordPress Heartbeat API to send updates at regular intervals, usually every 15 seconds when the page has focus, and every 2 minutes when the page doesn』t have the focus.
The Add-On Framework provides developers access to the Object Locking API in 2 ways:
Locking is automatically implemented for form settings and plugin settings – nothing additional is required for this to work. Locking for custom objects. For example, an add-on that manages employee information may have an 「employee」 object. The Add-On Framework will prevent concurrent editing of the employee profile.
Locking is activated by overriding the following functions:
get_locking_config()Return an array with the locking configuration to activate locking get_locking_object_id()Return the object id is_locking_edit_page()Return true if the current page is the edit page is_locking_view_page()Return true if the current page is the view page is_locking_list_page()Return true if the current page is the list page
public function get_locking_config(){
$strings = array(
"currently_locked" => __('This contact is currently locked. Click on the "Request Control" button to let %s know you'd like to take over.', "gravityforms"),
"currently_editing" => "%s is currently editing this contact",
"taken_over" => "%s has taken over and is currently editing this contact.",
"lock_requested" => __("%s has requested permission to take over control of this contact.", "gravityforms")
);
$contact_id = $this->get_object_id();
$config = array(
"object_type" => "contact",
"capabilities" => array("gravityforms_contacts_edit_contacts"),
"redirect_url" => admin_url(sprintf("admin.php?page=gf_contacts&view=contact&subview=profile&id=%d&edit=0", $contact_id)),
"edit_url" => admin_url(sprintf("admin.php?page=gf_contacts&view=contact&subview=profile&id=%d&edit=1", $contact_id)),
"strings" => $strings
);
return $config;
}
public function get_locking_object_id(){
return rgget("id");
}
public function is_locking_edit_page(){
$is_edit_page = rgget("page") == "gf_contacts" && rgget("view") == "contact" && rgget("subview") == "profile" && rgget("edit") == 1;
return $is_edit_page;
}
public function is_locking_view_page(){
$is_view_page = rgget("page") == "gf_contacts" && rgget("view") == "contact" && rgget("subview") == "profile" && rgget("edit") == 0;
return $is_view_page;
}
public function is_locking_list_page(){
$is_list_page = rgget("page") == "gf_contacts" && rgempty("view", $_GET);
return $is_list_page;
}
Uninstalling
All Gravity Forms Add-Ons should provide a way to remove settings completely before the user deactivates and deletes the plugin. The Add-On Framework handles much of this for you so you don』t need to configure anything unless you』ve added settings or database tables of your own. The uninstall button will be on the plugin settings page. The following elements will be removed automatically when the user uninstalls the add-on.
Form settingsPlugin settingsEntry metaVersion information
If you need to perform additional tasks such as removing custom options or database tables then override the uninstall() function. This will be called after permissions have been checked and before removing all the settings.
Example:
public function uninstall() {
// custom code to drop database tables and remove custom options
}
The uninstall section of the settings page can be modified or removed completely by overriding the render_uninstall() function.
Example:
public function render_uninstall() {
// an empty function will remove the uninstall section on the settings page
}
Sample Add-On
A sample add-on is available which demonstrates the basic features of the Add-On Framework:
Plugin pageForm SettingsPlugin SettingsScripts and Styles
Introduction
GF_User_Registration is the class which houses the main functionality of the Gravity Forms User Registration Add-on; it extends the GFFeedAddOn class which is part of the add-on framework. Below are a few functions which you may find useful when working on your own custom code.
gf_user_registration()
The gf_user_registration() function is used to return an instance of the GF_User_Registration class.
maybe_process_feed()
Triggers processing of the User Registration feeds for the specified form and entry objects.
$entry = gf_user_registration()->maybe_process_feed( $entry, $form );
$entry Entry Object
The Entry Object to be processed.
$form Form Object
The Form Object to be processed.
Returns Entry Object
get_single_submission_feed()
Retrieves the feed for the specified form and entry objects.
$feed = gf_user_registration()->get_single_submission_feed( $entry, $form );
$entry Entry Object
The Entry Object to be processed.
$form Form Object
The Form Object to be processed.
Returns Feed Object|boolean
The feed which was used to process the supplied entry object or false if a feed wasn』t processed for the entry and an active feed with matching conditional logic could not be found.
get_meta_value()
Retrieves the value to be used for the specified meta key.
$value = gf_user_registration()->get_meta_value( $meta_key, $meta, $form, $entry );
$meta_key string
The meta key for the field which was mapped when configuring the feed.
$meta User Registration Feed Meta
The array containing the feed properties.
$form Form Object
The Form Object being processed.
$entry Entry Object
The Entry Object being processed.
Returns string
The value matching the meta mapping for the given meta key or if not found, an empty string.
add_validation_error()
Useful when performing custom validation using the gform_user_registration_validation filter to add a custom validation error message.
$form = gf_user_registration()->add_validation_error( $field_id, $form, $message );
$field_id integer
The ID of the field the validation error should be applied to.
$form Form Object
The Form Object to be processed.
$message string
The validation message to be applied to the field.
Returns Form Object
get_user_by_entry_id()
Retrieve the user object or id for the user which was created or updated by the supplied entry id.
$user = gf_user_registration()->get_user_by_entry_id( $entry_id );
$user_id = gf_user_registration()->get_user_by_entry_id( $entry_id, true );
$entry_id integer
The ID of the entry the user was created or updated from.
$id_only boolean
Defaults to false. Indicates if the user ID should be returned instead of the full WP_User object
Returns boolean|integer|WP_User
False if a user wasn』t created or updated from the entry, or the user id or WP_User object.
get_site_by_entry_id()
Retrieve the id of the site which was created or updated by the supplied entry id.
$site = gf_user_registration()->get_site_by_entry_id( $entry_id );
$entry_id integer
The ID of the entry the user was created or updated from.
Returns boolean|integer
False if a site wasn』t created or updated from the entry, or the site id.
insert_feed()
The insert_feed() method can be used to add User Registration feeds.
$feed_id = gf_user_registration()->insert_feed( $form_id, $is_active, $meta );
$form_id integer
The ID of the form this feed will be used with.
$is_active boolean
Is this feed active or inactive.
$meta User Registration Feed Meta
An associative array containing the properties which determine if a user will be updated or created when the feed is processed.
Returns integer
The ID of the new feed.
add_note()
Add a note to the specified Entry.
gf_user_registration()->add_note( $entry_id, $note, $note_type );
$entry_id integer
The ID of the Entry this note should be added to.
$note string
The note to be added.
$note_type string
The type of note to be added. Example values: note, success, or error.
log_debug()
Writes a debug message to the log file for the User Registration Add-On. Requires the Logging Add-On.
gf_user_registration()->log_debug( $message );
$message string
The message to be written to the User Registration log.
log_error()
Writes an error message to the log file for the User Registration Add-On. Requires the Logging Add-On.
gf_user_registration()->log_error( $message );
$message string
The message to be written to the User Registration log.
Description
Setting this option allows you to specify a Form JSON file from which a set of default forms can be pre-generated when a theme containing this option is activated. This option can also be used in your theme』s functions.php file.
Usage
define( 'GF_THEME_IMPORT_FILE', 'path/to/gf_import.json' );
Note: The path is relative to your theme root.
Placement
This constant should be set in your wp-config.php. See the article Wp Config Options for more details regarding the JSON file.
Description
Indicates if the minimum supported version of WordPress has been met.
This constant is not meant to be changed, only to be read.
Usage
define( 'GF_SUPPORTED_WP_VERSION', true );
Placement
This constant is set in the file gravityforms.php.
Description
Automatically pre-populates the reCAPTCHA public key when a new site is created on your Multi-Site install.
Usage
define( 'GF_RECAPTCHA_PUBLIC_KEY', 'YOUR-KEY-HERE' );
Placement
This constant should be set in your wp-config.php. See the article Wp Config Options for more details.
Description
Automatically pre-populates the reCAPTCHA private key when a new site is created on your Multi-Site install.
Usage
define( 'GF_RECAPTCHA_PRIVATE_KEY', 'YOUR-KEY-HERE' );
Placement
This constant should be set in your wp-config.php. See the article Wp Config Options for more details.
Description
Specifies the minimum WordPress version required by Gravity Forms.
This constant is not meant to be changed, only to be read.
Usage
define( 'GF_MIN_WP_VERSION', '3.7' );
Placement
This constant is set in the file gravityforms.php.
Description
Specifies the minimum version of WordPress that will be officially supported by Gravity Forms.
This constant is not meant to be changed, only to be read.
Usage
define( 'GF_MIN_WP_VERSION_SUPPORT_TERMS', '5.1' );
Placement
This constant is set in the file gravityforms.php.
Description
Allows the non-dismissible security notice which displays on every WordPress admin page when logging is enabled to be turned off.
Usage
define( 'GF_LOGGING_DISABLE_NOTICE', true );
Placement
This constant should be set in your wp-config.php. See the article Wp Config Options.
