GravityView  2.1.1
The best, easiest way to display Gravity Forms entries on your website.
Public Member Functions | Static Public Member Functions | Private Member Functions | Static Private Member Functions
GravityView_Merge_Tags Class Reference

Enhance Gravity Forms' merge tag functionality by adding additional merge tags. More...

Public Member Functions

 __construct ()
 

Static Public Member Functions

static format_date ( $date_created='', $property='')
 Format Merge Tags using GVCommon::format_date() More...
 
static process_modifiers ( $value, $merge_tag, $modifier, $field, $raw_value)
 Process custom GravityView modifiers for Merge Tags. More...
 
static replace_current_post ( $original_text, $form=array(), $entry=array(), $url_encode=false, $esc_html=false)
 Add a {current_post} Merge Tag for information about the current post (in the loop or singular) More...
 
static replace_entry_link ( $original_text, $form=array(), $entry=array(), $url_encode=false, $esc_html=false)
 Add a {gv_entry_link} Merge Tag, alias of [gv_entry_link] shortcode in {gv_entry_link:[post id]:[action]} format. More...
 
static replace_get_variables ( $text, $form=array(), $entry=array(), $url_encode=false)
 Allow passing variables via URL to be displayed in Merge Tags. More...
 
static replace_gv_merge_tags ( $text, $form=array(), $entry=array(), $url_encode=false, $esc_html=false)
 Run GravityView filters when using GFCommon::replace_variables() More...
 
static replace_variables ( $text, $form=array(), $entry=array(), $url_encode=false, $esc_html=true, $nl2br=true, $format='html', $aux_data=array())
 Alias for GFCommon::replace_variables() More...
 

Private Member Functions

 add_hooks ()
 Tap in to gform_replace_merge_tags to add merge tags. More...
 

Static Private Member Functions

static get_format_from_modifiers ( $exploded, $backup='')
 If there is a :format modifier in a merge tag, grab the formatting. More...
 
static maybe_urlencode ( $field=false, $value='')
 GF 2.3 adds GF_Field::get_modifers(), which allows us to check if a field has urlencode applied to it. More...
 
static modifier_explode ( $raw_value, $matches, $value, $field=null)
 Convert JSON or CSV values into space-separated string. More...
 
static modifier_maxwords ( $raw_value, $matches, $field=null)
 Trim the Merge Tag's length in words. More...
 
static modifier_strings ( $raw_value, $matches, $value='', $field=null)
 Process strings with common PHP string manipulations. More...
 
static modifier_timestamp ( $raw_value, $matches)
 Convert Date field values to timestamp int. More...
 

Detailed Description

Enhance Gravity Forms' merge tag functionality by adding additional merge tags.

Since
1.8.4

Definition at line 7 of file class-gravityview-merge-tags.php.

Constructor & Destructor Documentation

◆ __construct()

__construct ( )
Since
1.8.4

Definition at line 12 of file class-gravityview-merge-tags.php.

References add_hooks().

Member Function Documentation

◆ add_hooks()

add_hooks ( )
private

Tap in to gform_replace_merge_tags to add merge tags.

Since
1.8.4
See also
GFCommon::replace_variables_prepopulate

Definition at line 20 of file class-gravityview-merge-tags.php.

Referenced by __construct().

◆ format_date()

static format_date (   $date_created = '',
  $property = '' 
)
static

Format Merge Tags using GVCommon::format_date()

GVCommon::format_date()

See also
https://docs.gravityview.co/article/331-date-created-merge-tag for documentation
Parameters
string$date_createdThe Gravity Forms date created format
string$propertyAny modifiers for the merge tag (human, format:m/d/Y)
Returns
int|string If timestamp requested, timestamp int. Otherwise, string output.

Definition at line 472 of file class-gravityview-merge-tags.php.

References GVCommon\format_date().

Referenced by GravityView_Field_Date\apply_format_date_modifiers(), and GravityView_Field_Date_Created\replace_merge_tag().

◆ get_format_from_modifiers()

static get_format_from_modifiers (   $exploded,
  $backup = '' 
)
staticprivate

