README.txt in Custom Breadcrumbs 6.2

/* $Id $ */

Custom Breadcrumbs 6.x-1.x (See below for 6.x-2.x)
--------------------------------------------------
Summary
-------
* Enable the module
* Assign 'administer custom breadcrumbs' permission to those roles that should
  be allowed to add/edit/delete custom breadcrumbs.
* Assign 'use php in custom breadcrumbs' to roles that should be allowed to use
  php to determine breadcrumb visibility.
* Go to Administer > Site building > Custom breadcrumbs to add new breadcrumbs
* Click "Add a new custom breadcrumb"
* Choose the node type to create a breadcrumb trail for
* For the titles, put each "crumb" one line after another (There is no need to
  put in "home"):

  Item 1
  SubItem A
  SuperSubItem X

* For the paths, put the path to each crumb starting after the domain name.
  Don't include a leading or trailing slash.

  item1
  item-1/subitem-a
  item-1/subitem-a/supersubitem-x

* Click save to save the breadcrumb
* Visit the page and your breadcrumb should appear!

Description
-----------
As the name suggests, Custom Breadcrumbs allows you to create and modify your
own breadcrumbs based on node type. After enabling the module, click on
Administer > Site building > Custom breadcrumbs. You'll be abel to add new
breadcrumbs from this page.

Clicking on that link, you have the option to select the node type the
breadcrumb will apply to. There are two text fields below-- "Titles" and 
"Paths." When creating a breadcrumb, you're simply creating a link. In the
custom breadcrumbs interface "Titles" describes the text of the breadcrumb
while "Paths" describes the Drupal path the breadcrumb links to. Each Title
must have a corresponding Path.

To give a very simple example of how to use this module, let's say I have a
blog on my web site called "Deep Thoughts." To create this, I use the Views
module to create a page at /blog that displays all the node types "blog post."
Whenever a user views a blog post I want the breadcrumb to show
Home > Deep Thoughts instead of simply Home. To do this I would simply type
"Deep Thoughts" in the "Titles" field and and "blog" in the "Paths" field and
save my breadcrumb.

Using the Tokens module, the Custom breadcrumbs module becomes much more
flexible because breadcrumbs can become dynamic. You can create a breadcrumb
like Home > Deep Thoughts > [Month of Blog Post] [Year of Blog Post], where
"Deep Thoughts" links to my main blog page and "[Month of Blog Post]
[Year of Blog Post]" links to a view that shows only blog posts from the month
and year the blog post was created (e.g. June 2007). For this, you would do
the following:

Node Type:
Blog Post

Titles:
Deep Thoughts
[month] [yyyy]

Paths:
blog
blog/[mm]_[yyyy]

(where of course, blog/[mm]_[yyyy] is the path to the view of blog posts from
that month and year). So if you created a blog pos on June 13, 2007 your
breadcrumb would show Home > Deep Thoughts > June 2007 and "June 2007" links
to "blog/06_2007" which is a view of all blog posts from June 2007.

Also, note that Custom Breadcrumbs doesn't actually check to be sure that a
particular path exists, so you'll have to check yourself to avoid 404 errors.

Only users with 'administer custom breadcrumbs' permission will be allowed to
create or modify custom breadcrumbs.

Breadcrumb Visibility
---------------------
Users given 'use php in custom breadcrumbs' permission can include a php code
snippet that returns TRUE or FALSE to control whether or not the breadcrumb is
displayed. Note that this code has access to the $node variable, and can check
its type or any other property. Tokens should not be used in the visibility
code snippet, since they will not be replaced.

Special Identifiers
-------------------
The following identifiers can be used to achieve a special behavior:
<pathauto> - will clean any path using the current pathauto module settings,
             if that module is installed.
<none>     - can be used as a path to have a breadcrumb element that is not
             hyperlinked.

Identifiers should be added to the paths area in the following format:
identifier|path. To be recognized, the identifier must be enclosed in angular
brackets, and proceed any part of the path:

For example: <pathauto>|[ogname-raw]


Custom Breadcrumbs 2.0
----------------------

Summary
-------
* Enable the module and any option submodules (see below for details)
* Assign 'administer custom breadcrumbs' permission to those roles that should
  be allowed to add/edit/delete custom breadcrumbs.
* Assign 'use php in custom breadcrumbs' to roles that should be allowed to use
  php to determine breadcrumb visibility.
* Go to Administer > Site Configuration > Custom breadcrumbs Settings to select
  the 'Home' breacrumb text and possibly other global settings.
* Go to Administer > Site building > Custom breadcrumbs to add new breadcrumbs
* To add a breadcrumb, click on one of the tabs at the top of the page. For
  example, click 'Node' to create a custom breadcrumb based on node type.
* Fill in the required information for the breadcrumb (varies depending on 
  breadcrumb type, see below).
* For the titles, put each "crumb" one line after another (There is no need to
  put in "home")
* (optional) For each crumb title you can specify a title attribute ("tooltip")
  to add to the link. Separate the crumb title and the title attribute with a
  pipe (|) symbol:

  Item 1
  SubItem A|Title attribute for SubItemA (optional)
  SuperSubItem X

* For the paths, put the path to each crumb starting after the domain name.
  Don't include a leading or trailing slash.

  item1
  item-1/subitem-a
  item-1/subitem-a/supersubitem-x

* Click save to save the breadcrumb
* Visit the page and your breadcrumb should appear!

New Features
------------
In the 6.x-2.x release, custom breadcrumbs has many new features which are
available through optional modules in the custom breadcrumbs package. The base
module, required by all the others, is still custom_breadcrumbs. This module
handles custom breadcrumbs based on node type as described above. The following
optional modules can also be installed to provide custom breadcrumbs in a
variety of situations:

+ custom_breadcrumbs_views provides custom breadcrumbs on views pages.
  Once this module is enabled, a new "Views" tab will appear at
  admin/build/custom_breadcrumbs. To add a views page breadcrumb, click on the
  tab and then select the view from list of available views. Fill in the
  visibility, title and paths sections as described above, and your breadcrumb
  should appear on your views page. Note that token substitution is possible
  with global and user tokens only. The $view object is available for use in
  the php_visibility section.

+ custom_breadcrumbs_paths provides custom breadcrumbs on nodes and views at
  a specified path (url). Once this module is enabled, a new "Path" tab will
  appear at admin/build/custom_breadcrumbs.  To add a breadcrumb for a node
  or a view at a specific path, just enter the Drupal path in the Specific
  Path section. Fill in the visibility, title and paths sections as
  described above, and save the breadcrumb. Now your breadcrumb should appear
  on the node or view at the specific path that you selected. Note that custom
  breadcrumbs does not check the validity of the entered path. When entering a
  path for a particular language (see below), do not specify the two-letter
  language prefix. Custom breadcrumbs will assume the correct prefix according
  to the selected language. To use '*' as a wildcard, go to custom breadcrumbs
  configuration page at /admin/settings/custom-breadcrumbs and select the
  'Use wildcard pattern matching in paths' option in the advanced settings
  section. When this option is enabled, the breadcrumb that best matches the
  path will be selected. The best match is determined by the depth at which
  the first wildcard appears. For example, if the path is path/to/some/content
  and breadcrumbs have been defined for path/to/* and path/to/some/*, the
  latter will be chosen as the best match.

+ custom_breadcrumbs_taxonomy provides custom breadcrumbs on taxonomy term
  pages, views, and for nodes that are assigned a taxonomy vocabulary or term.
  Once this module is enabled, two new tabs will appear appear at 
  admin/build/custom_breadcrumbs: Term and Vocabulary. Breadcrumb generation
  can be handled in two different ways. If 'use the taxonomy term hierarchy'
  is checked at custom breadcrumbs configuration page, then breadcrumbs will
  be generated similarly to the taxonomy_breadcrumb module. Otherwise,
  breadcrumb generation will be according to the standard custom breadcrumbs
  approach.

  In taxonomy breadcrumb mode, the breadcrumb trail is automatically
  constructed based on the taxonomy term hierarchy:
  [HOME] >> [VOCABULARY] >> TERM >> [TERM] >> [TITLE]. In this mode the
  breadcrumb titles are the term and vocabulary names. The paths these titles
  are linked to can be assigned via the Term and Vocabulary tabs at
  admin/build/custom_breadcrumbs. Providing a path for a vocabulary will enable
  the [VOCABULARY] portion of the breadcrumb.  The path for a term can
  similarly be set, but if one is not provided the default taxonomy/term/tid
  (where tid is a number, the taxonomy term id) will be used. Select the types
  of nodes to include or exclude at the custom breadcrumbs configuration
  settings page. The option to add the node title at the end of the breadcrumb
  trail can also be enabled on that page. There is also an option to append
  the current taxonomy term to the breadcrumb on taxonomy term pages
  (defined to be any page with drupal path */taxonomy/term/*).

  In the standard custom breadcrumbs mode, you can provide the titles and paths
  for constructing the breadcrumb trail on nodes that have defined taxonomy
  terms. Note that if a node has more than one term, the lightest term in the
  lightest vocabulary with a defined custom breadcrumb will be used.

  Note: do not use this module and the taxonomy_breadcrumb module at the same
  time. Custom_breadcrumbs_taxonomy has extended the functionality of 
  taxonomy_breadcrumb, so that module is not needed if you are using 
  custom_breadcrumbs.

  While at admin/settings/custom-breadcrumbs, go ahead and enable any
  additional taxonomy breadcrumb options that suits your needs. If you are
  using views to override taxonomy term pages, then be sure to enable the
  "Use taxonomy breadcrumbs for views" option.

+ custom_breadcrumbsapi provides a simple api that allows custom breadcrumbs to
  be defined for module pages implementing the api. Module developers need to
  provide a modulename_custom_breadcrumbsapi() function that returns an array
  containing the names of the module pages for which custom breadcrumbs may be
  defined.

  The following is an example that could be used with the forum module.

  /**
   *  Implementation of hook_custom_breadcrumbsapi().
   *  Allow custom breadcrumbs for the following module pages.
   */
  function forum_custom_breadcrumbsapi() {
    return array('forum listing');
  }

  Then, in the callback functions for each of those pages, the following line
  must be inserted within the function (preferably after defining $breadcrumb
  but before setting the breadcrumb):
  
  drupal_alter('breadcrumb', $breadcrumb, 'module_page_name');

  Continuing with the forum module example, 'module_page_name' would be
  replaced with 'forum listing'.
  
  custom_breadcrumbsapi can also provide custom breadcrumbs for modules 
  implementing theme templates (e.g. files ending in .tpl.php). To add a 
  custom breadcrumb when a specific theme template file is called, click
  on the module page tab at admin/build/custom_breadcrumbs. Select the
  template file from the list of theme templates (determined from the 
  theme registry). Then fill in the usual custom breadcrumbs information
  such as titles as paths. If using a php snippet for breadcrumb visibility
  or to specify titles and paths (see below), you have access to the template
  variables through $variables, an associative array defined by the module
  providing the template. See the documentation in the template file for
  details. For example, if a template file uses the variable $foo, then
  access to that variable would be through $variables['foo'].

User Interface
--------------
The user interface has been modified for Custom Breadcrumbs 2.0. Breadcrumbs
from all custom breadcrumbs modules are tabulated at
admin/build/custom_breadcrumbs. The table can be sorted according to
breadcrumb name, type, language (if locale is enabled) by clicking on the
column headers. The table can also be filtered to display breadcrumbs of a
specific type, language, or combination of the two.

A new custom breadcrumbs fieldset has  been added to node edit pages. All
defined breadcrumbs for a particular node are displayed here, with an option to
edit each.  If no breadcrumbs have been defined for a particular node, then a
link can be followed back to admin/build/custom_breacrumbs to add a custom
breadcrumb.

Languages
---------
If the core Locale module is enabled, then an additional option to specify the
language for the breadcrumb is available when constructing the breadcrumb trail
(with any of the custom breadcrumb modules).

HOME breadcrumb
---------------
The text to display at beginning of the breadcrumb trail can be assigned from
the custom breadcrumb configuration settings page. Typically this is Home or
your site name. You can leave it blank to have no home breadcrumb. As with
normal crumb titles, you can optionally specify a title attribute ("tooltip")
for the crumb. Just separate the crumb text and the title attribute text with a
pipe (|) symbol (i.e. Home crumb text|attribute title text). There is
also an advanced setting to set the Home breadcrumb text on ALL pages, not
just those with defined custom breadcrumbs. You can also use this feature to
remove the home breadcrumb on all pages on the site - just enable the advanced
setting and then leave the home breadcrumb text blank.

It is possible to translate the home reference title from custom breadcrumbs
using the i18n module. Just put this in your settings.php:

  $conf['i18n_variables'] = array(
    //custom breadcrumbs
    'custom_breadcrumb_home',
  );

