Breadcrumbs 1.0.1

From MODx Wiki
Revision as of 21:06, 20 January 2010 by Nsayers (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

 MODx Snippet 

Breadcrumbs v1.0.1
Author 
jaredc
MODx Versions 
>= 0.9.0
Last Updated 
25 Apr 2008

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.

Page download link: Package: Breadcrumbs at MODx

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.


Friendly 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 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.


Configuration information given in the body of the snippet, ie:

General setup

&maxCrumbs

Values: [ integer ]
Default: 100

Max number of elemetns to have in a breadcrumb path. The default 100 is an arbitrarily high number that will essentially include everything. If you were to set it to 2, and you were 5 levels deep, it would appear like:

HOME > ... > Level 3 > Level 4 > CURRENT PAGE

It should be noted that the "home" link, and the current page do not count as they are managed by their own configuration settings.


&pathThruUnPub

Values: [ 1 | 0 ]
Default: 1

When your path includes an unpublished folder, setting this to 1 (true) will show all documents in path EXCEPT the unpublished. When set to 0 (false), the path will not go "through" that unpublished folder and will stop there.


&respectHidemenu

Values: [ 0 | 1 ]
Default: 1

Setting this to 1 (true) will respect the hidemenu setting of the document and not include it in trail.


&showCurrentCrumb

Values: [ 1 | 0 ]
Default: 1

Include the current page at the end of the trail. On by default.


&currentAsLink

Values: [ 1 | 0 ]
Default: 0

If the current page is included, this parameter will show it as a link (1) or just plain text (0).


&linkTextField

Values: [ string ]
Default: menutitle,pagetitle,longtitle

Prioritized list of fields to use as link text. Options are: pagetitle, longtitle, description, menutitle. The first of these fields that has a value will be the title.


&linkDescField

Values: [ string ]
Default: description,longtitle,pagetitle,menutitle

Prioritized list of fields to use as link title text. Options are: pagetitle, longtitle, description, menutitle. The first of these fields that has a value will be the title.


&showCrumbsAsLinks

Values: [ 1 | 0 ]
Default: 1

If for some reason you want breadcrumbs to be text and not links, set to 0 (false).


&templateSet

Values: [ string ]
Default: defaultString

The set of templates you'd like to use. (Templates are defined below.) It will default to defaultString which replicates the output of previous versions.


&crumbGap

Values: [ string ]
Default: ...

String to be shown to represent gap if there are more crumbs in trail than can be shown. Note: if you would like to use an image, the entire image tag must be provided. When making a snippet call, you cannot use "=", so use "||" instead and it will be converted for you.


&stylePrefix

Values: [ string ]
Default: B_

Breadcrumbs will add style classes to various parts of the trail. To avoid class name conflicts, you can determine your own prefix. The following classes will be attached:

  • crumbBox: Span that surrounds all crumb output
  • hideCrumb: Span that surrounds the "..." if there are more crumbs than will be shown
  • currentCrumb: Span or A tag surrounding the current crumb
  • firstCrumb: Span that will be applied to first crumb, whether it is "home" or not
  • lastCrumb: Span surrounding last crumb, whether it is the current page or not
  • crumb: Class given to each A tag surrounding the intermediate crumbs (not "home", "current", or "hide")
  • homeCrumb: Class given to the home crumb


Home link parameters

The home link is unique. It is a link that can be placed at the head of the breadcrumb trail, even if it is not truly in the hierarchy.

&showHomeCrumb

Values: [ 1 | 0 ]
Default: 1

This toggles the "home" crumb to be added to the beginning of your trail.


&homeId

Values: [ integer ]
Default: $modx->config['site_start']

Usually the page designated as "site start" in MODx configuration is considered the home page. But if you would like to use some other document, you may explicitly define it.


&homeCrumbTitle

Values: [ string ]
Default:

If you'd like to use something other than the menutitle (or pagetitle) for the home link.


&homeCrumbDescription

Values: [ string ]
Default:

If you'd like to use a custom description (link title) on the home link. If left blank, the title will follow the title order set in $titleField.


Custom behaviors

The following parameters will alter the behavior of the Breadcrumbs based on the page it is on.

&showCrumbsAtHome

Values: [ 1 | 0 ]
Default: 0

You can turn off Breadcrumbs all together on the home page by setting this to 1 (true);


&hideOn

Values: [ string ]
Default:

Comma separated list of documents you don't want Breadcrumbs on at all. If you have a LOT of pages like this, you might try $hideUnder or use another template. This parameter is best for those rare odd balls - otherwise it will become a pain to manage.


&hideUnder

Values: [ string ]
Default:

Comma separated list of parent documents, whose CHILDREN you don't want Breadcrumbs to appear on at all. This enables you to hide Breadcrumbs on a whole folders worth of documents by specifying the parent only. The PARENT will not have Breadcrumbs hidden however. If you wanted to hide the parent and the children, put the parent ID in hideUnder AND hideOn.


&stopIds

Values: [ string ]
Default:

Comma separated list of document IDs that when reached, stops Breadcrumbs from going any further. This is useful in situations like where you have language branches, and you don't want the Breadcrumbs going past the "home" of the language you're in.


&ignoreIds

Values: [ string ]
Default:

Comma separated list of document IDs to explicitly ignore.


Templates

In an effort to keep the MODx chunks manager from getting mired down in lots of templates, Breadcrumbs templates are included here. Two sets are provided prefixed with defaultString, and defaultList. You can create as many more as you like, each set with it's own prefix

$templates = array(
    'defaultString' => array(
        'crumb' => '[+crumb+]',
        'separator' => ' &raquo; ',
        'crumbContainer' => '<span class="[+crumbBoxClass+]">[+crumbs+]</span>',
        'lastCrumbWrapper' => '<span class="[+lastCrumbClass+]">[+lastCrumbSpanA+]</span>',
        'firstCrumbWrapper' => '<span class="[+firstCrumbClass+]">[+firstCrumbSpanA+]</span>'
    ),
    'defaultList' => array(
        'crumb' => '<li>[+crumb+]</li>',
        'separator' => '',
        'crumbContainer' => '<ul class="[+crumbBoxClass+]">[+crumbs+]</ul>',
        'lastCrumbWrapper' => '<span class="[+lastCrumbClass+]">[+lastCrumbSpanA+]</span>',
        'firstCrumbWrapper' => '<span class="[+firstCrumbClass+]">[+firstCrumbSpanA+]</span>'
    ),
);

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


Personal tools