001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.wicket.extensions.breadcrumb; 018 019import java.util.List; 020 021import org.apache.wicket.extensions.breadcrumb.panel.BreadCrumbPanel; 022import org.apache.wicket.util.io.IClusterable; 023 024 025/** 026 * Bread crumbs provide a means to track certain history of client actions. Bread crumbs are 027 * typically rendered as a list of links, and are useful when users 'dig deeper' into the site 028 * structure so that they can find their way back again and have a notion of where they currently 029 * are. 030 * <p> 031 * Bread crumbs in the original sense just represent where people are in a site hierarchy. For 032 * example, when browsing a product site, bread crumbs could look like this: 033 * 034 * <pre> 035 * Home > Products & Solutions > Hardware > Desktop Systems 036 * </pre> 037 * 038 * or 039 * 040 * <pre> 041 * World > Europe > The Netherlands > Utrecht 042 * </pre> 043 * 044 * These items would be rendered as links to the corresponding site location. 045 * </p> 046 * Classes that implement this interface are responsible for managing such a bread crumb structure. 047 * A {@link BreadCrumbBar typical implementation} regards bread crumbs as a stack. When 048 * {@link #setActive(IBreadCrumbParticipant) a bread crumb is activated} that was not in the stack 049 * yet, it would add it to the stack, or when a bread crumb is activated that is already on the 050 * stack, it would roll back to the corresponding depth. 051 * <p> 052 * This model does not make any presumptions on how it should interact with components. Just that 053 * there is a list of {@link IBreadCrumbParticipant bread crumb participants}, and the notion of a 054 * currently active bread crumb participant. 055 * </p> 056 * <p> 057 * A {@link IBreadCrumbParticipant bread crumb participant} is not an actual bread crumb, but rather 058 * a proxy to components that represent a certain location relative to other bread crumbs in this 059 * model, and a means to get the bread crumb title, which is typically rendered as a link label of 060 * the actual bread crumb. The actual bread crumbs are supposed to be rendered by a component that 061 * works together with this model. I choose this model as this would suit what I think is one of the 062 * nicest patterns: {@link BreadCrumbPanel bread crumb aware panels}. 063 * </p> 064 * 065 * @author Eelco Hillenius 066 */ 067public interface IBreadCrumbModel extends IClusterable 068{ 069 /** 070 * Adds a bread crumb model listener. 071 * 072 * @param listener 073 * The listener to add 074 */ 075 void addListener(IBreadCrumbModelListener listener); 076 077 /** 078 * Lists the bread crumb participants in this model. 079 * 080 * @return The bread crumbs participants, as list with {@link IBreadCrumbParticipant bread crumb 081 * participants}. 082 */ 083 List<IBreadCrumbParticipant> allBreadCrumbParticipants(); 084 085 /** 086 * Gets the currently active participant, if any. 087 * 088 * @return The currently active participant, may be null 089 */ 090 IBreadCrumbParticipant getActive(); 091 092 /** 093 * Removes a bread crumb model listener. 094 * 095 * @param listener 096 * The listener to remove 097 */ 098 void removeListener(IBreadCrumbModelListener listener); 099 100 /** 101 * Sets the {@link IBreadCrumbParticipant bread crumb} as the active one. Implementations should 102 * call {@link IBreadCrumbModelListener#breadCrumbAdded(IBreadCrumbParticipant) bread crumb 103 * added} when the bread crumb was not yet part of the model, and 104 * {@link IBreadCrumbModelListener#breadCrumbRemoved(IBreadCrumbParticipant) bread crumb 105 * removed} for every crumb that was removed as the result of this call. 106 * 107 * @param breadCrumbParticipant 108 * The bread crump that should be set as the currently active 109 */ 110 void setActive(IBreadCrumbParticipant breadCrumbParticipant); 111}