GravityView Merge Tag modifiers

GravityView Merge Tag Modifiers

GravityView heavily uses Gravity Forms Merge Tags, in addition to adding new ones.

To enhance Merge Tags, GravityView adds additional "modifiers" that allow you to format Merge Tags differently.

GravityView Modifiers

String formatting

• :wpautop   - Converts line breaks into HTML paragraphs; runs wpautop()   on the output
• :wptexturize   - Applies WordPress "texturize" formatting (curly quotes, em-dashes, etc.); runs wptexturize()   on the output
• :esc_html   - Makes field output safe to use in HTML attributes; runs esc_html()   on the output
• :sanitize_html_class   - Makes output safe for use as CSS class names; runs sanitize_html_class()   on the output
• :sanitize_title   - Creates URL-friendly slugs; runs sanitize_title()   on the output
• :urlencode   - URL-encodes the output for use in query strings; runs urlencode()   on the output
• :rawurlencode  - URL-encodes the output per RFC 3986, encoding spaces as %20 ; runs rawurlencode()  on the output
• :maxwords:{number}   - Limits output to {number}   of words

Case transformation

• :strtolower   - Converts the entire output to lowercase
• :strtoupper   - Converts the entire output to uppercase
• :ucfirst   - Capitalizes the first character of the output
• :ucwords   - Capitalizes the first character of each word

Name formatting

• :initials   - Converts a full name to initials (e.g., "John Doe" becomes "JD")

Date and time formatting

• :timestamp   - Converts a date field value to a Unix timestamp
• :human   - Displays dates and times in a human-readable relative format (e.g., "2 hours ago", "3 days ago")
• :format:{format}   - Formats date and time field merge tags using WordPress date format strings

Multi-value fields

• :explode   - Converts JSON or CSV values into a space-separated string (useful for Multiple Select fields)

Usage: :esc_html   Modifier

The :esc_html   modifier runs the output of the field through the esc_html()   function in WordPress.

Before, you weren't able to use Merge Tags when generating HTML. This modifier makes field output safe for HTML, and allows you to use Merge Tags inside HTML attributes safely:

{Business Name:2}   is The "World's Best" Astronaut Ice Cream  

Before:

Without the Merge Tag modifier, you would use this code:

<a href="{Website:3}" title="Go to the {Business Name:2} website">{Business Name:2}</a>

And the output would be broken HTML:

<a href="{Website:3}" title="Go to the The "World's Best" Astronaut Ice Cream website">The "World's Best" Astronaut Ice Cream</a>

Notice the extra double quotes inside the HTML tag? That is broken HTML.

After:

Let's update the example to use the :esc_html   modifier:

<a href="{Website:3}" title="Go to the {Business Name:2:esc_html} website">{Business Name:2:esc_html}</a>

The output is now valid HTML, with the quotes converted to HTML entities:

<a href="{Website:3}" title="Go to the The &quot;World&#039;s Best&quot; Astronaut Ice Cream website">The &quot;World&#039;s Best&quot; Astronaut Ice Cream</a>

Usage: :sanitize_html_class   Modifier

This modifier is perfect for making sure the field values are valid CSS class names. Use it inside your HTML, like so:

<div class="{Category:5:sanitize_html_class}">[...]</div>

The :sanitize_html_class   modifier runs the field output through the gravityview_sanitize_html_class()   function, which is very similar to the sanitize_html_class()   WordPress function, except the WordPress function does not allow spaces (multiple CSS classes), and GravityView does.

Before:

• Merge Tag: {Your Profession:5}  
• Value: Scientist, Astronaut!  

After:

• Merge Tag: {Your Profession:5:sanitize_html_class}  
• Value: Scientist Astronaut  

Usage: :sanitize_title   Modifier

The :sanitize_title   modifier runs the field output through the sanitize_title()   WordPress function.

This is convenient for adding standardized attributes to HTML tags.

Before:

• Merge Tag: {Your Profession:5}  
• Value: Scientist, Astronaut!  

After:

• Merge Tag: {Your Profession:5:sanitize_title}  
• Value: scientist-astronaut  

Usage: :urlencode   Modifier

The :urlencode   modifier URL-encodes the output, making it safe to use in query strings.

Before:

• Merge Tag: {Search Query:7}  
• Value: rocket science & space travel  

After:

• Merge Tag: {Search Query:7:urlencode}  
• Value: rocket+science+%26+space+travel  

This is useful when building URLs dynamically:

https://example.com/search?q={Search Query:7:urlencode}

Usage: :rawurlencode  Modifier

The :rawurlencode  modifier URL-encodes the output according to RFC 3986. Unlike :urlencode , which encodes spaces as + , :rawurlencode  encodes spaces as %20 . This makes it more suitable for encoding URL path segments and safer for use with email links.

This modifier runs the rawurlencode() function on the Merge Tag's content.

Before:

• Merge Tag: {Search Query:7}
• Value: rocket science & space travel

After:

• Merge Tag: {Search Query:7:rawurlencode}
• Value: rocket%20science%20%26%20space%20travel

Use :rawurlencode  when building URLs that need to be used in emails.

<a href="mailto:[email protected]?subject={My Topic:1:rawurlencode}">email us</a>

Usage: :wpautop   Modifier

The :wpautop   modifier changes double line breaks in the text into HTML paragraphs (<p>...</p>  ) and single line-breaks are converted to HTML <br />  . Line breaks within the script and style sections are not affected.

This modifier will run the wpautop() function on the Merge Tag's content. Learn more on WordPress.org.

Before:

• Merge Tag: {Cosmonaut:4}  
• Output: The Earth was small and light blue.  

After:

• Merge Tag: {Cosmonaut:4:wpautop}  
• Output: <p>The Earth was small and light blue.</p>  

Usage: :wptexturize   Modifier

The :wptexturize   modifier applies WordPress "texturize" formatting, which converts straight quotes to curly quotes, double hyphens to em-dashes, and other typographic improvements.

This modifier will run the wptexturize() function on the Merge Tag's content.

Before:

• Merge Tag: {Quote:8}  
• Value: She said "Hello" -- and then left...  

After:

• Merge Tag: {Quote:8:wptexturize}  
• Value: She said "Hello" — and then left…  

Usage: :maxwords:{number}   Modifier

Limits the length of displayed field content to {number}   words.

When the content length exceeds the number of words, "…" will be appended to the text. Example: "The text is too long" becomes "The text…".

Example: Display the first 10 words of a testimonial

We have a form named "Testimonial", where we gather customer feedback. It has a textarea field called "Quote", and it has the field ID of "12".

To display the content in GravityView, we normally use the {Quote:12}   Merge Tag. The full quote is too long, though:

I really enjoyed the service that I received. Thank you for all your help! In the future, I will have no reservations about referring people to your business. Thanks again!

That quote has 30 words. We only want to show the first 10 words so the content fits nicely in our heading. We can use the :maxwords   modifier to limit the number of words.

We can add the :maxwords   modifier to the end of the Merge Tag, along with the max number of words we want: :maxwords:10  . The final Merge Tag looks like {Quote:12:maxwords:10}  .

Here's the output from the {Quote:12:maxwords:10}   Merge Tag:

I really enjoyed the service that I received. Thank you…

Notes

• Commas, periods, etc, connected to the final word of the value will be preserved.
  • If you set :maxwords:3   on this value: Example with comma, to be trimmed  , the output would be Example with comma,…  
• HTML tags are preserved. Whitespace between tags will make an HTML tag be considered a separate word:
  • <p> <strong>Example</strong></p>   will be considered two words because there is a space between <p>   and <strong>  .
  • <p><strong>Example</strong></p>   will be considered one word.
• HTML entities are allowed. If they are separated by word breaks, they will be counted as words:
  • Foo & Bar   will be considered three words because &   is separate.
  • Foo& Bar   will be considered two words because &   is connected to Foo  .
• When the text is truncated, "…" is appended to the output, using HTML entity …  .

Usage: Case Transformation Modifiers

GravityView provides four modifiers for transforming the case of text:

:strtolower  

Converts the entire output to lowercase.

Before:

• Merge Tag: {Name:3}  
• Value: JOHN DOE  

After:

• Merge Tag: {Name:3:strtolower}  
• Value: john doe  

:strtoupper  

Converts the entire output to uppercase.

Before:

• Merge Tag: {Name:3}  
• Value: John Doe  

After:

• Merge Tag: {Name:3:strtoupper}  
• Value: JOHN DOE  

:ucfirst  

Capitalizes only the first character of the output.

Before:

• Merge Tag: {Description:4}  
• Value: rocket scientist  

After:

• Merge Tag: {Description:4:ucfirst}  
• Value: Rocket scientist  

