The most basic perk must:
- Include the “Perk: True” custom plugin header
- A class that matches the file name (dashes will be replaced with underscores) and extends the GWPerk class.
- Include variables for the current perk version and the minimum versions required for Gravity Forms, Gravity Perks, and WordPress.
- An init() method (which will be called by Gravity Perks itself).
- A documentation() method (which includes a URL to the documentation for the perk).
Custom “Perk” Header
The plugin header for a perk will look much like a WordPress plugin header with the addition of one extra header:
| /** | |
| * Plugin Name: GP Sample Perk | |
| * Description: A description of what this perk does. | |
| * Plugin URI: http://gravitywiz.com/documentation/gp-sample-perk/ | |
| * Version: 1.2 | |
| * Author: Gravity Wiz | |
| * Author URI: http://gravitywiz.com/ | |
| * License: GPL2 | |
| * Perk: True | |
| */ |
Note the last header “Perk: True”. This is how Gravity Perks knows which WordPress plugins to load as perks and which to ignore.
Plugin Class Name
Everything stems from the perk naming convention. The perk name should always be prefixed with GP followed by the basic plugin name (i.e. GP Sample Plugin, GP Preview Submission, GP Limit Choices).
The folder and file name should match the plugin name replacing spaces with dashes and all characters being lowercase:
gp-sample-plugin/gp-sample-plugin.php
The class name of the plugin should match the file name, replacing dashes with undescores.
GP_Sample_Plugin
The class should extend the GWPerk class:
| class GP_Sample_Plugin extends GWPerk { } |
Version Variables
There are four required version variables:
| public $version = '1.2' |
Indicates the current version of the perk. Also specified in the plugin header.
| public $min_gravity_perks_version = '1.0'; |
Indicates the minimum required version of Gravity Perks for the perk.
| public $min_gravity_forms_version = '1.8'; |
Indicates the minimum required version of Gravity Forms for the perk.
| public $min_wp_version = '3.7'; |
Indicates the minimum required version of WordPress.
The Init Method
The init() method is called by Gravity Perks once individual perks are ready to be loaded. This is the heart of the perk and where the perks core functionality should be initialized.
| function init() { | |
| // start coding! | |
| } |
The Documentation Method
The documention() method should return an array with a “type” and “value” property. Currently the only supported “type” value is “url”. The “value” would then be a URL to the perk documentation.
| function documentation() { | |
| return array( | |
| 'type' => 'url', | |
| 'value' => 'http://gravitywiz.com/documentation/gp-sample-perk/' | |
| ); | |
| } |
Localization
Currently, localization support is present but in need of improvement. Use ‘gravityperks’ as the text domain for all localized strings. The lead developer will handle regenerating the translation files when new perks are added.
Adding Field Settings
Most settings added by perks are form settings or field settings. This section covers adding field settings.
Field settings are managed from the Form Editor view. Here is a top level view of how Gravity Form field settings work.
- Output your field setting markup to the page.
- Let GF know which form fields your field setting should be available for.
- Save data (via JS) to the global form object when the user interacts with the settings.
Output Field Settings Markup
Field Settings: “Perks” Tab
Gravity Perks provides a custom “Perks” tab on the Gravity Forms field settings UI (in the form editor). This should be used when the perk’s field setting does not fit well in any of the other tabs.
To add a setting to the “Perks” tab use the “gperk_field_settings” action.
| <?php | |
| add_action( 'gperk_field_settings', 'my_custom_setting' ) | |
| function my_custom_setting() { | |
| ?> | |
| <li class="my-custom-field-setting field_setting"> | |
| <input type="checkbox" id="my-custom-setting" value="1" onclick="SetFieldProperty( 'myCustomSetting', this.checked);"> | |
| <label class="inline" for="my-custom-setting"> | |
| _e( 'My Custom Setting Label' ) | |
| <?php gform_tooltip( 'my-custom-setting-toolip' ); ?> | |
| </label> | |
| </li> | |
| <?php | |
| } |
Field Settings: Default GF Tabs
To add a setting to the “General”, “Appearance” or “Advanced” tabs, use the respective action:
- gform_field_standard_settings
- gform_field_appearance_settings
- gform_field_advanced_settings
By default, these hooks provide a $position parameter which you can use to only output your settings when the hook is called from a specific position. Gravity Perks automates this a bit by creating position-specific versions of each hook:
- gform_field_standard_settings_25
- gform_field_standard_settings_50
- gform_field_standard_settings_75
- etc
The easiest way to find the position (and hook) you want is to uncomment the echo statement in gravityperks.php in this function:
| public static function dynamic_setting_actions( $position, $form_id ) { | |
| $action = current_filter() . '_' . $position; | |
| if( did_action( $action ) < 1 ) { | |
| do_action( current_filter() . '_' . $position, $form_id ); | |
| //echo current_filter() . '_' . $position . '<br />'; | |
| } | |
| } |
Display Your Field Settings
Some field settings are available for all field types. Others are available only under specific conditions. You can “register” your field setting for a specific field type
If the field setting will be available for all field types, you can something like this:
| add_action( 'gform_editor_js', 'field_settings_js' ); | |
| public function field_settings_js() { | |
| ?> | |
| <script type="text/javascript"> | |
| (function($) { | |
| $(document).ready(function(){ | |
| for( i in fieldSettings ) { | |
| fieldSettings[i] += ', .my-custom-field-setting'; | |
| } | |
| }); | |
| })(jQuery); | |
| </script> | |
| <?php | |
| } |
If the field setting will only be available for some field types, you will have to use a completely different process.
| add_action( 'gform_editor_js', 'field_settings_js' ); | |
| public function field_settings_js() { | |
| ?> | |
| <script type="text/javascript"> | |
| (function($) { | |
| $(document).bind( 'gform_load_field_settings', function( event, field, form ) { | |
| // populates the stored value from the field back into the setting when the field settings are loaded | |
| $( '#my-custom-setting' ).attr( 'checked', field['myCustomSetting'] == true ); | |
| // if our desired condition is met, we show the field setting; otherwise, hide it | |
| if( GetInputType( field ) == 'desired_field_type' ) { | |
| $( '.my-custom-field-setting' ).show(); | |
| } else { | |
| $( '.my-custom-field-setting' ).hide(); | |
| } | |
| } ); | |
| })(jQuery); | |
| </script> | |
| <?php | |
| } |
Save Data from Your Field Settings
Let’s refer back to the markup code sampe:
| add_action( 'gperk_field_settings', 'my_custom_setting' ) | |
| function my_custom_setting() { | |
| ?> | |
| <li class="my-custom-field-setting field_setting"> | |
| <input type="checkbox" id="my-custom-setting" value="1" onclick="SetFieldProperty( 'myCustomSetting', this.checked);"> | |
| <label class="inline" for="my-custom-setting"> | |
| _e( 'My Custom Setting Label' ) | |
| <?php gform_tooltip( 'my-custom-setting-toolip' ); ?> | |
| </label> | |
| </li> | |
| <?php | |
| } |
Note the use of the onclick event and the SetFieldProperty() function. This is a Gravity Forms JS function used to save the specified property of the field currently being edited. To save the value of a text input, you might use it like so:
<input ... onkeyup="SetFieldProperty( 'myCustomSetting', this.value );" />
This will save the data to the global form object handled by Gravity Forms on the page. When the “Update Form” button is clicked, the global form object is submitted and saved to the database.
