Skip to main content
Contact Support

substr Field Modifier- A Closer Look

Ryan J.

Overview

The substr (substring) field modifier can be used to extract a portion of text from a merge field (instead of rendering the entire text).  The basic syntax is as follows:

{$MyMergeField|substr:start:length}

Like all other field modifiers, the substr field modifier is activated by appending it to the merge field with the pipe character (|).  The modifier can take in 2 parameters:

  • Start position: This indicates the index* of where the substring should start
  • String length (optional): This indicates how long the string should be.  If no value is provided, the modifier will return all characters from the start position to the end of the string.

*NOTE: The starting position uses a zero-based index.  This means that if you want to start from the first character of the string, the index is 0; if you wanted to start from the second character, the index would be 1; if you wanted to start from the third character, the index would be 2, etc.

 

Use Cases

There are several instances where this modifier can be utilized.  For example, if you only wanted to print the first three characters of a month name that is passed into the modifier, you could use the following:

{$month|substr:0:3}

In this example, if "January" is passed into the $month merge field, the final document will render "Jan" instead.

Using Dynamic Parameters

In addition to using static values in the parameters, you may find yourself wanting to extract text starting from a specific character within the string instead of an index. In such an event, we would need to calculate the indexes and/or lengths.

For example, your merge data source passes in full names of individuals in the format of "FirstName LastName", but you only want to render the first names.

First, we would need to find the position of the space character.  This can be done by using the strpos (string position) field modifier:

{$_space_pos = $name|strpos:" "}
  • We create a new merge field/variable called $_space_pos.  This will be used to store the index of the position of the space from the $name merge field
  • The strpos field modifier is used on the $name merge field to find the index of the space character (indicated in the strpos parameter)

Now that we have the index value of the space, we can use it to extract just the first name from the merge field:

{$_space_pos = $name|strpos:" "}
{$name|substr:0:$_space_pos}

Let's step through the code using an example of "Rita Book" being passed into the $name merge field:

  • First, we determine the index of the space character.  This should be 4: 
    Rita Book
    012345678

  • Once we find the index, we store that value in the $_space_pos field modifier.

  • We then render the $name field and use the substr field modifier to indicate we want to start at the first (0) position of the $name field and pull 4 characters (as indicated by the $_space_pos field)
  • The final output should be: 
    Rita

Related articles