HTML Helper

The HTML helper assists in calling various elements such as stylesheet, javascript, image links and anchor links into position.

'specialchars' is similar to PHP's htmlspecialchars() function. However, there are some small differences:

• It will automatically use the UTF-8 character set in conversion (instead of ISO-8859-1).
• It will automatically translate both single and double quotes to HTML entities (instead of only double quotes).
• It provides built-in fallback functionality for not double encoding existing HTML entities (for PHP versions older than 5.2.3).

The two arguments are:

• [string] The string you want to encode
• [boolean] Do you want to encode existing HTML entities? – TRUE by default

Example:

$string = '<p>"I\'m hungry"&mdash;Cookie Monster said.</p>';
echo html::specialchars($string);

It will result in the following HTML:

<p>"I'm hungry"—Cookie Monster said.</p>

When setting the second parameter to FALSE, existing HTML entities are preserved. Look closely at —.

echo html::specialchars($string, FALSE);

<p>"I'm hungry"—Cookie Monster said.</p>

'anchor' creates a HTML anchor (<a href=””></a>), linking an internal page or external site automatically.

The four arguments are:

• [string] An internal or external page that you would like to link to
• [string] The title you would like to have show up as the hyperlink
• [array] Attributes to add to your anchor
• [string] The protocol your link will use: 'ftp', 'irc', etc. – This is only necessary if it's an internal page with a non-absolute link for the first argument and you need to change the protocol from 'http'

Example 1:

echo html::anchor('home/news', 'Go to our news section!');

It will result in HTML as:

<a href="http://localhost/home/news">Go to our news section!</a>

Example 2:

echo html::anchor('irc://irc.freenode.net/kohana', 'Join us on IRC!', array('style'=>'font-size: 20px;'));

It will result in HTML as:

<a href="irc://irc.freenode.net/kohana" style="font-size: 20px;">Join us on IRC!</a>

Similar to 'anchor', 'file_anchor' creates a HTML anchor (<a href=””></a>) linking to non-Kohana resources. Therefore, it will always prefix the site's URL to the path of your file.

The four arguments are:

• [string] An internal file that you would like to link to
• [string] The title you would like to have show up as the hyperlink
• [array] Attributes to add to your anchor
• [string] The protocol your link will use: 'ftp', 'irc', etc. – This is only necessary if you need to change the protocol from 'http'

Example 1:

echo html::file_anchor('media/files/2007-12-magazine.pdf', 'Check out our latest magazine!');

It will result in HTML as:

<a href="http://localhost/media/files/2007-12-magazine.pdf">Check out our latest magazine!</a>

Example 2:

echo html::file_anchor('pub/index.php', 'The Public Linux Archive', array('id'=>'id432'), 'ftp');

It will result in HTML as:

<a href="ftp://localhost/pub/index.php" id="id432">The Public Linux Archive</a>

Similar to 'anchor', but accepts the protocol attribute first instead of last.

The four arguments are:

• [string] The protocol your link will use: 'ftp', 'irc', etc. This is only necessary if it's an internal page with a non-absolute link for the first argument and you need to change the protocol from 'http'
• [string] An internal or external page that you would like to link to
• [string] The title you would like to have show up as the hyperlink
• [array] Attributes to add to your anchor

Example:

echo html::panchor('irc', '/kohana', 'Join us on our custom IRC!');

It will result in HTML as:

<a href="irc://localhost/kohana">Join us on our custom IRC!</a>

anchor_array($array) create an array of anchors from an array of link/title pairs. It takes:

• [array] link/title pairs

Example:

echo Kohana::debug(html::anchor_array(array('home/news' => 'Go to our news section!', 'home/about' => 'Go to the about page')));

It will result as:

(array) Array
(
    [0] => <a href="/kohana/index.php/home/news">Go to our news section!</a>
    [1] => <a href="/kohana/index.php/home/about">Go to the about page</a>
)

'email($email)' generates an obfuscated version of an email address. It escapes all characters of the e-mail address into HTML, hex or raw randomly to help prevent spam and e-mail harvesting. It takes:

• [string] E-mail address

Example:

echo Kohana::debug(html::email('[email protected]'));

It could result as:

(string) test@mydomain.com

'mailto' prints a <a href=“mailto:”></a> tag but escapes all characters of the e-mail with the above method.

The three arguments are:

• [string] E-mail address
• [string] The title you would like to have show up as the hyperlink
• [string or array] Attributes to add to your anchor

Example:

echo html::mailto('[email protected]');

It will result in HTML as:

<a href="&#109;&#097;&#105;&#108;&#116;&#111;&#058;i&#x6e;fo&#x40;&#101;&#x78;&#x61;mp&#108;e&#x2e;&#x63;&#x6f;&#109;">i&#x6e;fo&#x40;&#101;&#x78;&#x61;mp&#108;e&#x2e;&#x63;&#x6f;&#109;</a>

'meta($tag, $value = NULL)' creates a meta tag.

The two arguments are:

• [string|array] tag name, or an array of tags
• [string] tag “content” value - default NULL
• returns [string] the meta tag(s)

Example:

echo html::meta('generator', 'Kohana 2.2');
echo html::meta(array('generator' => 'Kohana 2.2', 'robots' => 'noindex,nofollow'));

It will result in HTML as:

<meta name="generator" content="Kohana 2.2" />
 
<meta name="generator" content="Kohana 2.2" />
<meta name="robots" content="noindex,nofollow" />

'stylesheet' calls CSS files internally and will suffix .css if it is not already present. It supports full absolute URL.

The three arguments are:

• [string or array] Either a string with the file's location or an array of files
• [string or array] Media type such as 'screen', 'print' or 'aural'
• [boolean] Set to TRUE if you want to have the index.php file included in the link – This makes the difference between processing the request through Kohana (usually a media controller) or simply calling the file with an absolute path

Example:

echo html::stylesheet(array
(
    'media/css/default',
    'media/css/menu',
    'http://developer.yahoo.com/yui/build/reset-fonts-grids/reset-fonts-grids.css'
),
array
(
    'screen',
    'print',
    'print'
), FALSE);

It will result in HTML as:

<link rel="stylesheet" type="text/css" href="http://localhost/media/css/default.css" media="screen" />
<link rel="stylesheet" type="text/css" href="http://localhost/media/css/menu.css" media="print" />
<link rel="stylesheet" type="text/css" href="http://developer.yahoo.com/yui/build/reset-fonts-grids/reset-fonts-grids.css" media="print" />

'link' calls files such as feeds internally. Will render the <link> tag. Linking to stylesheets also uses the <link> tag but the html::stylesheet() helper can be used for those.

Arguments:

• [string or array] Either a string with the file's location or an array of files
• [string or array] Either a string or array with values for the 'rel' attribute (e.g. stylesheet, alternate)
• [string or array] Either a string or array with values for the 'type' attribute (application/rss+xml etc.)
• [boolean] set to TRUE to specify the suffix of the file, defaults to FALSE
• [string or array] Either a string or array with values for the 'media' attribute (print, screen etc.)
• [boolean] Set to TRUE if you want to have the index.php file included in the link – This makes the difference between processing the request through Kohana (usually a media controller) or simply calling the file with an absolute path

Example:

echo html::link(array
(
    'welcome/home/rss',
    'welcome/home/atom'
),
'alternate',
array('application/rss+xml','application/atom+xml')
, FALSE);

It will result in HTML as:

<link rel="alternate" type="application/rss+xml" href="http://localhost/welcome/home/rss" />
<link rel="alternate" type="application/atom+xml" href="http://localhost/welcome/home/atom" />

'script' calls JavaScript files internally and will suffix .js if not present in your file call. It supports full absolute URL.

The two arguments are:

• [string or array] Either a string with the file's location or an array of files
• [boolean] Set to TRUE if you want to have the index.php file included in the link – This makes the difference between processing the request through Kohana (usually a media controller) or simply calling the file with an absolute path

Example:

echo html::script(array
(
    'media/js/login',
    'media/js/iefixes.js',
    'http://ajax.googleapis.com/ajax/libs/jquery/1.3.1/jquery.min.js'
), FALSE);

It will result in HTML as:

<script type="text/javascript" src="http://localhost/media/js/login.js"></script>
<script type="text/javascript" src="http://localhost/media/js/iefixes.js"></script>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.1/jquery.min.js"></script>

