Including and Using Entry Meta with the Add-On Framework

Introduction

Entry meta data is custom data that’s stored and retrieved along with the entry object. For example, entry meta data may contain the results of a calculation made at the time of the entry submission, or a unique id for a subscriber returned by a mailing list service.

Any add-on which extends GFAddon, GFFeedAddOn, or GFPaymentAddOn can add custom entry meta.

get_entry_meta()

To add entry meta, override the get_entry_meta() function and return an associative array with the properties for each meta key your add-on is including.

Properties

  • label string

    The label for the entry meta item.

  • is_numeric boolean

    Used for sorting.

  • is_default_column boolean

    Default columns appear in the entry list by default. Otherwise the user has to edit the columns and select the entry meta from the list.

  • update_entry_meta_callback string

    The function that should be called when updating this entry meta value.

  • filter array

    An array containing the configuration for the filter used on the results pages, the entry list search, and export entries page.
    The array should contain one element: operators. e.g. ‘operators’ => array( ‘is’, ‘isnot’, ‘>’, ‘<‘ )

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
public function get_entry_meta( $entry_meta, $form_id ) {
    $entry_meta['simpleaddon_contact_id']   = array(
        'label'                      => 'Simple Add-On Contact ID',
        'is_numeric'                 => true,
        'is_default_column'          => true,
        'update_entry_meta_callback' => array( $this, 'update_entry_meta' ),
        'filter'         => array(
            'operators' => array( 'is', 'isnot', '>', '<' )
                    )
                );
    return $entry_meta;
}
public function update_entry_meta( $key, $lead, $form ) {
    $return ''; // return the value of the entry meta
}

Saving a value to the Entry Meta key

In this example we are using gform_update_meta() to store the contact id returned by the third-party service during feed processing in the entry meta.

1
2
3
4
5
6
7
public function process_feed( $feed, $entry, $form ) {
    $contact_id = $this->create_contact( $feed, $entry, $form );
    gform_update_meta( $entry['id'], 'simpleaddon_contact_id', $contact_id );
    $entry['simpleaddon_contact_id'] = $contact_id;
 
    return $entry;
}

Accessing the Entry Meta Value

If you have access to the Entry Object then you could access the meta value like so:

1
$contact_id = rgar( $entry, 'simpleaddon_contact_id' );

If you don’t have access to the Entry Object but you do have the entry id then you can access the value by using gform_get_meta() like so:

1
$contact_id = gform_get_meta( $entry_id, 'simpleaddon_contact_id' );

Deleting the Entry Meta Value

The gform_delete_meta() function can be used to delete the meta value from the entry like so:

1
gform_delete_meta( $entry_id, 'simpleaddon_contact_id' );