If there is a :format modifier in a merge tag, grab the formatting.

The :format modifier should always have the format follow it; it's the next item in the array In foo:format:bar, "bar" will be the returned format

Since
1.16
Parameters
array$explodedArray of modifiers with a possible format value
string$backupThe backup value to use, if not found
Returns
string If format is found, the passed format. Otherwise, the backup.

Definition at line 504 of file class-gravityview-merge-tags.php.

◆ maybe_urlencode()

static maybe_urlencode (   $field = false,
  $value = '' 
)
staticprivate

GF 2.3 adds GF_Field::get_modifers(), which allows us to check if a field has urlencode applied to it.

Since
2.0
See also
GFCommon::replace_field_variable

Here's the relevant code:

$modifier = strtolower( rgar( $match, $i ) ); $modifiers = array_map( 'trim', explode( ',', $modifier ) ); $field->set_modifiers( $modifiers );

Parameters
GF_Field | false$field
string$value
Returns
mixed|string

Definition at line 203 of file class-gravityview-merge-tags.php.

References $field, and $value.

◆ modifier_explode()

static modifier_explode (   $raw_value,
  $matches,
  $value,
  $field = null 
)
staticprivate

Convert JSON or CSV values into space-separated string.

Useful for Multiple Select field data, like categories

Since
2.0
Parameters
mixed$raw_valueThe raw value submitted for this field. May be CSV or JSON-encoded.
array$matchesRegex matches group
string$valueThe value as passed by Gravity Forms
GF_Field | false$fieldGravity Forms field, if any
Returns
string

Definition at line 234 of file class-gravityview-merge-tags.php.

◆ modifier_maxwords()

static modifier_maxwords (   $raw_value,
  $matches,
  $field = null 
)
staticprivate

Trim the Merge Tag's length in words.

Notes:

  • HTML tags are preserved
  • HTML entities are encoded, but if they are separated by word breaks, they will be counted as words Example: "one & two" will be counted as three words, but "one& two" will be counted as two words
Since
1.17
2.0 Added $field param and support for urlencode
Parameters
string$raw_valueValue to filter
array$matchesRegex matches group
GF_Field | false$field
Returns
string Modified value, if longer than the passed maxwords modifier

Use htmlentities instead, so that entities are double-encoded, and decoding restores original values.

See also
https://core.trac.wordpress.org/ticket/29533#comment:3

Definition at line 162 of file class-gravityview-merge-tags.php.

References $field.

◆ modifier_strings()

static modifier_strings (   $raw_value,
  $matches,
  $value = '',
  $field = null 
)
staticprivate

Process strings with common PHP string manipulations.

Since
2.0
Parameters
mixed$raw_valueThe raw value submitted for this field. May be CSV or JSON-encoded.
array$matchesRegex matches group
string$valueThe value as passed by Gravity Forms
GF_Field | false$fieldGravity Forms field, if any
Returns
string

Definition at line 256 of file class-gravityview-merge-tags.php.

◆ modifier_timestamp()

static modifier_timestamp (   $raw_value,
  $matches 
)
staticprivate

Convert Date field values to timestamp int.

Since
1.17

strtotime()

Parameters
string$raw_valueValue to filter
array$matchesRegex matches group
Returns
int Timestamp value of date. -1 if not a valid timestamp.

Definition at line 133 of file class-gravityview-merge-tags.php.

◆ process_modifiers()

static process_modifiers (   $value,
  $merge_tag,
  $modifier,
  $field,
  $raw_value 
)
static

Process custom GravityView modifiers for Merge Tags.

Is not processed on {all_fields} Merge Tag.

