Gravity Forms 文檔

gform_export_fields

DescriptionUsageParametersExamples1. Add custom field2. Remove fields3. Remove advanced field inputs4. Single columns for multi-input fields5. Include Section FieldsPlacementSource Code

Description
Use this filter to add custom columns to the entry export. The new fields show in the field selection list. Use this filter in conjunction with the filter gform_export_field_value.
Usage
1add_filter( 'gform_export_fields', 'your_function_name' );

Parameters

$form Form Object
The current form.

Examples
1. Add custom field
This example adds two custom fields to the field selection list.
1234567add_filter( 'gform_export_fields', 'add_fields', 10, 1 );function add_fields( $form ) {    array_push( $form['fields'], array( 'id' => 'custom_field1', 'label' => __( 'Custom Field 1', 'gravityforms' ) ) );    array_push( $form['fields'], array( 'id' => 'custom_field2', 'label' => __( 'Custom Field 2', 'gravityforms' ) ) );     return $form;}
2. Remove fields
This example shows how you can remove fields from the field selection list.
12345678910111213141516171819202122232425add_filter( 'gform_export_fields', function ( $form ) {    // only limit the fields available for export form form ID 3    if ( $form['id'] == 3 ) {        // array of field IDs I never want to see on the export page        $fields_to_remove = array(            'payment_amount',            'payment_date',            'payment_status',            'transaction_id',            'user_agent',            'ip',            'post_id'        );         foreach ( $form['fields'] as $key => $field ) {            $field_id = is_object( $field ) ? $field->id : $field['id'];            if ( in_array( $field_id, $fields_to_remove ) ) {                unset ( $form['fields'][ $key ] );            }        }    }     // always return the form    return $form;} );
3. Remove advanced field inputs
This example shows how you can remove hidden name and address field inputs from the field selection list.
12345678910111213141516add_filter( 'gform_export_fields', function ( $form ) {    $types = array( 'name', 'address' );     foreach ( $form['fields'] as $key => $field ) {        if ( is_object( $field ) && in_array( $field->get_input_type(), $types ) ) {            foreach ( $field->inputs as $i => $input ) {                if ( rgar( $input, 'isHidden' ) ) {                    unset ( $field->inputs[ $i ] );                }            }        }     }     return $form;} );
4. Single columns for multi-input fields
This tutorial (by Gravity Wiz) adds a choice for each multi-input field allowing the field to be exported as a single column.
5. Include Section Fields
This example shows how you can make Section type fields available for selection, you』ll also need to use the gform_export_field_value hook to include the field description in the csv file.
123456789101112131415add_filter( 'gform_export_fields', 'restore_section_fields', 10 );function restore_section_fields( $form ) {    foreach ( $form['fields'] as $key => $field ) {        if ( is_object( $field ) && $field->type == 'section' ) {            $new_field = array(                'id'          => $field->id,                'label'       => $field->label,                'description' => $field->description,            );            $form['fields'][ $key ] = $new_field;        }    }     return $form;}
Placement
This code should be placed in the functions.php file of your active theme.
Source Code
This filter is located in GFExport::add_default_export_fields() in export.php.

gform_export_field_value

DescriptionUsageParametersExamples1. Set export value for custom fields2. Use choice text instead of values3. Decode special characters4. Format date field value5. Use display name instead of user id6. Format Number field value7. Remove new lines, tabs and carriage returns8. Export the secure file download URL9. Export customized Quiz field valuesPlacementSource Code

Description
Use this filter override the field value before it is included in the CSV export. This filter can be used in conjunction with the gform_export_fields filter to include custom columns in the export.
Usage
add_filter( 'gform_export_field_value', 'your_function_name', 10, 4 );

Parameters

$value string
Value of the field being exported.

$form_id integer
ID of the current form.

$field_id integer
ID of the current field.

$entry Entry Object
The current entry.

Examples
1. Set export value for custom fields
This example sets the values for two custom fields that were added to the export. The custom fields are named 「custom_field1」 and 「custom_field2」.
add_filter( 'gform_export_field_value', 'set_export_values', 10, 4 );
function set_export_values( $value, $form_id, $field_id, $entry ) {
switch( $field_id ) {
case 'custom_field1' :
$value = 'valueforcustomfield1';
break;
case 'custom_field2' :
$value = 'valueforcustomfield2';
break;
}
return $value;
}

2. Use choice text instead of values
add_filter( 'gform_export_field_value', 'export_choice_text', 10, 4 );
function export_choice_text( $value, $form_id, $field_id, $entry ) {
$field = GFAPI::get_field( $form_id, $field_id );

return is_object( $field ) && is_array( $field->choices ) ? $field->get_value_export( $entry, $field_id, true ) : $value;
}

3. Decode special characters
The following example shows how you can decode special characters such as the ampersand which may have been encoded during field value sanitization.
add_filter( 'gform_export_field_value', 'decode_export_values' );
function decode_export_values( $value ) {

return htmlspecialchars_decode( $value );
}

4. Format date field value
add_filter( 'gform_export_field_value', 'format_date', 10, 4 );
function format_date( $value, $form_id, $field_id, $entry ) {
$field = GFAPI::get_field( $form_id, $field_id );

return is_object( $field ) && $field->type == 'date' ? GFCommon::date_display( $value, $field->dateFormat ) : $value;
}

5. Use display name instead of user id
add_filter( 'gform_export_field_value', 'export_user_display_name', 10, 4 );
function export_user_display_name( $value, $form_id, $field_id, $entry ) {
if ( $field_id == 'created_by' ) {
$user = get_user_by( 'id', $value );

return is_object( $user ) ? $user->display_name : $value;
}

return $value;
}

6. Format Number field value
add_filter( 'gform_export_field_value', 'format_number_field_value', 10, 4 );
function format_number_field_value( $value, $form_id, $field_id, $entry ) {
$field = GFAPI::get_field( $form_id, $field_id );
$include_thousands_sep = true;

return is_object( $field ) && $field->type == 'number' ? GFCommon::format_number( $value, $field->numberFormat, rgar( $entry, 'currency' ), $include_thousands_sep ) : $value;
}

7. Remove new lines, tabs and carriage returns
The following example shows how you can remove new lines, tabs and carriage returns before exporting the field value. Useful when importing CSV files in Excel.
add_filter( 'gform_export_field_value', 'decode_export_values' );
function decode_export_values( $value ) {
$value = str_replace(array("n", "t", "r"), '', $value);
return $value;
}

8. Export the secure file download URL
This example shows how you can replace the direct file URL with the secure file download URL.
add_filter( 'gform_export_field_value', function ( $value, $form_id, $field_id ) {
if ( ! empty( $value ) ) {
$field = GFAPI::get_field( $form_id, $field_id );
if ( $field && $field->get_input_type() === 'fileupload' ) {
$urls = explode( ' , ', $value );
foreach ( $urls as &$url ) {
$url = $field->get_download_url( $url, $force_download = true );
}
$value = implode( ' , ', $urls );
}
}

return $value;
}, 10, 3 );

9. Export customized Quiz field values
This example shows how to export values for Quiz fields. This is useful only when you have set custom values after using the gform_quiz_show_choice_values filter.
// Note that priority is set to 20 to run after the Quiz add-on. This is required.
add_filter( 'gform_export_field_value', 'export_quiz_value', 20, 4 );
function export_quiz_value( $value, $form_id, $field_id, $entry ) {
$field = GFAPI::get_field( $form_id, $field_id );

if ( $field->type == 'quiz'){
GFCommon::log_debug( __METHOD__ . '(): Running for field id: => ' . $field_id );
$value = rgar( $entry, $field_id );
GFCommon::log_debug( __METHOD__ . '(): Value from entry: => ' . $value );
}

return $value;
}

Placement
This code should be placed in the functions.php file of your active theme.
Source Code
This filter is located in GFExport::start_export() in export.php.

gform_export_entries_forms

DescriptionUsageParametersExamplesPlacementSinceSource Code

Description
The 「gform_export_entries_forms」 filter in Gravity Forms allows the forms displayed on the Export Entries page to be filtered.
Usage
1add_filter( 'gform_export_entries_forms', 'your_function_name', 10, 1 );

Parameters

$forms array
The complete list of forms.

Examples
123456add_filter( 'gform_export_entries_forms', 'filter_forms', 10, 1 );function filter_forms( $forms ){    //remove half of the forms    $forms = array_slice( $forms, 0, round( count( $forms ) / 2 ) );    return $forms;}
Placement
This code should be placed in the functions.php file of your active theme.
Since
This filter was added in Gravity Forms version 2.4.6.16.
Source Code
This filter is located in GFExport::export_lead_page() in export.php.

gform_entry_pre_update

DescriptionUsageParametersExamplePlacementSinceSource Code

Description
Filters the entry before it is updated by an add-on or the API.
When editing entries in the admin, this filter is only used when updating payment information.
Usage
add_filter( 'gform_entry_pre_update', 'your_function_name', 10, 2 );

Parameters

$entry Entry Object
The current entry.

$original_entry Entry Object
The original entry, before changes.

Example
add_filter( 'gform_entry_pre_update', 'change_entry', 10, 2 );
function change_entry( $entry, $original_entry ){
if ( rgar( $entry, '1.3' ) == 'Rocketgenius' || rgar( $entry, '1.6' ) == 'Rocketgenius') {
$entry['2'] = '[email protected]';
}
return $entry;
}

Placement
This code should be placed in the functions.php file of your active theme.
Since
This filter was added in Gravity Forms version 1.8.8.
Source Code
This filter is located in GFAPI::update_entry() in includes/api.php and
GF_Forms_Model_Legacy::update_entry() in includes/legacy/forms_model_legacy.php.

gform_entry_pre_handle_confirmation

DescriptionUsageParametersExamplePlacementSinceSource Code

Description
Allows the entry to be modified before the confirmation is processed.
Usage
add_filter( 'gform_entry_pre_handle_confirmation', 'your_function_name', 10, 2 );

Parameters

$entry Entry Object
The current entry.

$form Form Object
The current form.

Example
add_filter( 'gform_entry_pre_handle_confirmation', 'change_entry', 10, 2 );
function change_entry( $entry, $form ){
if ( rgar( $entry, '1.3' ) == 'Rocketgenius' || rgar( $entry, '1.6' ) == 'Rocketgenius') {
$entry['2'] = '[email protected]';
}
return $entry;
}

Placement
This code should be placed in the functions.php file of your active theme.
Since
This filter was added in Gravity Forms version 2.3.4.2.
Source Code
This filter is located in GFFormDisplay::handle_submission() in form_display.php.

gform_entry_post_save

DescriptionUsageParametersExamples1. Temporarily change field value2. Change Entry PropertyPlacementSource Code

Description
Use this filter to perform actions right after an entry has been saved. This fires before notifications are sent and before the confirmation is processed.
Usage
add_filter( 'gform_entry_post_save', 'post_save', 10, 2 );

Parameters

$entry Entry Object
The current entry.

$form Form Object
The current form.

Examples
1. Temporarily change field value
This example appends the text 「testing」 to the value of field 1 in the lead. This new value will be available for use in notifications and confirmations, but the updated text is NOT saved with the entry.
add_filter( 'gform_entry_post_save', 'post_save', 10, 2 );
function post_save( $entry, $form ) {
$entry['1'] = rgar( $entry, '1' ) . ' testing';
return $entry;
}

2. Change Entry Property
This example shows how you can change an entry property such as the 『source_url』 and save the change.
add_filter( 'gform_entry_post_save', function ( $entry ) {
$entry['source_url'] = 'the new url here';
GFAPI::update_entry_property( $entry['id'], 'source_url', $entry['source_url'] );

return $entry;
} );

Placement
This code should be placed in the functions.php file of your active theme.
Source Code
apply_filters( 'gform_entry_post_save', $lead, $form )

This filter is located in GFFormDisplay::handle_submission() in form_display.php.

gform_entry_page_size

DescriptionUsageParametersExamplesSource Code

Description
Use this filter modify how many entries are shown per page in the Entry List view.
Usage
The base filter which would run for all forms would be used like so:
add_filter( 'gform_entry_page_size', 'your_function_name', 10, 2 );

To target a specific form append the form id to the hook name. (format: gform_entry_page_size_FORMID)
add_filter( 'gform_entry_page_size_10', 'your_function_name', 10, 2 );

Parameters

$page_size integer
The number of entries to show per page.

$form_id integer
The current form ID.

Examples
This example demonstrates how to set the entry page size. Let』s set it to show 40 entries per page.
add_filter( 'gform_entry_page_size', 'my_entry_page_size' );
function my_entry_page_size() {
return 40;
}

Source Code
This filter is located in GFEntryList::leads_page() in entry_list.php.

gform_entry_meta

DescriptionUsageParametersExamples1. Basic meta column2. Meta column with filters3. Quiz Add-On MetaPlacementSinceSource Code

Description
Use this hook to add custom properties to the Entry object. Allows entry meta data to be added as sortable columns to the entry list and export entries file.
Usage
add_filter( 'gform_entry_meta', 'custom_entry_meta', 10, 2);

Parameters

$entry_meta array
Entry meta array.

$form_id integer
The ID of the form from which the entry value was submitted.

Examples
1. Basic meta column
add_filter( 'gform_entry_meta', 'custom_entry_meta', 10, 2 );
function custom_entry_meta( $entry_meta, $form_id ) {
// data will be stored with the meta key named score
// label - entry list will use Score as the column header
// is_numeric - used when sorting the entry list, indicates whether the data should be treated as numeric when sorting
// is_default_column - when set to true automatically adds the column to the entry list, without having to edit and add the column for display
// update_entry_meta_callback - indicates what function to call to update the entry meta upon form submission or editing an entry
$entry_meta['score'] = array(
'label' => 'Score',
'is_numeric' => true,
'update_entry_meta_callback' => 'update_entry_meta',
'is_default_column' => true
);

return $entry_meta;
}

function update_entry_meta( $key, $lead, $form ) {
//update score
$value = "5";
return $value;
}

2. Meta column with filters
add_filter( 'gform_entry_meta', function ( $entry_meta, $form_id ) {
$entry_meta['test'] = array(
'label' => 'Test',
'is_numeric' => false,
'update_entry_meta_callback' => 'update_entry_meta_test',
'is_default_column' => false,
'filter' => array(
'key' => 'test',
'text' => 'Test',
'operators' => array(
'is',
'isnot',
)
),
);

return $entry_meta;
}, 10, 2 );

function update_entry_meta_test( $key, $entry, $form ){
//update test
$value = "thisisatest";
return $value;
}

3. Quiz Add-On Meta
add_filter( 'gform_entry_meta', array( 'GFQuiz', 'entry_meta' ), 10, 2);
public static function entry_meta($entry_meta, $form_id){
$form = RGFormsModel::get_form_meta($form_id);
$quiz_fields = GFCommon::get_fields_by_type( $form, array( 'quiz' ) );
if ( false === empty ( $quiz_fields ) ) {
$entry_meta['gquiz_score'] = array(
'label' => 'Quiz Score Total',
'is_numeric' => true,
'update_entry_meta_callback' => array('GFQuiz', 'update_entry_meta')
);
$entry_meta['gquiz_grade'] = array(
'label' => 'Quiz Grade',
'is_numeric' => false,
'update_entry_meta_callback' => array('GFQuiz', 'update_entry_meta')
);
$entry_meta['gquiz_percent'] = array(
'label' => 'Quiz Percentage',
'is_numeric' => true,
'update_entry_meta_callback' => array('GFQuiz', 'update_entry_meta')
);
$entry_meta['gquiz_is_pass'] = array(
'label' => 'Quiz Pass/Fail',
'is_numeric' => false,
'update_entry_meta_callback' => array('GFQuiz', 'update_entry_meta')
);
}
return $entry_meta;
}
public static function update_entry_meta($key, $lead, $form){
$value = "";
$results = self::get_quiz_results( $form, $lead, false );
if ( $key == "gquiz_score" )
$value = $results["score"];
elseif ( $key == "gquiz_percent" )
$value = $results["percent"];
elseif ( $key == "gquiz_grade" )
$value = $results["grade"];
elseif ( $key == "gquiz_is_pass" )
$value = $results["is_pass"] ? "1" : "0";
return $value;
}

Placement
This code should be placed in the functions.php file of your active theme.
Since
This filter was added in Gravity Forms version 1.7.
Source Code
This action hook is located in GFFormsModel::get_entry_meta() in forms_model.php.

gform_entry_meta_conditional_logic_notifications

DescriptionUsageParametersExamplesPlacementSource Code

Description
Enables the entry meta conditional logic filters to be modified on the notification edit page.
Usage
1add_filter( 'gform_entry_meta_conditional_logic_notifications', 'conditional_logic_filters', 10, 3 );
Parameters

$filters array
The array of filters

$form Form Object
The form object

Examples
This example removes certain entry meta filters depending on the form settings.
1234567891011121314151617181920212223add_filter( 'gform_entry_meta_conditional_logic_confirmations', 'conditional_logic_filters', 10, 3 );function conditional_logic_filters($filters, $form, $id) {    $quiz_fields = GFAPI::get_fields_by_type( $form, array( 'quiz' ) );    if (empty($quiz_fields))        return $filters;     switch ( self::get_form_setting( $form, 'grading' ) ) {        case "letter" :            if ( false === isset( $form['gquizDisplayConfirmationLetter'] ) || $form['gquizDisplayConfirmationLetter'] )                unset( $filters['gquiz_is_pass'] );            break;        case "passfail" :            if ( false === isset( $form['gquizDisplayConfirmationPassFail'] ) || $form['gquizDisplayConfirmationPassFail'] )                unset( $filters['gquiz_grade'] );            break;        default:            unset( $filters['gquiz_grade'] );            unset( $filters['gquiz_is_pass'] );    }     return $filters; }
Placement
This code should be placed in the functions.php file of your active theme.
Source Code
This action hook is located in GFNotification::notification_edit_page() in notification.php

gform_entry_meta_conditional_logic_confirmations

DescriptionUsageParametersExamplesPlacementSource Code

Description
Enables the entry meta conditional logic filters to be modified on the confirmation edit page.
Usage
add_filter( 'gform_entry_meta_conditional_logic_confirmations', 'conditional_logic_filters', 10, 3 );

Parameters

$entry_meta array
The entry meta.

$form array
The form object.

$notification_id string
The notification id.

Examples
This example removes certain entry meta filters depending on the form settings.
add_filter( 'gform_entry_meta_conditional_logic_confirmations', 'conditional_logic_filters', 10, 3 );
function conditional_logic_filters( $filters, $form, $id ) {
$quiz_fields = GFAPI::get_fields_by_type( $form, array( 'quiz' ) );
if ( empty( $quiz_fields ) )
return $filters;

switch ( self::get_form_setting( $form, 'grading' ) ) {
case "letter" :
if ( false === isset ( $form['gquizDisplayConfirmationLetter'] ) || $form['gquizDisplayConfirmationLetter'] )
unset( $filters['gquiz_is_pass'] );
break;
case "passfail" :
if ( false === isset ( $form['gquizDisplayConfirmationPassFail'] ) || $form['gquizDisplayConfirmationPassFail'] )
unset( $filters['gquiz_grade'] );
break;
default:
unset( $filters['gquiz_grade'] );
unset( $filters['gquiz_is_pass'] );
}

return $filters;
}

Placement
This code should be placed in the functions.php file of your active theme.
Source Code
This action hook is located in GFFormSettings::confirmations_edit_page() in form_settings.php.