Custom Methods

Note: By default, you can separate arguments with a pipe (|) and lists with a comma (,), but you can easily change that. Take a look at the parameters page for more details.

allow_eecode

Allows EE code in the tagdata to be executed.

• query: Allow exp:query tags? Can be "yes" or "no", default is "no"
• embed: Allow embed= tags? Can be "yes" or "no", default is "no"

The following would execute any EE code that was passed in through the custom field:

If {custom_field} was a variable representing an entry custom field that contained {path='contact'}, then the tag would return the url to the contact page.

The following would permit embeds and query tags:

alpha_to_int

Converts alphabetic characters to an integer representation. This is the opposite of the int_to_alpha method.22

• zero based: Should A = 0 ("no") or A = 1 ("yes")? The default is "no", which means A = 1, B = 2, etc

Returns:

1
26
218
---------------
0
25
217

alternate

An alternative to the switch param that preserves whitespace and can be prefixed. Easily alternates between strings.

Results in:

amped

Replaces all & that are not entities with &.

Returns:

Cause & Effect

auto_link

Auto-links URLs.

• target: Optionally set the target attribute to open in a new window by setting to _blank
• type: Can be all (links both URLs and email addresses), url (only links URLs), or email (only links email addresses). Defaults to all.
• show_protocol: Can be yes or no. The default is yes. If set to no, then the anchor text will not include the 'http://' or 'https://' part of the URL (the href= attribute will still include the protocol part of the URL).

The following would auto-link all of the URLs passed in through the custom field

Returns:

This would auto-link the URLs and have them open in a new window:

Returns:

auto_typography

From the EE docs:

This function takes a string of text and returns typographically correct XHTML. It’s primary modifications are

• turns double spaces into paragraphs.
• adds line breaks where there are single spaces.
• turns single and double quotes into curly quotes.
• turns three dots into ellipsis.
• turns double dashes into em-dashes."

Returns:

Or in human-readable format:

backspace

Removes a specified number of characters from the end of a string.

• characters: The number of characters to remove from the end of the string.

The following example removes the last 7 characters from the string:

Returns:

encode_email_bulk

Encodes all email addresses in script or human readable form. The 'fallback' option will script-encode the email address, and give a human-readable fallback version.

• type: Can be script, noscript, or fallback. The default is script.
• at replacement: If using the noscript or fallback type, this sub parameter specifies the text to use for the human-readable @ character. The default is at.
• dot replacement: If using the noscript or fallback type, this sub parameter specifies the text to use for the human-readable . character. The default is dot.
• opener: If using the noscript or fallback type, this sub parameter specifies the opening text to wrap the anchor element's text in. The default is (.
• closer: If using the noscript or fallback type, this sub parameter specifies the closing text to wrap the anchor element's text in. The default is ).

script example

This will encode all of the email addresses using the native EE email encoding method:

Result:

Result HTML:

fallback example

This will use the native EE email encoding method too, but it will provide the friendlier human-readable version of the email address (like Example (example at example dot com)), instead of the cryptic .(JavaScript must be enabled to view this email address) message if JavaScript is not enabled.

Result:

Result HTML:

noscript example

This method converts all email anchor links and text email addresses into a human-readable email address. You can customize the output format using the sub parameters.

Result:

Result HTML:

encode_email_noscript

Creates a human-readable "encoded" email address, without JavaScript.

Returns:

blah at example dot com

encode_email_script

From the EE docs:

"This function encodes email addresses with Javascript, to assist in prevention of email harvesting by bots."

• title: The text to use as the title of the email link. Defaults to ''
• anchor: Whether or not a clickable link is created for the email address. Can be "yes" or "no", default is "yes"

Returns:

expand_escaped

Expands unexpanded escape sequences like \n and \t.

Returns:

This
is
a               test

external_links

Adds a target="_blank" attribute to all external links (links to remote domains). It optionally allows certain domains to be ignored, and has the ability to add one or more HTML classes to any external links (in addition to the target="_blank" attribute). It works with http://, https://, and // (protocol relative) links.