'image' creates a 'img' HTML tag.

There are three arguments:

• [string or array] A string to specify the image 'src' attribute or an array of attributes
• [string or array] A string to specify the 'alt' attribute or an array of attributes
• [boolean] Set to TRUE if you want to have '/index.php/' included in the link (to use views to serve images using Kohana)

Example 1:

echo html::image('media/images/thumbs/01.png');

It will result in HTML as:

<img src="http://localhost/media/images/thumbs/01.png" />

echo html::image(array('src' => 'media/images/thumbs/01.png', 'width' => '100', 'height' => 100), array('alt' => 'Thumbnail', 'class' => 'noborder'));

<img src="http://localhost/media/images/thumbs/01.png" width="100" height="100" alt="Thumbnail" class="noborder"/>

Example 2 (with html::anchor and lightbox):

echo html::file_anchor('media/images/01.png', html::image('media/images/thumbs/01.png'), array('rel'=>'lightbox'));

It will result in HTML as:

<a href="http://localhost/media/images/01.png" rel="lightbox"><img src="http://localhost/media/images/thumbs/01.png" /></a>

'attributes' parses attributes for a HTML tag from an array.

There are two arguments are:

• [array] An array of attributes you'd like to add to a HTML tag

Example 1:

echo html::attributes(
	array
	(
		'style' => 'font-size: 20px; border-bottom: 1px solid #000;',
		'rel' => 'lightbox',
		'class' => 'image'
	)
);

It will result in HTML as:

style="font-size: 20px; border-bottom: 1px solid #000;" rel="lightbox" class="image"

Example 2 (with html::anchor):

echo html::file_anchor('home/images/01.png', 'See my picture!',
html::attributes(
	array
	(
		'style' => 'font-size: 20px; border-bottom: 4px solid #000;',
		'rel' => 'lightbox',
		'class' => 'image'
	)
)
);

It will result in HTML as:

<a href="http://localhost/home/images/01.png"  style="font-size: 20px; border-bottom: 4px solid #000;" rel="lightbox" class="image">See my picture!</a>

The function returns an array of links for each segment.

Arguments:

• [array] segments to use as breadcrumbs, defaults to using Router::$segments

Example:

  echo Kohana::debug(html::breadcrumb());

will produce the following output:

 Array
 (
    [0] => <a href="http://localhost/ajax">Ajax</a>
    [1] => <a href="http://localhost/ajax/welcome">Welcome</a>
    [2] => <a href="http://localhost/welcome/text">Text</a>
 )

Creating Breadcrumbs

Creating breadcrumbs is easy; use the following code as an example:

public function get_breadcrumbs()
{
	global $breadcrumbs;
 
	$get_breadcrumbs = html::breadcrumb();
	while (current($get_breadcrumbs))
	{
		$breadcrumbs .= current($get_breadcrumbs);
 
		// Check if we have reached the last crumb
		if (key($get_breadcrumbs) < (count($get_breadcrumbs)-1))
		{
			// If we haven't, add a breadcrumb separator
			$breadcrumbs .= ' / ';
		}
		next($get_breadcrumbs);
	}
		return $breadcrumbs;
}

A function like this could be included in your 'MY_Controller' library and made available to every page. Displaying the breadcrumb (ie. from a view) is as easy as:

echo $this->get_breadcrumbs();

This function will display each breadcrumb as a hyper-link. However, we may want the hyper-link removed from the last link (as we are currently on that page) and have it bold instead. This can be achieved by using this code:

public function get_breadcrumbs()
{
	global $breadcrumbs;
 
	$get_breadcrumbs = html::breadcrumb();
	while(current($get_breadcrumbs))
	{
		// Check if we have reached the last crumb
		if(key($get_breadcrumbs) < (count($get_breadcrumbs)-1))
		{
			// If we haven't, add a breadcrumb separator
			$breadcrumbs .= current($get_breadcrumbs).' / ';
		}
		else
		{
			// If we have, remove the anchor from the breadcrumb and make it bold
			$breadcrumbs .= strip_tags("<strong>".current($get_breadcrumbs)."</strong>", "<strong>");
		}
		next($get_breadcrumbs);
	}
		return $breadcrumbs;
}