Plug:ignatius:phpCMS Breadcrumb

From phpCMS

1 phpCMS Breadcrumb

[edit] phpCMS Breadcrumb

[edit] Overview

title         : phpCMS Breadcrumb
version       : 0.7
author        : (c) by Thilo Wagner (Ignatius)
licence       : GPL
description   : A plugin for phpCMS to create breadcrumb-navigation lines
phpCMS version: 1.1.x (tested with 1.1.7), 1.2.x

please post any errors, discussions etc. about this plugin to the
phpCMS forum at http://www.phpcms.de or twagner (at) drachenreiter.de

[edit] Licence

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

[edit] Download

The plugin can be downloaded from the plugin-database on http://www.phpcms.de. The direct link is:

http://phpcms.de/download/plugins/files/phpcms_breadcrumb_0_7.zip

Please make sure that there is no newer version in the plugin database (and update this page in the wiki if this is the case)

[edit] Plugin description

phpCMS-breadcrumb is a plugin for the open-source content management system phpCMS (http://www.phpcms.de). With this plugin you can easily add an co called "breadcrumb-navigation line" to your phpCMS driven homepage. phpCMS-breadcrumb will only work as a plugin for phpCMS and not as a stand-allone script.

Breadcrumb navigation displays the current page's context within the site structure. The term "breadcrumb" is as in "Hansel and Gretel" - leaving a trail of crumbs in order to find their way back out of the forest. The benefit of this approach is that it makes obvious the ways in which information has been grouped and allows the user both to move between these groupings and understand the information structure.

[edit] Installation instructions

Step 1:

Copy the file phpcms_breadcrumb.php to the plugin-directory of your phpCMS installation (normaly this is something like /parser/plugs)

Step 2:

Add a new layout-definition-block for the breadcrumb-navigation line to your standard menu-template file (for example /template/home.mtpl):

Here is an example for such a layout-definition-block:

{BREADCRUMB.PRE}

{BREADCRUMB.NORMAL}
<a href="{LINK}">{MNAME}</a> >

{BREADCRUMB.ACTIVE}
{MNAME}

{BREADCRUMB.PAST}

The .PRE field is printed at the beginning of the breadcrumb-line and the .PAST field at the end

.NORMAL is the definition for all the pages which lay under the actual one in the menu-tree und .ACTIVE is the style for the page the user is looking to at the moment (always the last item in the breadcrumb line)

So if your breadcrumb navigation-line is

Home > phpCMS > Plugins > Breadcrumb

The first three items are printed in .NORMAL layout and the last one in .ACTIVE layout.

Please always add all 4 fields (.PRE, .NORMAL, .ACTIVE and .PAST) to your menu-template file. If you don't need one field, simply leave it empty.

Example: If you don't need anything to be printed out before and after the breadcrumb navigation-line you could use for example something like:

{BREADCRUMB.PRE}

{BREADCRUMB.NORMAL}
<a href="{LINK}">{MNAME}</a> >

{BREADCRUMB.ACTIVE}
{MNAME}

{BREADCRUMB.PAST}

Step 3:

Include the plugin as a static plugin in the beginning of your page-template file:

{PLUGIN FILE="$plugindir/phpcms_breadcrumb.php" TYPE="STATIC"}

If you have phpcms_breadcrumb installed in a different directory you must point of course to the correct path.

Step 4:

Place the <BREADCRUMB> tag in the place of your page-template or content-file where you want to have the breadcrumb-navigation line inserted

Step 5:

Clear the phpCMS-Cache so the breadcrumb-navigtion line gets inserted the next time phpCMS parses the content-file. On some browsers (for example IE) it can happen that you have to hold down the ctrl-Key down while clicking on the reload button so the browsers ignores the local cached version and requests a the file again from the server.

That's it.

[edit] Special features

phpCMS-breadcrumb has implemented a few special configuration features. Normaly you don't need to use them, they're only for special cases. So if you don't unterstand the following descriptions, don't bother.. you probablby don't need these features ;-)

[edit] {BREADCRUMB_MENU}

If you put the optional field {BREADCRUMB_MENU} in a content-file phpCMS-breadcrumb will use the Menu-class in that field instead the one in the {MENU} field to build it's breadcrumb navigation-bar.

So if your content file looks for example like:

{MENU} 00.01.05
{BREADCRUMB_MENU} 00.01.07
{TITLE} Test-Page
{CONTENT} This is a test page!

phpCMS will use menu-class 00.01.05 to display the menu for this page, but phpCMS-breadcrumb will instead use the menu-class 00.01.07 to display the breadcrumb navigation line.

If you add the {BREADCRUMB_MENU} field to a content-file and write the word "auto" instad of a menu-class behind that field, phpCMS breadcrumb will handle the page as if there is no Menu-class at all defined in the content-file so it will try to compare the URL with the links in the menu-file to find the right menu-class.

So if your content file looks for example like:

{MENU} 00.01.05
{BREADCRUMB_MENU} auto
{TITLE} Test-Page
{CONTENT} This is a test page!

phpCMS will use menu-class 00.01.05 to display the menu for this page, but phpCMS-breadcrumb will instead look in the menu-file to see if it can find any menu item which points to the actual URL and will use that menu-class to display the navigation line.

[edit] {BREADCRUMB_TEMPLATE}

If you put the optional field {BREADCRUMB_TEMPLATE} in a content-file, phpCMS-breadcrumb will use the name given in this field as the name for the layout-definition-block in the menu-template file.

If you have for example set

$layout_block = "BREADCRUMB";

in the configuration part of the phpCMS-breadcrumb sourcecode, the line

{BREADCRUMB_TEMPLATE} SPECIAL_BREADCRUMB

in the content file will overwrite the name of the layout-definition-block for this content-file, so if a user opens that file the breadcrumb-navigation line will be displayed with the layout-definition-block

{SPECIAL_BREADCRUMB.PRE}
..
..
{SPECIAL_BREADCRUMB.NORMAL}
..
..

from the menu-template file

[edit] {BREADCRUMB_ITEM}

Sometimes it is useful to add one more breadcrumb to the breadcrumb navigation line even if you don't have defined an own menu-class for that item in your menu-file.

Let's take for example an page where you can browse through a picture gallery and let's suppose you have defined your menus in the menu-file like this:

MENU: MAIN
CLASS;       MNAME;     LINK;
00.01;       home       $home/index.htm
..
..

MENU: SUB1
CLASS;       MNAME;     LINK;
00.01.01;    gallery;   $home/gallery.htm

So if you go on gallery.htm you will get the breadcrumb navigation line

home -> gallery

Suppose now, you can click on one picture in that overview to enlarge it and you want to have a breadcrumb navigation line like for example

home -> gallery -> picture 1 of 273

you could do this by adding

MENU: SUB2
CLASS;        MNAME;             LINK;
00.01.01.01;  picture 1 of 273;  $home/picture001.htm
00.01.01.02;  picture 2 of 273;  $home/picture002.htm
00.01.01.03;  picture 3 of 273;  $home/picture003.htm
..

lot's of work, only for the breadcrumb line, eh? Especialy as you probably don't want to have all these classes in your menu-file because you don't need every picture displayed in the menu and also not in the site-map.

So this is the point where my "virtual breadcrumbs" comes into the game :)

With the usage of {BREADCRUMB_ITEM} you can add a breadcrumb to the end of the breadcrumb line.

For example you could write in the picture001.htm content-file:

{MENU} 00.01.01
{BREADCRUMB_ITEM} picture 1 of 273
{TITLE} picture 1 of 273
{CONTENT} <img src="pictures/picture001.jpg">

If you look at that page it will display the breadcrumb line

home -> gallery -> picture 1 of 273

And the other (by phpCMS generated) menus will look as if the gallery overwiev page is active. And that without adding any menu-classes to the menu-file.

[edit] Referencing from {BREADCRUMB_ITEM} to other fields

The content file from the last example looked like this:

{MENU} 00.01.01
{BREADCRUMB_ITEM} picture 1 of 273
{TITLE} picture 1 of 273
{CONTENT} <img src="pictures/picture001.jpg">

As you can see we have the same text in {BREADCRUMB_ITEM} as in {TITLE}. If we change the title of the content file we would also have to made the same change in the {BREADCRUMB_ITEM} field. But there's a little trick to avoid this. You can reference from {BREADCRUMB_ITEM} to another existing field in the content file by including the name of the field in square brackets ("[....]"):

{MENU} 00.01.01
{BREADCRUMB_ITEM} [title]
{TITLE} picture 1 of 273
{CONTENT} <img src="pictures/picture001.jpg">

This example will result in the same breadcrumb line as the example from above:

home -> gallery -> picture 1 of 273

and you have to change the title of the page only in one field.

[edit] {SELECTION}

With {SELECTION} you can display for example the last item of the breadcrumb navigation line as aa drop-down menu. Here is a how you can use {SELECTION} in your Menu-Template:

{BREADCRUMB.PRE}
<form action="">

{BREADCRUMB.NORMAL}
<a href="{LINK}" class="line"
 onMouseOver="window.status='{TEXT}';return true;" >{MNAME}</a> $gt;

{BREADCRUMB.ACTIVE}
<select size=1 name="select" onChange="top.location.href = this.form.select.options[this.form.select.options.selectedIndex].value">
{SELECTION}
</select>

{BREADCRUMB.PAST}
</form>

This example creates a drop down menu as the last item in the breadcrumb navigation line.

[edit] Development status / known bugs

No known bugs at the moment. Found any bugs? Any ideas for improvements or new features? Then please contact me!

[edit] Version History

28.07.2003 V0.7

Added support for field {SELECTION} to create a drop-down list in the breadcrumb menu

08.11.2002 V0.6

Added support for "virtual breadcrumbs" {BREADCRUMB_ITEM}
You can modify now the error-message in the "configuration-part" of the plugin
Improved this documentation file

11.05.2002 V0.5

Added support for the optional fields {BREADCRUMB_MENU} and {BREADCRUMB_TEMPLATE} in the content-file
changed licence to GNU Public Licence (GPL) and added a copy of the GPL to the distribution archive
Improved this documentation file

10.05.2002 V0.4

Added some more error-handling functions.
phpcms_breadcrumb is now more failure-tolerant, for example if the menu-class of the actual page is 00.01.01.05 and you only have the menu-classes 00.01 and 00.01.01.05 (but not 00.01.01) defined in your menu-file, phpcms_breadcrumb can handle this by simply skipping the missing menu-classes without producing any errors

08.05.2002 V0.3

phpcms_breadcrumb works now also if you don't have the {MENU}-field set in your Content-File. In this case it compares the actual url with the links in the

menu-file to determine the correct menu-class for the actual content-file (equal as phpCMS handles these cases)

08.05.2002 V0.2

Improved documentation
minor bugfixes
corrected a few typos.
Breadcrumb-Tag is now <BREADCRUMB> instead of <BREADCRUMP> ("B" instead of "P" ;-)
.ACTIVE layout-definition can be written also as .AKTIV to be backward compatible to phpCMS-versions prior 1.1.7

07.05.2002 V0.1

First public release

Main Page: Main Page | Top Page: Plugin Documentation MainPage

Retrieved from "http://docs.phpcms.de/index.php/Plug:ignatius:phpCMS_Breadcrumb"

Category: Plugin Docu