:ucwords  

Capitalizes the first character of each word.

Before:

• Merge Tag: {Job Title:5}  
• Value: senior rocket scientist  

After:

• Merge Tag: {Job Title:5:ucwords}  
• Value: Senior Rocket Scientist  

Usage: :initials   Modifier

The :initials   modifier converts a full name to initials. This is useful for displaying abbreviated names or creating avatar placeholders.

Before:

• Merge Tag: {Name:3}  
• Value: John Michael Doe  

After:

• Merge Tag: {Name:3:initials}  
• Value: JMD  

Usage: :timestamp   Modifier

The :timestamp   modifier converts valid dates into a timestamp (the number of seconds since the Unix Epoch, January 1 1970 00:00:00 GMT). This is helpful for use in combination with the [gvlogic]   shortcode.

This modifier will run the strtotime() function on the Merge Tag's content. If not a valid format, the value will be returned as -1  .

Before:

• Merge Tag: {Date:3}  
• Output: 07/07/2003  

After:

• Merge Tag: {Date:3:timestamp}  
• Output: 1057547880  

It will work with any format for the Date field (mm/dd/yyyy  , yyyy-dd-mm  , and everything in between):

Before:

• Merge Tag: {Text Field With Parseable Date:6}  
• Output: July 14, 2015, 11:49 GMT  

After:

• Merge Tag: {Text Field With Parseable Date:6:timestamp}  
• Output: 1436874540  

Notes

• The :timestamp   modifier is designed to work with Date fields, but it will work for any field, as long as the value is formatted in a way that is parsed by PHP's strtotime() function.

Usage: :human   Modifier

The :human   modifier displays dates and times in a human-readable relative format. This is useful for showing how long ago something happened.

This modifier works with Date and Time fields.

Before:

• Merge Tag: {Date Created:date_created}  
• Value: 2024-01-15 10:30:00  

After:

• Merge Tag: {Date Created:date_created:human}  
• Value: 2 weeks ago  

For Time fields:

Before:

• Merge Tag: {Appointment Time:6}  
• Value: 14:30  

After:

• Merge Tag: {Appointment Time:6:human}  
• Value: 3 hours from now  

Usage: :format:{format}   Modifier

The :format   modifier allows you to format date and time fields using PHP date format strings, which are the same format strings supported by WordPress.

This modifier works with Date fields, Time fields, and date-related merge tags like {date_created}  , {date_updated}  , {now}  , {yesterday}  , and {tomorrow}  .

Examples:

• {Date:3:format:F j, Y}   → January 15, 2024  
• {Date:3:format:m/d/Y}   → 01/15/2024  
• {Date:3:format:Y-m-d}   → 2024-01-15  
• {Time:4:format:g:i A}   → 2:30 PM  
• {Time:4:format:H:i}   → 14:30  

Notes

• To include a colon (:  ) in your format string, escape it with a backslash: {Time:4:format:H\:i\:s}   → 14:30:00  
• The :format   modifier preserves the original timezone of Date fields (no timezone offset is applied).

Usage: :explode   Modifier

The :explode   modifier converts JSON arrays or comma-separated values into a space-separated string. This is particularly useful for Multiple Select fields or other fields that store multiple values.

Before (JSON array):

• Merge Tag: {Categories:5}  
• Value: ["Science","Technology","Space"]  

After:

• Merge Tag: {Categories:5:explode}  
• Value: Science Technology Space  

Before (CSV):

• Merge Tag: {Tags:6}  
• Value: rocket,satellite,launch  

After:

• Merge Tag: {Tags:6:explode}  
• Value: rocket satellite launch  

This is especially useful when you want to use field values as CSS classes:

<div class="{Categories:5:explode,sanitize_html_class}">[...]</div>

Using Multiple Modifiers at a Time

You can combine multiple modifiers by separating them with commas. Be sure to use GravityView's modifiers first, then Gravity Forms’.

For example, if you want to use :wpautop   but you also want to URL-encode the output, you would write it like this: {Field:1:wpautop,urlencode}  

More examples:

• {Name:3:strtolower,sanitize_html_class}   - Convert to lowercase, then make safe for CSS classes
• {Description:4:maxwords:20,wpautop}   - Limit to 20 words, then add paragraph tags
• {Categories:5:explode,sanitize_html_class}   - Convert array to space-separated string, then sanitize for CSS