String Plugin Template Tags & Parameters

• String Set Tag Pair
• String Append Tag Pair
• String Prepend Tag Pair
• String Clear Tag
• String Output Tag Pair
• String Output Convenience Tag

Important: special values for glue & separator parameters
Important: using the "random" parameter to avoid plugin tag caching

---

exp:string:set

This tag will set a variable's value. It will overwrite anything that may already exist in the variable.

Parameters

• name - required - the name of the variable having its value set
• default - optional - if the tag pair is empty, the variable will be set to this instead

Usage

{exp:string:set name="title" default="{title}"}{blog_page_title}{/exp:string:set}

---

exp:string:append

This tag will add new text to the end of an existing variable. If the variable doesn't exist or is empty, this tag will act like the exp:string:set tag (separator & glue will only be inserted if the variable has text in it already).

Parameters

• name - required - the name of the variable to which we are appending text.
• separator - optional - the text to be inserted between the old text and the new text (default = "").
• glue - optional - the text to be inserted on either side of the separator (default = " "). If the separator is empty, only one instance of glue will be inserted.
• default - optional - if the tag pair is empty, this text will be appended instead.

Usage

This would store the string "Newest Blog Entry | Blog | eMarketSouth" to the "title" variable:

{exp:string:set name="title"}Newest Blog Entry{/exp:string:set}
{exp:string:append name="title" separator="|" glue="SPACE"}Blog{/exp:string:append}
{exp:string:append name="title" separator="|" glue="SPACE"}eMarketSouth{/exp:string:append}

---

exp:string:prepend

This tag will add new text to the beginning of an existing variable. If the variable doesn't exist or is empty, this tag will act like the exp:string:set tag (separator & glue will only be inserted if the variable has text in it already).

Parameters

• name - required - the name of the variable to which we are prepending text.
• separator - optional - the text to be inserted between the old text and the new text (default = "").
• glue - optional - the text to be inserted on either side of the separator (default = " "). If the separator is empty, only one instance of glue will be inserted.
• default - optional - if the tag pair is empty, this text will be prepended instead.

Usage

This would store the string "Newest Blog Entry | Blog | eMarketSouth" to the "title" variable:

{exp:string:set name="title"}eMarketSouth{/exp:string:set}
{exp:string:prepend name="title" separator="|" glue="SPACE"}Blog{/exp:string:prepend}
{exp:string:prepend name="title" separator="|" glue="SPACE"}Newest Blog Entry{/exp:string:prepend}

---

exp:string:clear

This tag will clear the value of the named variable. Just a single tag, no need to close the pair.

Parameters

• name - required - the name of the variable to clear.

Usage

This will clear the contents of the "title" variable:

{exp:string:clear name="title"}

---

exp:string:output

This tag will print the current value of the named variable. As of version 1.2.0 the value of any string variable can be output within this tag pair by putting the variable name in curly braces.

Parameters

• name - optional - the name of the variable to print.

Single Variables

• string - the value of the named variable
• <variable_name> - any named string variable

Usage

This will print the string stored in the variable "title":

{exp:string:output name="title"}{string}{/exp:string:output}

It is possible to use conditionals within the output tag:

{exp:string:output name="title"}
	{if string != ""}
		<title>{string}</title>
	{if:else}
		<title>eMarketSouth</title>
	{/if}
{/exp:string:output}

As of version 1.2.0 it is possible to output multiple variables in a single tag pair. This example will output "This is a test":

{exp:string:set name="test1"}This is{/exp:string:set}
{exp:string:set name="test2"}a test{/exp:string:set}
{exp:string:output}
	{test1} {test2}
{/exp:string:output}

---

exp:string - string output convenience tag

This short tag can be used as a single tag (not a pair) to print the value of the named variable.

Parameters

• name - required - the name of the variable to print.

Usage

this will print the string stored in the variable "title":

{exp:string name="title"}

---

Special Values for Glue & Separator Parameters

ExpressionEngine trims whitespace from parameter values, so in order to use spaces, tabs, newlines, and empty values for glue and separator parameters we need special tokens:

Parameter Values

• SPACE
• TAB
• NEWLINE
• NONE

Usage

To append a string using a newline "\n" as the separator and an empty string for glue:

{exp:string:append name="demo" separator="NEWLINE" glue="NONE"}test string{/exp:string:append}

---

Using the "Random" Parameter to Avoid Plugin Tag Caching

ExpressionEngine caches the return value for identical plugin tag calls and silently won't call the plugin the second and subsequent times. This only happens when the parameters and tag data is identical on multiple calls to the same plugin. This does not cause problems for most plugins, but will for this one. As an example, the following code will exhibit the issue:

{exp:string:set name="demo"}testing{/exp:string:set}
{exp:string name="demo"} 
{exp:string:append name="demo" separator="SPACE" glue="NONE"}123{/exp:string:append}
{exp:string name="demo"} 

It isn't (currently) documented, but ExpressionEngine provides a somewhat awkward - yet effective - solution to this problem. Plugins with the word "random" somewhere in the tag will not be cached and will get executed each time they are called. Just have a blank parameter called "random" in the tag to solve this issue:

{exp:string name="demo" random}

Price: $9.95 per site - buy now at devot-ee.com

Compatibility:

• ExpressionEngine 1.6
• ExpressionEngine 2.x

Most Recent Version:

• EE 1.6: String Plugin 1.2.0
  July 28, 2010
• EE 2.x: String Plugin 1.2.0
  July 28, 2010

• Template Tags & Parameters
• Code Examples