TextHelper¶

class TextHelper(View $view, array $settings = array())¶

The TextHelper contains methods to make text more usable and friendly in your views. It aids in enabling links, formatting urls, creating excerpts of text around chosen words or phrases, highlighting key words in blocks of text, and to gracefully truncating long stretches of text.

Changed in version 2.1: Several of TextHelper methods have been moved into String class to allow easier use outside of the View layer. Within a view, these methods are accessible via the TextHelper class and you can called it as you would call a normal helper method: $this->Text->method($args);.

TextHelper::autoLinkEmails(string $text, array $options=array())¶

Parameters:	$text (string) – The text to convert. $options (array) – An array of html attributes for the generated links.

Adds links to the well-formed email addresses in $text, according to any options defined in $htmlOptions (see HtmlHelper::link()).:

$myText = 'For more information regarding our world-famous pastries and desserts, contact info@example.com';
$linkedText = $this->Text->autoLinkEmails($myText);

Output:

For more information regarding our world-famous pastries and desserts,
contact <a href="mailto:info@example.com">info@example.com</a>

Changed in version 2.1: In 2.1 this method automatically escapes its input. Use the escape option to disable this if necessary.

TextHelper::autoLinkUrls(string $text, array $htmlOptions=array())¶

Parameters:	$text (string) – The text to convert. $htmlOptions (array) – An array html attributes for the generated links

Same as in autoLinkEmails(), only this method searches for strings that start with https, http, ftp, or nntp and links them appropriately.

Changed in version 2.1: In 2.1 this method automatically escapes its input. Use the escape option to disable this if necessary.

TextHelper::autoLink(string $text, array $htmlOptions=array())¶

Parameters:	$text (string) – The text to autolink. $htmlOptions (array) – An array html attributes for the generated links

Performs the functionality in both autoLinkUrls() and autoLinkEmails() on the supplied $text. All URLs and emails are linked appropriately given the supplied $htmlOptions.

Changed in version 2.1: In 2.1 this method automatically escapes its input. Use the escape option to disable this if necessary.

TextHelper::highlight(string $haystack, string $needle, array $options = array())¶

Parameters:	$haystack (string) – The string to search. $needle (string) – The string to find. $options (array) – An array of options, see below.

Highlights $needle in $haystack using the $options['format'] string specified or a default string.

Options:

‘format’ - string The piece of html with that the phrase will be highlighted
‘html’ - bool If true, will ignore any HTML tags, ensuring that only the correct text is highlighted

Example:

// called as TextHelper
echo $this->Text->highlight($lastSentence, 'using', array('format' => '<span class="highlight">\1</span>'));

// called as String
App::uses('String', 'Utility');
echo String::highlight($lastSentence, 'using', array('format' => '<span class="highlight">\1</span>'));

Output:

Highlights $needle in $haystack <span class="highlight">using</span>
the $options['format'] string specified  or a default string.

TextHelper::stripLinks($text)¶: Strips the supplied $text of any HTML links.

TextHelper::truncate(string $text, int $length=100, array $options)¶

Parameters:	$text (string) – The text to truncate. $length (int) – The length to trim to. $options (array) – An array of options to use.

Cuts a string to the $length and adds a suffix with 'ellipsis' if the text is longer than $length. If 'exact' is passed as false, the truncation will occur after the next word ending. If 'html' is passed as true, html tags will be respected and will not be cut off.

$options is used to pass all extra parameters, and has the following possible keys by default, all of which are optional:

array(
    'ellipsis' => '...',
    'exact' => true,
    'html' => false
)

Example:

// called as TextHelper
echo $this->Text->truncate(
    'The killer crept forward and tripped on the rug.',
    22,
    array(
        'ellipsis' => '...',
        'exact' => false
    )
);

// called as String
App::uses('String', 'Utility');
echo String::truncate(
    'The killer crept forward and tripped on the rug.',
    22,
    array(
        'ellipsis' => '...',
        'exact' => false
    )
);

Output:

The killer crept...

Changed in version 2.3: ending has been replaced by ellipsis. ending is still used in 2.2.1

TextHelper::tail(string $text, int $length=100, array $options)¶

Parameters:	$text (string) – The text to truncate. $length (int) – The length to trim to. $options (array) – An array of options to use.

Cuts a string to the $length and adds a prefix with 'ellipsis' if the text is longer than $length. If 'exact' is passed as false, the truncation will occur before the next word ending.

$options is used to pass all extra parameters, and has the following possible keys by default, all of which are optional:

array(
    'ellipsis' => '...',
    'exact' => true
)

New in version 2.3.

Example:

// called as TextHelper
echo $this->Text->tail(
    'I packed my bag and in it I put a PSP, a PS3, a TV, a C# program that can divide by zero, death metal t-shirts',
    70,
    array(
        'ellipsis' => '...',
        'exact' => false
    )
);

// called as String
App::uses('String', 'Utility');
echo String::tail(
    'I packed my bag and in it I put a PSP, a PS3, a TV, a C# program that can divide by zero, death metal t-shirts',
    70,
    array(
        'ellipsis' => '...',
        'exact' => false
    )
);

Output:

...a TV, a C# program that can divide by zero, death metal t-shirts

TextHelper::excerpt(string $haystack, string $needle, integer $radius=100, string $ellipsis="...")¶

Parameters:	$haystack (string) – The string to search. $needle (string) – The string to excerpt around. $radius (int) – The number of characters on either side of $needle you want to include. $ellipsis (string) – Text to append/prepend to the beginning or end of the result.

Extracts an excerpt from $haystack surrounding the $needle with a number of characters on each side determined by $radius, and prefix/suffix with $ellipsis. This method is especially handy for search results. The query string or keywords can be shown within the resulting document.:

// called as TextHelper
echo $this->Text->excerpt($lastParagraph, 'method', 50, '...');

// called as String
App::uses('String', 'Utility');
echo String::excerpt($lastParagraph, 'method', 50, '...');

Output:

... by $radius, and prefix/suffix with $ellipsis. This method is
especially handy for search results. The query...

TextHelper::toList(array $list, $and='and')¶

Parameters:	$list (array) – Array of elements to combine into a list sentence. $and (string) – The word used for the last join.

Creates a comma-separated list where the last two items are joined with ‘and’.:

// called as TextHelper
echo $this->Text->toList($colors);

// called as String
App::uses('String', 'Utility');
echo String::toList($colors);

Output:

red, orange, yellow, green, blue, indigo and violet

TextHelper¶

Table of Contents

Page contents