Breadcrumbs

From MODx Wiki

The Breadcrumbs snippet will create a "breadcrumb" page trail navigation. It allows many configuration options such as limiting the number of crumbs shown, insertion of custom characters between crumbs, and hiding breadcrumbs on your home page to name a few.

What it was designed to do:

To show the path through the various levels of site structure back to the root, which is NOT necessarily the path the user took to arrive at a given page.

Usage

To use breadcrumbs with just the default configuration you only need to add this to your template: (or wherever else you may want to put them)

[[Breadcrumbs]]

and if you wish to use a parameter then it is:

[[Breadcrumbs? &parameter=`value`]]

and more than one parameter is

[[Breadcrumbs? &parameter=`value` &parameter2=`value`]]

The parameters to use are listed below along with descriptions of what they do as well as examples.

Freindly URLs

With friendly URLs activated you should to add the following line into the template:

<base href="[(site_url)]" />

Caching

Calling the snippet like this will allow caching:

[[Breadcrumbs]]

For the snippet not to be cached it is neccessary to call it like so:

[!Breadcrumbs!]

Parameters

note on defaults: all default values can be changed in the snippet code by logging into the manager then going to resources then snippets then opening Breadcrumbs.

Also note that parameters do not use single quotes around values, they use back ticks. On the majority of keyboards this is the key above the "tab" key and to the left of the number "1" key.

---

homePageId

Allows you define the document ID of your home page.

This can be any ID or the default `site_start`

Example:

[[Breadcrumbs? &homePageId=`5`]]

This would make the home page link go to the document with the ID of 5.

---

maxCrumbs

Maximum Number of elements to have in a path

should be set to the number of levels deep you want

Default is `100`

example:

[[Breadcrumbs? &maxCrumbs=`2`]]

would make "Home > ... > Level 4 > Current-Page" as it does not include the current page or the "Home" as these are configured in showHomeCrumb and showCurrentCrumb.

---

pathThruUnPub

Should be set to `1` or `0`, 1 being true and 0 being false. The default is 1

Example:

[[Breadcrumbs? &pathThruUnpub=`0`]]

This would show the breadcrumbs trail minus the unpublished document for example if b was unpublished, it would display as

"a > c > d"

as opposed to

"a > b > c > d"

("a" refers to the home page)

---

respectHidemenu

Setting the parameter "respectHidemenu" to the value `1` will hide items in the breadcrumb list which are set to be hidden in menus. It will work much the same way as the above parameter "pathThruUnpub"

The default value is `1`

Example:

[[Breadcrumbs? &respectHidemenu=`0`]]

This would display as

"a > b > c > d" if document "b" is set to hidden

as opposed to "a > c > d" if the value was set to `1`

("a" refers to the home page)

---

showHomeCrumb

Set to `0` if you would not like a link to your home page in the breadcrumbs. The default is `1`

Example:

[[Breadcrumbs? &showHomeCrumb=`0`]]

This would not show a home link.

Some people prefer this as they have a home page link elsewhere in there navigation.

---

showCrumbsAtHome

This parameter defines whether to show the breadcrumbs on the home page.

A value of `1` would show it and `0` would not. The default value is `0`

Example:

[[Breadcrumbs? &showCrumbsAtHome=`1`]]

This would show the breadcrumbs on the home page.

---

showCurrentCrumb

Defines whether or not to show the current page in the breadcrumb navigation.

It can be set to `1` or `0` The default setting is `1` which is to show the current page in the breadcrumbs.

Example:

[[Breadcrumbs? &showCurrentCrumb=`0`]]

This would not show the current page in the breadcrumb navigation.

---

currentAsLink

Defines whether or not to show the current page as a link in the breadcrumb navigation. Can be set to `1` or `0` The default is `0` which is to not show it as a link.

NOTE: with this set to `0` the current page will still be shown, just not as a link. To not show it at all you should use the above parameter "showCurrentCrumb"

Example:

[[Breadcrumbs? &currentAsLink=`1`]]

This would show the current page as a link in the breadcrumb navigation, not just plain text.

---

crumbSeparator

This parameter allows you to define the character between the links or "crumbs"

The default character is "»"

which is using the html code

»

This can be set to any "string" which could be one character, or a horizontal rule, or anything you feel like.

Example:

[[Breadcrumbs? &crumbSeparator=` - `]]

This would seperate the breadcrumb navigation items like so.

"a - b - c - d"

("a" refers to the home page)

---

homeCrumbTitle

This parameter is used when you want a link to your home page, but you want to call it something other than "home"

The default value is `Home`.

Example:

[[Breadcrumbs? &homeCrumbTitle=`index`]]

This makes the text of the link to your home page read "index" instead of the default "Home"

---

homeCrumbDescription

This parameter is used when youwant to have a custom description of your home page.

The default is `$homeCrumbTitle` (the above parameter), so if you left homeCrumbTitle as default then this parameters default would be "Home"

Example

[[Breadcrumbs? &homeCrumbDescription=`Home Page`]]

This would make the description be "Home Page" as opposed to "Home".

---

titleField

This is used if you wish to change the default page field to be used as the title of the breadcrumb navigation "crumb".

The default value is `pagetitle`

Example:

[[Breadcrumbs? &titleField=`alias`]]

This would make the title of the breadcrumb navigation "crumb" the documents alias rather than the default pagetitle.

---

descField

This is used if you wish to change the default page field to be used as the link description.

The default value is `description`

If the value is empty, it falls back to use the titlefield of which has a default value of pagetitle.

Example:

[[Breadcrumbs? &descField=`introtext`]]

This would make the link description of the "crumb" the summary or "introtext" of the document as opposed to the default page description.

---

CSS

You can customize certain elements of the breadcrumb navigation using cascading style sheets or "CSS". This is placed in either the head section of your page, or on an external style sheet.

This will, in most cases, NOT change functionalty, just appearance.

The classes used are:

---

.B_crumbBox

Span that surrounds all crumb output

---

.B_hideCrumb

Span surrounding the "..." if there are more crumbs than will be shown

---

.B_currentCrumb

Span or A tag surrounding the current crumb

---

.B_firstCrumb

Span that always surrounds the first crumb, whether it is "home" or not

---

.B_lastCrumb

Span surrounding last crumb, whether it is the current page or not

---

.B_crumb

Class given to each A tag surrounding the intermediate crumbs (not home, or hide)

---

.B_homeCrumb

Class given to the home crumb

---