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 &gt; Products &amp; Solutions &gt; Hardware &gt; Desktop Systems
036 * </pre>
037 * 
038 * or
039 * 
040 * <pre>
041 *          World &gt; Europe &gt; The Netherlands &gt; 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}