Description

Tapestry-zbreadcrumbs is a yet another bread crumb trail implementation Tapestry 5.It is licensed under The Apache Software License, Version 2.0

Even though it was inspired from tapestry-breadcrumbs it has many differences.Two main differences are

1. It uses a PageRenderRequestFilter instead of a dispatcher
2. It does not need an annotation in order to add pages to the trail

Features

• Configuration through contributions and annotations
• Dynamic breadcrumb titles
• Very flexible breadcrumbs trail component

Screenshot

Usage

Add the dependency to your POM:

<dependency>
  <groupId>org.oscy</groupId>
  <artifactId>tapestry-zbreadcrumbs</artifactId>
  <version>0.0.2</version>
</dependency>

Add the crumb trail component to your template:

<t:zcrumb.BreadCrumbsTrail />

Configuration

Module Configuration

Many properties of the module can be overridden by contributing to application defaults:

BreadCrumbs configuration

In many cases user needs to exclude a page from beeing added to the breadcrumbs list or even reset the whole list.There are two options to configure such operations:

1. Using annotations
2. Using contribution

Using annotations

Annotation BreadCrumb can be added on every page template you want to have control.The annotation has two properties:

• reset (Reset breadcrumbs list)
• ignore (Ignore page)
  

If both annotations are true it will first reset the list and then ignore the page

@BreadCrumb(ignore=true,reset=true)
public class Index {
}

Using contributions

By contributing to BreadCrumbsService you can control breadcrumb behavior on each page.Configuration though contribution, takes a list of BreadCrumbRule elements.Each BreadCrumbRule element contains a path pattern and a BreadCrumbAttribute (Ignore, Reset)

The mapping matches URLs using the following rules:

• ? matches one character
• * matches zero or more characters
• ** matches zero or more 'directories' in a path

Some examples:

• index - matches all index files in the root directory
• com/t?st - matches com/test but also com/tast or com/txst
• com/* - matches all files in the com directory
• com/**/test - matches all test files underneath the com path
• com/zenios/bread/**/* - matches all files underneath the com/zenios/bread path
• com/**/servlet/bla.jsp - matches com/zenios/bread/servlet/bla.jsp but also com/zenios/bread/testing/servlet/bla.jsp and com/servlet/bla.jsp

@BreadCrumb(ignore=true,reset=true)
public static void contributeBreadCrumbsService(Configuration<BreadCrumbRule> configuration) {
	configuration.add(new BreadCrumbRule("index",BreadCrumbAttribute.IGNORE));
	configuration.add(new BreadCrumbRule("index",BreadCrumbAttribute.RESET));
	configuration.add(new BreadCrumbRule("reports/*",BreadCrumbAttribute.IGNORE));
}

BreadCrumb titles

BreadCrumb titles are extracted using the following order

1. Using an event BreadCrumbsEventConstants.GET_TITLE. The component event handler will be passed the activation context
2. Using message catalogs
3. Using logical page name

Using an event

An event with name BreadCrumbsEventConstants.GET_TITLE will be triggered on the appropriate component. The component event handler will be passed the activationContext. The returned string, will be used as the page title

@OnEvent(value=BreadCrumbsEventConstants.GET_TITLE)
public String getBreadCrumbTitle(User user) {
	return user.getUsername();
}

Using message catalogs

If there is no event handler for the event mentioned above then the title will be retrieved from the components message catalog.The key for the message will be extracted from the logical page name and then append BreadCrumbsConstants.BREADCRUMBS_TITLE_SUFFIX

Index-crumb = Index page

Using logical page name

If there is no event handler and no message then the logical page name will be used as breadcrumb title

BreadCrumbs trail component

Breadcrumbs trail component, is the component responsible for rendering the list of breadcrubs.Main features of the component are

• Add block before each breadcrumb
• Add block after each breadcrumb
• Override the default breadcrumb block

public class testPage {
	@Property
	private BreadCrumbElement breadCrumb;
	
	@Property
	private int index;

	public String getCrumbClass() {
		return getTitle() + "-class";
	}

	public String getTitle() {
		return breadCrumb.getLogicalPageName();
	}
}

<t:zcrumb.BreadCrumbsTrail t:value="breadCrumb" t:index="index" t:class="literal:testclass" t:crumbClass="crumbClass">
	<p:before>
		${index}
	</p:before>
	<p:after>
		${index}
	</p:after>
	<p:inside>
		${title}
	</p:inside>
</t:zcrumb.BreadCrumbsTrail>	

Have in mind that by overridding the default breadCrumb block the methods for getting breadcrumb title mentioned above will not be used.You will be responsible for the rendering of the actual breadcrumb.