Then you can change it for each language at
http://example.com/#lang-prefix#/admin/settings/custom-breadcrumbs.

See http://drupal.org/node/313272 for additional information.

Use PHP in breadcrumb titles and paths
--------------------------------------
If this advanced option is enabled at admin/settings/custom-breadcrumbs, then
users given 'use php in custom breadcrumbs' permission can include small php
code snippets (less than 250 characters)in the titles and/or paths fields of
the add breadcrumb form. Be careful when enabling this option, as the incorrect
use of php can break your site.

There are a couple of ways to use php in breadcrumbs and titles. One way is to
return an array of breadcrumb titles in the titles text field and a
corresponding array of breadcrumb paths in the paths text field such as

Titles:
<?php return array('title-1','title-2','title-3');?>

Paths:
<?php return array('path/to/title-1','path/to/title-2','path/to/title-3');?>

Sometimes, it may be more convient to assign the titles and paths in the same
code snippet, so you can also return an associate array with elements 'titles'
and 'paths' that contain the titles and paths arrays, respectively.
For example,

Titles:
<?php $titles = array('title-1','title-2','title-3');
$paths = array('path/to/title-1','path/to/title-2','path/to/title-3');
return array('titles' => $titles, 'paths' => $paths); ?>

(In this case, the paths text field will be ignored, so you can leave it
empty).

When defined, appropriate objects such as $node, $term, or $view, will be
available for these code snippets. Note that if this option is enabled and an
array is not returned, then the module defaults to the standard operation of
using each line of the titles and paths text fields to define a part of the
breadcrumb.

For longer code snippets (greater than 250 characters), you can save your code
snippet in an include file and use a php require_once statement in the titles
and/or paths section of your custom breadcrumb to include and evaluate your
code. See http://drupal.org/node/654766 for an example of this.

Add CSS classes to custom breadcrumb elements
---------------------------------------------

You can enable this feature on the custom breadcrumbs configuration screen
under the HTML element identifiers section. There are several options that
provide html class identifiers for theming custom breadcrumb links, including
add a 'custom-breadcrumbs-home' ID attribute to the home breadcrumb item,
adding numbered class attributes 'custom-breadcrumbs-item-N' for each
breadcrumb item, adding even and odd classes to breadcrumb items and storing an
identifier that is unique for each defined custom breadcrumbs. Using this
last option requires modifying your sites phptemplate_breadcrumb (or theme
override) function to actually add the class name to the breadcrumb container.
The class name is returned as a string by the function 
custom_breadcrumbs_unique_breadcrumb_id(). The identifier will be of the form
'custom-breadcrumbs-type-id'where type is the breadcrumb type (node, panels,
path, views or taxonomy) and id is the breadcrumb id number.
See http://drupal.org/node/643796#comment-2532998 for more information on this
feature.

Special Identifiers
-------------------
In Custom Breadcrumbs 2.0, Special identifiers are now provided as a separate,
optional module - custom_breadcrumbs_identifiers. At present, this module
provides the following identifiers:

<none>              - Produces a plain text crumb. This identifier should not
                      be used with the pipe (|) symbol.
<pathauto>          - Cleans the given path using your pathauto replacement
                      rules.
<book-hierarchy>    - Provides crumbs for each parent node of a book page.
                      Whatever is placed in the corresponding position of the
                      title area will be ignored. It should not be used with
                      the pipe (|) symbol.
<page-title>        - Provides a plain text crumb using the page title. Whatever
                      is placed in the corresponding position of the title area
                      will be ignored. It should not be used with the pipe (|)
                      symbol.
<menu-parent-trail> - Produces crumbs for each parent item for the given path.
                      The title information for this line will be ignored
                      because the menu link titles are used. If a path is not
                      provided following the pipe (|) symbol, the current path
                      with be used.

Additional special identifiers can be developed and added by contributed
modules that implement hook_cb_identifier_list(), to provide a description of
the identifer, and hook_cb_identifier_values(), to prepare the appropriate
crumb items. See the custom_breadcrumbs_identifiers.module for examples of
how to do this.

Identifiers should be added to the paths area in the following format:
identifier|path. To be recognized, the identifier must be enclosed in angular
brackets, and proceed any part of the path:

For example: <pathauto>|[ogname-raw]

Note that not all identifiers require the use of |path.

Authors
-------
bennybobw, dbabbage, Michelle, MGN