Chapter 14. Creating & Using Breadcrumbs

A definition.  Bread crumbs are another method of navigation but instead of linking a user forward, they link a user back. This is very useful for seeing what a level up is or tracing your path back through the site. They are implemented into the LiveJournal codebase, and tied in to the translation system. You can read more about what bread crumbs are, and how they work, here[o].

Hierarchy.  First, crumbs are organized in a tree. The base of the tree is 'home', which is the front page. Every crumb has a unique key for itself and one (only one) parent. Each crumb is also defined as having a default English title and a link to its page.

Adding crumbs.  In the relevant crumbs definition files (cgi-bin/crumbs.pl and crumbs-local.pl) you will find the hashes that define the crumbs. If you want to add a new crumb, you need to add it to one of these files. Note that crumbs in crumbs-local.pl override crumbs in crumbs.pl. Site-specific files, like those from ljcom, need to have their crumbs put into crumbs-local.pl.

%LJ::CRUMBS(_LOCAL) Hash format. 

'unique_key' => [ 'Title of Crumb', '/some/page.bml', 'my_parent' ]

That's a static crumb. Once you have defined one of those in the relevant Perl file, you can tell LiveJournal to display that crumb on a BML page by using this code:

LJ::set_active_crumb('unique_key');

Run that anywhere inside of a BML page's code block.

If you have a page that does not have a code block, you should insert one in the following manner:

<?_code
     return LJ::set_active_crumb('unique_key');
_code?>

Example site-specific crumb definition file (cgi-bin/crumbs-local.pl). 

#!/usr/bin/perl
#
# Stores all local crumbs and adds to the global %LJ::CRUMBS hash

%LJ::CRUMBS_LOCAL = (
        'whatis' => ['What Is YourSite?', '/site/whatis.bml', 'home'],
        'ljbase' => ['Base', "$LJ::SITEROOT/", ''],
        'press' => ['YourSite', '/press/', 'whatis'],
	           );
1;

You can also insert dynamic crumbs. If you wish to have a crumb title reflect something like “Support Request #3777”, you will need to use a dynamic crumb. You use these like this:

LJ::set_dynamic_crumb(BML::ml('.foo', { 'num' => 5 }), 'parent');

Notice that we call BML::ml. This means that the crumb title can be pulled from the translation database, so you still have a translated crumb, but you can still insert in the dynamic data that you want.

Placing crumbs into the database.  When you edit the crumbs files, you need to put them into the translation database. This is, as you probably expected, done with bin/upgrading/texttool.pl. Specifically, there is a new “loadcrumbs” option as well as a “wipecrumbs” option. It is easiest to just run: bin/upgrading/texttool.pl load en en_YS [15]. If you use loadcrumbs instead of load, make sure to also use the makeusable option with texttool.pl, so the crumbs really show up on your site.



[15] The load option includes “en” by default; en_YS is only needed if you are using site-specific text and bread crumbs.