• ignored domains: Domains to ignore. These will not be flagged as external domains. If there are multiple domains to ignore, delimit them with the array_delimiter (defaults to ')
• add class(es): One or more HTML classes to assign to the link. If the link already has one or more classes, they will automatically be combined.
• ignore current domain: Whether or not to ignore the current domain. If set to no, fully quantified links for the current site (links that start with http://, https://, or //) will be treated as external links. The default is yes.

Returns:

Note: All domain names automatically add a rule to ignore the domain name with a www. prefix, in addition to the specified domain name. So if my current domain is causingeffect.com, then www.causingeffect.com would also be ignored automatically. This holds true for both the current domain (sub parameter 3) and ignored domains (sub parameter 1).

format_characters

From the EE docs:

"This function performs the character transformation portion of the XHTML typography only, i.e. curly quotes, ellipsis, ampersand, etc."

highlight

Highlights a given phrase or phrases in the tagdata text.

• phrase: The phrase(s) to search for. If there are multiple phrases, delimit them with the array_delimiter
• format: The format(s) to replaced the found instances of the phrase(s). If there are multiple formats, delimit them with the array_delimiter. It is possible to have multiple phrases and 1 format, or multiple phrases and the same number of formats. The default value is: <span class="highlight">\1</span>. The \1 will be replaced with the found phrase
• html: Can be "yes" or "no", default is "yes"

The following will wrap any found instances of the word foo in the default span with a class of "highlight":

The following will wrap any found instances of the words foo, bar, and blah in a span with a class of "terms"

int_to_alpha

Converts an integer to an alphabetic representation, like A-Z, AA-ZZ, etc. This is the opposite of the alpha_to_int method.

• zero based: Should 0 = A ("yes") or 1 = A ("no")? The default is "no", which means 1 = A, 2 = B, etc

Returns:

Y
HI
---------------
A
Z
HJ

int_to_roman

Converts an integer to a Roman numeral. This is the opposite of the roman_to_int method.

Returns:

MCMX
MCMLIV
MCMXC

lowercase

Make a string lowercase. This will automatically work with multi-byte strings if possible (if the mb_strtolower function is available to PHP).

Returns: mary had a little lamb in são paulo and she loved it so

math_lite

A simple matheval function. Can handle simple numeric calculations.

Return 0 (zero) for empty values?: If set to yes, if the data is invalid or empty, the number zero (0) will be returned instead of the default empty data. The default is no.

Returns: 10.25

Returns: 1.0833333333333

In the following example, the data is invalid so it returns empty:

Returns:

For the below example, the return zero for empty values option is set to yes, so a zero is returned instead of an empty return value:

Returns: 0

markdown

Gets (X)HTML from a Markdown Extra markup string.

URL: http://michelf.com/projects/php-markdown/extra/

• html: Should the output be HTML? A value of 'yes' will produce HTML (default), a value of 'no' will produce XHTML.

Returns:

php

Evaluates the string as PHP.

This method was inspired by the old first-party add-on, but with several added benefits:

• The output is actually returned where you called the tag in your template (as opposed to always being returned at the top).
• You can open and close PHP tags multiple times.
• You can nest the tags and leverage variable prefixing.

Note: This method will allow anyone with coding access to your templates to have full access to the power of PHP (in other words, they can play God with your server). You can optionally disable this method in your config settings.

Returns:

Finally, PHP can be used in templates!

Pseudo Tags

If you want to get around using early parse order (or because you prefer it), you can use {php} to represent an opening php tag and {/php} to represent a closing php tag.

Returns:

Today (2016-01-13) is a good day.

Note: The above example would normally reflect the current date, but this page is static, so the example is too. ;)

preg_rep

Simplified preg_replace method. This method is much like the "replace" method, except you can use regex.

• find: The text to find. To pass in multiple find strings, delimit the values with the array_delimiter. The default value is ''
• replace: The text to replace the found strings. To pass in multiple find strings, delimit the values with the array_delimiter. The default value is ''
• modifier: If you would like to pass in a modifier, like 'Usi'

Returns:

The cat jumped over the spoon.

remove_ee_vars

Removes EE variable tags that have no spaces in them. Ex: {blah}

Returns:

Blah blah  blah.

remove_html

Will remove all HTML. No prisoners.

Returns:

This is some html.

remove_tags

Will remove the specified tags.

• tags: One or more tags to remove (can be delimited with the array_delimiter)
• strip content: Whether or not to remove the content within the stripped tags. Can be "yes" or "no", default is "no"

Returns:

Returns:

remove_tags_except

Will remove all tags except the ones specified.

• tags: One or more tags to keep (can be delimited with the array_delimiter)

Returns:

replace

Find and replace.

• find: The text to find. To pass in multiple find strings, delimit them with the array_delimiter. The default value is ''
• replace: The text to replace the found strings. To pass in multiple find strings, delimit them with the array_delimiter. The default value is ''

Returns:

The cat jumped over the spoon.

replace_last

Replace the last occurrence of a string in a string.

• find: The text to find.
• replace: The text to replace the found strings with.

Returns:

boom, pow, pow

roman_to_int

Converts a Roman numeral to an integer. This is the opposite of the int_to_roman method.

Returns:

1910
1954
1990

sentence_case

Converts a string to sentence case.

Returns:

This should *really* be a sentence!

smart

Easy to implement typography helper. Alias for the format_characters method.

Returns:

smartypants

SmartyPants Typographer easily translates plain ASCII punctuation characters into "smart" typographic punctuation HTML entities.

URL: http://michelf.com/projects/php-smartypants/typographer/

Returns:

stripos

Find position of first occurrence of a string. The haystack is the string passed in as tagdata. This method differs from the native PHP stripos function, because it returns -1 if the string is not found, as opposed to the native response of FALSE. Unlike the strpos, stripos is case-insensitive.

PHP Docs URL: http://php.net/manual/en/function.stripos.php

• needle: If needle is not a string, it is converted to an integer and applied as the ordinal value of a character.
• offset: The optional offset parameter allows you to specify which character in haystack to start searching. The position returned is still relative to the beginning of haystack. Defaults to 0.

Returns: -1

Returns: 4

strpos

Find position of first occurrence of a string. The haystack is the string passed in as tagdata. This method differs from the native PHP strpos function, because it returns -1 if the string is not found, as opposed to the native response of FALSE.

PHP Docs URL: http://php.net/manual/en/function.strpos.php

• needle: If needle is not a string, it is converted to an integer and applied as the ordinal value of a character.
• offset: The optional offset parameter allows you to specify which character in haystack to start searching. The position returned is still relative to the beginning of haystack. Defaults to 0.

Returns: -1

Returns: 0

strripos

Find position of last occurrence of a string in a string. Unlike strrpos, strripos is case-insensitive. The haystack is the string passed in as tagdata. This method differs from the native PHP strpos function, because it returns -1 if the string is not found, as opposed to the native response of FALSE.

PHP Docs URL: http://php.net/manual/en/function.strripos.php

• needle:
• offset: If specified, search will stop this number of characters counted from the beginning of the string. If the value is negative, search will instead start from that many characters from the end of the string.

Returns: 2

strrpos

Returns the numeric position of the last occurrence of needle in the haystack string. The haystack is the string passed in as tagdata. This method differes from the native PHP strpos function, because it returns -1 if the string is not found, as opposed to the native response of FALSE.

PHP Docs URL: http://php.net/manual/en/function.strrpos.php

• needle:
• offset: If specified, search will stop this number of characters counted from the beginning of the string. If the value is negative, search will instead start from that many characters from the end of the string.

Returns: 17

Returns: 27

Returns: -1

swap_breaks

The ExpressionEngine® template parser tends to leave a lot of extra line breaks in rendered pages. This method allows you to whittle down those line breaks and tighten up your output.

• threshold: This is the minimum number of line breaks that need to be present before replacing them. Defaults to 2.
• replace: This is the number of line breaks to reduce to. Defaults to 1.

Here’s an example using the default parameters (which is the same as swap_breaks="2|1"). If there are two or more consecutive line breaks, they will be reduced to one line break:

Returns:

Here’s the same example, but using custom parameters 3|2. Anytime there are three or more line breaks, they will be reduced to two:

Returns:

textile

Gets XHTML from a Textile-markup string.

URL: http://textile.thresholdstate.com/

Returns:

to_title

Converts a url_title to title case.

• separator: The url_title separator. Defaults to the EE word_separator config value.

Note: For the following examples, keep in mind that the default word_separator is -.

Returns: My Article Title

Returns: My Article Title

truncate

Truncates text. Cuts a string to the length of $length and replaces the last characters with the ending if the text is longer than length.

• length: Length of the returned string, including the ending. Defaults to 500.
• ending: The text that will be appended to the truncated string.
• exact: If 'yes', the text will be truncated mid-word. The default is 'no'.
• html: If 'yes', HTML tags will be handled correctly. The default is 'yes'.

Returns:

Returns:

twitterfy

Auto-links Twitter content.

• links @username to the user's Twitter profile page
• links regular links
• links hashtags to a Twitter search of that hashtag

Returns:

uppercase

Make a string uppercase. This will automatically work with multi-byte strings if possible (if the mb_strtoupper function is available to PHP).

Returns: MARY HAD A LITTLE LAMB IN SÃO PAULO AND SHE LOVED IT SO

url_title

Converts a string to an EE url_title.

• separator: The word separator. Can be either - or _. Defaults to the EE word_separator config value.
• lowercase: Should the url_title be lowercase? Defaults to 'yes'

Note: For the following examples, keep in mind that the default word_separator for this site is -.

Returns: my-article-title

utf8tohtml

When using UTF-8 as a charset, htmlentities will only convert 1-byte and 2-byte characters. Use this method if you also want to convert 3-byte and 4-byte characters.

• encode tags: Encode the html tags? Defaults to 'no'

You may or may not see the tagdata characters in your editor; they are an mdash and a right single quote.

Returns: — ’

word_limit

Limits text to a maximum number of words.

• words: The maximum number of words. Defaults to 500

Returns:

Note: Keep in mind that this method always appends … to the end of the string. The truncate method is overall much more robust and flexible.

xss_clean

The built in ExpressionEngine® XSS (cross-site scripting) sanitization method.

Returns: