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
{exp:ce_str:ing strtolower alpha_to_int}Z{/exp:ce_str:ing}
{exp:ce_str:ing strtolower alpha_to_int}HJ{/exp:ce_str:ing}
---------------
{exp:ce_str:ing strtolower alpha_to_int="yes"}A{/exp:ce_str:ing}
{exp:ce_str:ing strtolower alpha_to_int="yes"}Z{/exp:ce_str:ing}
{exp:ce_str:ing strtolower alpha_to_int="yes"}HJ{/exp:ce_str:ing}
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.
<p>{alternate="foo|bar|baz"}<br>
{alternate="foo|bar|baz"}<br>
{alternate="foo|bar|baz"}<br>
{alternate="foo|bar|baz"}<br>
{alternate="foo|bar|baz"}<br>
{alternate="foo|bar|baz"}</p>
{/exp:ce_str:ing}
Results in:
bar<br>
baz<br>
foo<br>
bar<br>
baz</p>
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), oremail
(only links email addresses). Defaults toall
. - show_protocol: Can be
yes
orno
. The default isyes
. If set tono
, then the anchor text will not include the 'http://' or 'https://' part of the URL (thehref=
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."
"Lorem ipsum" dolor sit amet', consectetur adipiscing elit... In fringilla elit--id est congue--non malesuada diam viverra.
Mauris libero libero, lacinia id accumsan ac, dapibus id lacus 7-10. In sit amet lectus arcu, ac pretium odio.
{/exp:ce_str:ing}
Returns:
<p>Mauris libero libero, lacinia id accumsan ac, dapibus id lacus 7-10. In sit amet lectus arcu, ac pretium odio.</p>
Or in human-readable format:
Mauris libero libero, lacinia id accumsan ac, dapibus id lacus 7-10. In sit amet lectus arcu, ac pretium odio.
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
, orfallback
. The default isscript
. - at replacement: If using the
noscript
orfallback
type, this sub parameter specifies the text to use for the human-readable@
character. The default isat
. - dot replacement: If using the
noscript
orfallback
type, this sub parameter specifies the text to use for the human-readable.
character. The default isdot
. - opener: If using the
noscript
orfallback
type, this sub parameter specifies the opening text to wrap the anchor element's text in. The default is(
. - closer: If using the
noscript
orfallback
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:
Ut wisi <a href="mailto:example@example.com">Example</a> enim ad minim veniam, quis nostrud test@example.com
{/exp:ce_str:ing}
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.
Ut wisi <a href="mailto:example@example.com">Example</a> enim ad minim veniam, quis nostrud test@example.com
{/exp:ce_str:ing}
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.
Ut wisi <a href="mailto:example@example.com">Example</a> enim ad minim veniam, quis nostrud test@example.com.
{/exp:ce_str:ing}
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 withhttp://
,https://
, or//
) will be treated as external links. The default isyes
.
<p><a href="/">internal URI example</a></p>
<p><a href="http://www.example.com" class="external example">external HTTP URI</a></p>
<p><a href="mailto:example@example.com">email example</a></p>
<p><a href="//example.com" target="_top">external protocol relative URI</a></p>
<p><a href="https://example.com">external HTTPS URI</a></p>
<p><a href="http://ignore.example.com">ignored external HTTPS URI</a></p>
<p><a href="{path='about'}">current domain (not external)</a></p>
{/exp:ce_str:ing}
Returns:
<p><a href="http://www.example.com" class="external example foreign" target="_blank">external HTTP URI</a></p>
<p><a href="mailto:example@example.com">email example</a></p>
<p><a href="//example.com" target="_blank" class="external foreign">external protocol relative URI</a></p>
<p><a href="https://example.com" target="_blank" class="external foreign">external HTTPS URI</a></p>
<p><a href="http://ignore.example.com">ignored external HTTPS URI</a></p>
<p><a href="https://www.causingeffect.com/about">current domain (not external)</a></p>
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
{exp:ce_str:ing int_to_alpha}25{/exp:ce_str:ing}
{exp:ce_str:ing int_to_alpha}217{/exp:ce_str:ing}
---------------
{exp:ce_str:ing int_to_alpha="yes"}0{/exp:ce_str:ing}
{exp:ce_str:ing int_to_alpha="yes"}25{/exp:ce_str:ing}
{exp:ce_str:ing int_to_alpha="yes"}217{/exp:ce_str:ing}
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.
{exp:ce_str:ing int_to_roman}1954{/exp:ce_str:ing}
{exp:ce_str:ing int_to_roman}1990{/exp:ce_str:ing}
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.
<?php echo 'Finally, PHP can be used in templates!'; ?>
{/exp:ce_str:ing}
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.
Today ({php} echo date("Y-m-d"); {/php}) is a {php}
//create mood options array
$moods = array( 'bad', 'good', 'fantastic', 'terrible', 'blah' );
//randomly select a mood and echo it
echo $moods[ mt_rand( 0, count( $moods ) - 1 ) ];
{/php} day.
{/exp:ce_str:ing}
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.
{exp:ce_str:ing roman_to_int}MCMLIV{/exp:ce_str:ing}
{exp:ce_str:ing roman_to_int}MCMXC{/exp:ce_str:ing}
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:
<!-- start slipsum code -->
<p>Now that we know who you are, I know who I am. I'm not a mistake! It all makes sense!</p>
<p>In a comic, you know how you can tell who the arch-villain's going to be? He's the exact opposite of the hero. And most times they're friends, like you and me!</p>
<p>I should've known way back when... You know why, David? Because of the kids. They called me Mr Glass.</p>
<!-- end slipsum code -->
{/exp:ce_str:ing}
Returns:
<p>Now that we know who you are, I know who I am. I'm not a mistake! It all makes sense!</p>
<p>In a comic, you know how you can tell who the arch-villain's going to be? He's the exact opposite of the hero. And most times they're friends, like you and me!</p>
<p>I should've known way back when... You know why, David? Because of the kids. They called me Mr Glass.</p>
<!-- end slipsum code -->
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:
<!-- start slipsum code -->
<p>Now that we know who you are, I know who I am. I'm not a mistake! It all makes sense!</p>
<p>In a comic, you know how you can tell who the arch-villain's going to be? He's the exact opposite of the hero. And most times they're friends, like you and me!</p>
<p>I should've known way back when... You know why, David? Because of the kids. They called me Mr Glass.</p>
<!-- end slipsum code -->
{/exp:ce_str:ing}
Returns:
<p>Now that we know who you are, I know who I am. I'm not a mistake! It all makes sense!</p>
<p>In a comic, you know how you can tell who the arch-villain's going to be? He's the exact opposite of the hero. And most times they're friends, like you and me!</p>
<p>I should've known way back when... You know why, David? Because of the kids. They called me Mr Glass.</p>
<!-- end slipsum code -->
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: