Skip to content

Template

Jump to bottom Edit New page
Randy Merrill edited this page Feb 23, 2011 · 15 revisions

Breadcrumb

The template can be used to generate a breadcrumb based upon the current page and where it appears in the hierarchy of the navigation.

getBreadcrumb(options)

The following options can be passed while retrieving the breadcrumb.

Option Description Default
separator Text used to separate the breadcrumb items. :
showMultiple Determines if only the current page will be shown or if multiple breadcrumb items will be used. true
topLevel Used as the top level that will be displayed. If the page level is less than the top level it will return a blank breadcrumb. 1
useNavTitle Determines if the breadcrumb will use the navigation title or the normal page title. true

Internationalization

When templating a page it is suggested that you use i18n to be able to translate the design into different languages. The template allows you to add bundles that can be used in your templating to show the correct translation.

addBundle(path, name)

The addBundle is used to add a i18n translation bundle for later use.

getLabel(key)

The getLabel is used to retrieve the correct i18n value for the current session's selected locale.

Levels

Much of templating is based upon the level of the page in it's heirarchy. For example, the navigation you see on a page often changes depending upon what level the page lies in the hierarchy.

At times it becomes necessary to inject a level into the page hierarchy. This is done to be able to create dynamic content for a page that makes it appear as though it is a part of the normal hierarchy.

For example, a user plugin that is dynamically showing a user profile would be able to add a level to the template that included the user's name and a link to the user's profile.

addLevel(title, navTitle, link, position, isCustom)

Argument Description Default
title The page title of the level being added.
navTitle The navigation title of the level being added.
link The link that should be used for the level.
position
The position to place the level. If the level is 0 it will be added to the end of the existing levels. If the level is greater than 0 it will attempt to replace the level at the position given. If the level is less than 0 it will attempt to insert the level relative to the existing levels. 
		<div>
			For example, if you add a level with a -1 position it will add
			the level would appear just above the current page in the hierarchy.
		</div>
	</td>
	<td><code>0</code></td>
</tr>
<tr>
	<td><code>isCustom</code></td>
	<td>
		When adding custom levels to a page this should be set to true. 
		Setting this to true prevents throwing off the level count that is 
		returned from the <code>getLevel()</code> and used in the 
		navigation.
	</td>
	<td><code>false</code></td>
</tr>

getLevel()

Returns the current level based upon the page that is being displayed and any adjustments made by adding levels manually.

getLevels()

Returns an array of information about each of the levels.

Navigation

Navigation is based on three main components: the current location, the level to base the navigation, and the navigation position.

Current Location

The current location is, by default, based upon the URL _base variable. For 90% of the navigation generated this is the desired effect. For those occasions where a custom location is desired it can be overridden using the parentPath option cited below.

Being able to control the location that the navigation thinks it is at is handy in situations, like account navigation, where the navigation to be shown may be based upon a separate page (/account). By providing a custom location the navigation will always display the correct navigation, regardless of the current page. In the account example, it would be able to display the navigation for the /account/profile page even though the current page might be in a different location, ex: /about.

Level

The level that the navigation is based off can be a static value, such as 1, which would always show the first level navigation and keep the navigation constant. The level can also be more dynamic, such as using the current level to show a different navigation tailored to the page being shown.

Navigation Position

As there are multiple navigations usually shown on a page at a time the position that the navigation is going to be displayed becomes important. For example, you may have a top, main, footer, and account navigation all showing on one page.

getNavigation(level, navPosition, options, user)

The following options can be passed while retrieving the navigation.

Option Description Default
depth Number of navigation levels to display. 1
innerTag Tag used around the individual navigation elements. ul
numLevels
Used to control the number levels of navigation to retrieve. If the value is > 1 it will nest any available sub navigation. If the value is -1 it will return all levels of nested navigation. 
		<div>
			Can also be used with the selected only to only show sub navigation 
			when the sub navigation is part of the current path.
		</div>
	</td>
	<td><code>1</code></td>
</tr>
<tr>
	<td><code>outerTag</code></td>
	<td>
		Tag used as the parent to the individual navigation elements.
	</td>
	<td><code>ul</code></td>
</tr>
<tr>
	<td><code>parentPath</code></td>
	<td>
		Used as the parent path for the navigation.
		Useful when trying to output navigation for a that does not change based upon the current path.
	</td>
	<td><code>@current path@</code></td>
</tr>
<tr>
	<td><code>selectedOnly</code></td>
	<td>When showing more than 1 level will only display sub navigation for the current page.</td>
	<td><code>false</code></td>
</tr>

Scripts and Styles

To ease the haphazard insertion of scripts and styles into the content the template component comes with some functions to make it easier to work with scripts and styles and generate the needed html.

Titles

There are two different versions of titles available to use in the templating process: the HTMl title and the page title.

As the name implies, the HTML title is made to easily generate the HTML title for a page with a few extra options. Some themes will use the html title as a normal title while others will use it as a reverse of the breadcrumb that gives an additional method of showing the user's location.

The page title is used to return the title of the current page. It can also be used to return the title of a specific level.

getHtmlTitle(options)

The following options can be passed while retrieving the html title.

Option Description Default
separator Text used to separate the html title items. :
showMultiple Determines if only the current page will be shown or if multiple items will be used for the title. false
useNavTitle Determines if the html title will use the navigation title or the normal page title. true

getPageTitle(level)

Used to retrieve the full page title for a given level. If no level is given it will show the title from the showing page.

Add a custom footer
Add a custom sidebar
Clone this wiki locally