Since
1.17
Parameters
string$valueThe current merge tag value to be filtered.
string$merge_tagIf the merge tag being executed is an individual field merge tag (i.e. {Name:3}), this variable will contain the field's ID. If not, this variable will contain the name of the merge tag (i.e. all_fields).
string$modifierThe string containing any modifiers for this merge tag. For example, "maxwords:10" would be the modifiers for the following merge tag: {Text:2:maxwords:10}.
GF_Field$fieldThe current field.
mixed$raw_valueThe raw value submitted for this field.
Returns
string If no modifiers passed, $raw_value is not a string, or {all_fields} Merge Tag is used, original value. Otherwise, output from modifier methods.
See also
modifier_maxwords
modifier_timestamp
modifier_explode
modifier_strings
Runs Filter:
gravityview/merge_tags/modifiers/value Modify the merge tag modifier output
Since
2.0
Parameters
string$returnThe current merge tag value to be filtered.
string$raw_valueThe raw value submitted for this field. May be CSV or JSON-encoded.
string$valueThe original merge tag value, passed from Gravity Forms
string$merge_tagIf the merge tag being executed is an individual field merge tag (i.e. {Name:3}), this variable will contain the field's ID. If not, this variable will contain the name of the merge tag (i.e. all_fields).
string$modifierThe string containing any modifiers for this merge tag. For example, "maxwords:10" would be the modifiers for the following merge tag: {Text:2:maxwords:10}.
GF_Field$fieldThe current field.

Definition at line 45 of file class-gravityview-merge-tags.php.

References $field, $merge_tag, and $value.

◆ replace_current_post()

static replace_current_post (   $original_text,
  $form = array(),
  $entry = array(),
  $url_encode = false,
  $esc_html = false 
)
static

Add a {current_post} Merge Tag for information about the current post (in the loop or singular)

{current_post} is replaced with the current post's permalink by default, when no modifiers are passed. Pass WP_Post properties as :modifiers to access.

{current_post} is the same as {embed_post}, except:

  • Adds support for {current_post:permalink}
  • Works on post archives, as well as singular
See also
https://www.gravityhelp.com/documentation/article/merge-tags/#embed-post for examples
GFCommon::replace_variables_prepopulate - Code is there for {custom_field} and {embed_post} Merge Tags
Parameters
string$original_textText to replace
array$formGravity Forms form array
array$entryEntry array
bool$url_encodeWhether to URL-encode output
bool$esc_htmlIndicates if the esc_html function should be applied.
Returns
string Original text, if no {current_post} Merge Tags found, otherwise text with Merge Tags replaced
See also
WP_Post Post properties

Definition at line 541 of file class-gravityview-merge-tags.php.

References Utils\get().

◆ replace_entry_link()

static replace_entry_link (   $original_text,
  $form = array(),
  $entry = array(),
  $url_encode = false,
  $esc_html = false 
)
static

Add a {gv_entry_link} Merge Tag, alias of [gv_entry_link] shortcode in {gv_entry_link:[post id]:[action]} format.

Parameters
string$original_textText to replace
array$formGravity Forms form array
array$entryEntry array
bool$url_encodeWhether to URL-encode output
bool$esc_htmlIndicates if the esc_html function should be applied.
Returns
string Original text, if no {gv_entry_link} Merge Tags found, otherwise text with Merge Tags replaced
Parameters
array$match{ $match[0] Full tag $match[1] Post ID (optional) $match[2] Action (optional) }

Definition at line 409 of file class-gravityview-merge-tags.php.

References $entry, GV\get(), gravityview(), and GravityView_Entry_Link_Shortcode.

◆ replace_get_variables()

static replace_get_variables (   $text,
  $form = array(),
  $entry = array(),
  $url_encode = false 
)
static

Allow passing variables via URL to be displayed in Merge Tags.

Works with [gvlogic]: [gvlogic if="{get:example}" is="false"] ?example=false [else] ?example wasn't "false". It's {get:example}! [/gvlogic]

Supports passing arrays: URL: example[]=Example+One&example[]=Example+(with+comma)%2C+Two Merge Tag: {get:example} Output: Example One, Example (with comma), Two

Since
1.15
Parameters
string$textText to replace
array$formGravity Forms form array
array$entryEntry array
bool$url_encodeWhether to URL-encode output
Returns
string Original text, if no Merge Tags found, otherwise text with Merge Tags replaced
Runs Filter:
gravityview/merge_tags/get/glue/ Modify the glue used to convert an array of {get} values from an array to string
Since
1.15
Parameters
[in,out]string$glueString used to implode() $_GET values Default: ', '
[in]string$propertyThe current name of the $_GET parameter being combined
Runs Filter:
gravityview/merge_tags/get/esc_html/{url parameter name} Disable esc_html() from running on {get} merge tag By default, all values passed through URLs will be escaped for security reasons. If for some reason you want to pass HTML in the URL, for example, you will need to return false on this filter. It is strongly recommended that you do not disable this filter.
Since
1.15
Parameters
bool$esc_htmlWhether to esc_html() the value. Default: true
Runs Filter:
gravityview/merge_tags/get/esc_html/{url parameter name} Modify the value of the {get} replacement before being used
Parameters
[in,out]string$valueValue that will replace {get}
[in]string$textText that contains {get} (before replacement)
[in]array$formGravity Forms form array
[in]array$entryEntry array

Definition at line 613 of file class-gravityview-merge-tags.php.

References $entry, GV\$form, and $value.

◆ replace_gv_merge_tags()

static replace_gv_merge_tags (   $text,
  $form = array(),
  $entry = array(),
  $url_encode = false,
  $esc_html = false 
)
static

Run GravityView filters when using GFCommon::replace_variables()

Instead of adding multiple hooks, add all hooks into this one method to improve speed

Since
1.8.4
Parameters
string$textText to replace
array | bool$formGravity Forms form array. When called inside {
See also
GFCommon::replace_variables()} (now deprecated), false
Parameters
array | bool$entryEntry array. When called inside {
See also
GFCommon::replace_variables()} (now deprecated), false
Parameters
bool$url_encodeWhether to URL-encode output
bool$esc_htmlWhether to apply esc_html() to output
Returns
mixed

This prevents the gform_replace_merge_tags filter from being called twice, as defined in:

See also
GFCommon::replace_variables()
GFCommon::replace_variables_prepopulate()

Definition at line 373 of file class-gravityview-merge-tags.php.

References $entry, and GV\$form.

◆ replace_variables()

static replace_variables (   $text,
  $form = array(),
  $entry = array(),
  $url_encode = false,
  $esc_html = true,
  $nl2br = true,
  $format = 'html',
  $aux_data = array() 
)
static

Alias for GFCommon::replace_variables()

Before 1.15.3, it would check for merge tags before passing to Gravity Forms to improve speed.

Since
1.15.3 - Now that Gravity Forms added speed improvements in 1.9.15, it's more of an alias with a filter to disable or enable replacements.
1.8.4 - Moved to GravityView_Merge_Tags
1.15.1 - Add support for $url_encode and $esc_html arguments
1.22.4 - Added $nl2br, $format, $aux_data args
Parameters
string$textText to replace variables in
array$formGF Form array
array$entryGF Entry array
bool$url_encodePass return value through url_encode()
bool$esc_htmlPass return value through esc_html()
bool$nl2brConvert newlines to
HTML tags
string$formatThe format requested for the location the merge is being used. Possible values: html, text or url.
array$aux_dataAdditional data to be used to replace merge tags {
See also
https://www.gravityhelp.com/documentation/article/gform_merge_tag_data/}
Returns
string Text with variables maybe replaced
Runs Filter:
gravityview_do_replace_variables Turn off merge tag variable replacements.
Useful where you want to process variables yourself. We do this in the Math Extension.
Since
1.13
Parameters
[in,out]boolean$do_replace_variablesTrue: yes, replace variables for this text; False: do not replace variables.
[in]string$textText to replace variables in
[in]array$formGF Form array
[in]array$entryGF Entry array

Make sure the required keys are set for GFCommon::replace_variables

Definition at line 321 of file class-gravityview-merge-tags.php.

References $entry, GV\$form, $format, and gravityview().

Referenced by GravityView_Shortcode\parse_and_sanitize_atts(), gravityview\parse_and_sanitize_atts(), GravityView_Widget_Custom_Content\render_frontend(), GravityView_API\replace_variables(), and GravityView_Field_Custom\show_field_in_edit_entry().


The documentation for this class was generated from the following file: