Writing Your Own Perks

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.